HTTPie的安装及使用
HTTPie(发音为aitch-tee-tee-pie)是一个命令行HTTP客户端。其目标是使与Web服务的CLI交互尽可能人性化。它提供了一个简单的http
命令,允许使用简单自然的语法发送任意HTTP请求,并显示彩色输出。HTTPie可用于测试,调试以及通常与HTTP服务器交互。
本文根据原文(https://httpie.org/doc) 进行了翻译,便于后面查询和使用。
主要特点
- 表达和直观的语法
- 格式化和彩色化的终端输出
- 内置JSON支持
- 表单和文件上传
- HTTPS,代理和身份验证
- 任意请求数据
- 自定义标题
- 持久的会议
- 类似Wget的下载
- Python 2.7和3.x支持
- Linux,macOS和Windows支持
- 插件
- 文档
- 测试覆盖率
一、安装
macOS苹果系统
在macOS上,HTTPie可以通过Homebrew安装 (推荐的):
$ brew install httpie
还提供MacPorts 端口:
$ port install httpie
Linux系统
大多数Linux发行版提供了可以使用系统包管理器安装的包,例如:
#Debian,Ubuntu等
$ apt-get install httpie
#Fedora的
$ dnf install httpie
#CentOS,RHEL,...
$ yum install httpie
#Arch Linux
$ pacman -S httpie
Windows系统
通用安装方法(适用于Windows,Mac OS X,Linux,...,并始终提供最新版本)是使用pip:
#确保我们有最新版本的pip和setuptools:
$ pip install --upgrade pip setuptools
$ pip install --upgrade httpie
(如果pip
由于某种原因安装失败,您可以尝试 easy_install httpie
作为后备。)
Python版本
虽然也支持Python 2.7,但强烈建议尽可能针对最新的Python 3.x安装HTTPie。这将确保一些较新的HTTP功能,如SNI(服务器名称指示),开箱即用。从版本0.9.4开始,Python 3是Homebrew安装的默认设置。要查看HTTPie使用的版本,请运行http --debug
。
不稳定的版本
您也可以直接从master
GitHub上的分支安装最新的未发布的开发版本。这是未来稳定发布的一项工作,因此体验可能不那么顺利。
在macOS上,您可以使用Homebrew安装它:
$ brew install httpie --HEAD
否则pip
:
$ pip install --upgrade https://github.com/jakubroztocil/httpie/archive/master.tar.gz
验证现在我们有 当前的开发版本标识符 带-dev
后缀,例如:
$ http --version
1.0.0-dev
用法
Hello World:
$ http httpie.org
语法:
$ http [ flags ] [ METHOD ]网址[ ITEM [ ITEM ]]
另见http --help
。
例子
$ http PUT example.org X-API-Token:123 name=John
提交表格:
$ http -f POST example.org hello=World
请参阅使用以下输出选项之一发送的请求:
$ http -v example.org
使用Github API发布对问题的评论与认证:
$ http -a USERNAME POST https://api.github.com/repos/jakubroztocil/httpie/issues/83/comments body='HTTPie is awesome! :heart:'
使用重定向输入上传文件:
$ http example.org < file.json
下载文件并通过重定向输出保存:
$ http example.org/file > file
下载文件wget
样式:
$ http --download example.org/file
使用命名会话在对同一主机的请求之间建立某些方面或通信持久性:
$ http --session=logged-in -a username:password httpbin.org/get API-Key:123
$ http --session=logged-in httpbin.org/headers
设置自定义Host
标头以解决丢失的DNS记录:
$ http localhost:8000 Host:example.com
HTTP方法
HTTP方法的名称就在URL参数之前:
$ http DELETE example.org/todos/7
看起来类似于发送的实际Request-Line
内容:
DELETE /todos/7 HTTP/1.1
当METHOD
从命令中省略参数时,HTTPie默认为GET
(没有请求数据)或POST
(带有请求数据)。
请求网址
HTTPie执行请求所需的唯一信息是URL。默认http://
可以从参数中省略 http example.org
工作得很好。
查询字符串参数
如果您发现自己在终端上手动构建带有查询字符串参数的URL,您可能会欣赏param==value
附加URL参数的语法。有了它,您不必担心转义&
shell 的分隔符。此外,参数值中的特殊字符也将自动转义(HTTPie否则要求URL已被转义)。要HTTPie logo
在Google图片上搜索,您可以使用以下命令:
$ http www.google.com search=='HTTPie logo' tbm==isch
GET /?search=HTTPie+logo&tbm=isch HTTP/1.1
用于localhost
的URL快捷方式
此外,支持localhost的类似curl的简写。这意味着,例如,:3000
将扩展为http://localhost:3000
如果省略端口,则假定端口80。
$ http :/foo
GET /foo HTTP/1.1
Host: localhost
$ http :3000/bar
GET /bar HTTP/1.1
Host: localhost:3000
$ http :
GET / HTTP/1.1
Host: localhost
自定义默认方案
您可以使用--default-scheme <URL_SCHEME>
该选项为除HTTP之外的其他协议创建快捷方式:
$ alias https='http --default-scheme=https'
请求项
有一些不同的请求项类型提供了一种方便的机制来指定HTTP标头,简单的JSON和表单数据,文件和URL参数。
它们是URL后指定的键/值对。在共同所有的优点是它们成为被发送的实际请求的一部分,他们的类型由使用的分隔符来分辨: :
,=
,:=
,==
,@
,=@
,和:=@
。用的那些 @
期望的那样值的文件路径。
请求类型 | 描述 |
---|---|
HTTP头 Name:Value
|
任意HTTP标头,例如X-API-Token:123 。 |
URL参数 name==value
|
将给定的名称/值对作为查询字符串参数附加到URL。使用== 分隔符。 |
数据字段 field=value , field=@file.txt
|
请求将数据字段序列化为JSON对象(默认),或者进行表单编码(--form, -f )。 |
原始JSON字段 field:=json , field:=@file.json
|
有用的发送JSON和一个或多个字段需要一个时Boolean ,Number 嵌套Object ,或者Array ,例如,meals:='["ham","spam"]' 或pies:=[1,2,3] (注意引号)。 |
表单文件字段 field@/dir/file
|
仅适用于--form, -f 。例如screenshot@~/Pictures/img.png 。文件字段的存在会导致multipart/form-data 请求。 |
请注意,数据字段不是指定请求数据的唯一方法: 重定向输入是一种传递任意请求数据的机制。
转义规则
您可以使用\
转义不应用作分隔符(或其部分)的字符。例如,foo\==bar
将成为数据键/值对(foo=
和bar
)而不是URL参数。
通常有必要引用这些值,例如foo='bar baz'
。
如果任何字段名称或标题以减号(例如-fieldname
)开头,则需要将所有此类项目放在特殊标记之后,--
以防止与--arguments
以下内容混淆:
$ http httpbin.org/post -- -name-starting-with-dash=foo -Unusual-Header:bar
POST /post HTTP/1.1
-Unusual-Header: bar
Content-Type: application/json
{
"-name-starting-with-dash": "foo"
}
JSON
JSON是现代Web服务的通用语言,它也是HTTPie默认使用的 隐式内容类型。
简单的例子:
$ http PUT example.org name=John email=john@example.org
PUT / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Content-Type: application/json
Host: example.org
{
"name": "John",
"email": "john@example.org"
}
默认行为
如果您的命令包含一些数据请求项,则默认情况下将它们序列化为JSON对象。HTTPie还会自动设置以下标头,这两个标头都可以被覆盖:
Content-Type |
application/json |
---|---|
Accept |
application/json, */* |
显式JSON
无论您是否正在发送数据 ,都可以使用--json, -j
显式设置(这是通过常用标题符号设置标题的快捷方式:) 。此外,即使错误或未知,HTTPie也会尝试检测JSON响应 。Accept
`application/jsonhttp url Accept:'application/json, */*'
Content-Type`text/plain
非字符串JSON字段
非字符串字段使用:=
分隔符,允许您将原始JSON嵌入到结果对象中。文本和原始JSON文件也可以使用=@
和嵌入到字段中:=@
:
$ http PUT api.example.com/person/1 \
name=John \
age:=29 married:=false hobbies:='["http", "pies"]' \ # Raw JSON
description=@about-john.txt \ # Embed text file
bookmarks:=@bookmarks.json # Embed JSON file
PUT /person/1 HTTP/1.1
Accept: application/json, */*
Content-Type: application/json
Host: api.example.com
{
"age": 29,
"hobbies": [
"http",
"pies"
],
"description": "John is a nice guy who likes pies.",
"married": false,
"name": "John",
"bookmarks": {
"HTTPie": "http://httpie.org",
}
}
请注意,使用此语法时,命令在发送复杂数据时会变得难以处理。在这种情况下,使用重定向输入总是更好:
$ http POST api.example.com/person/1 < person.json
表单
提交表单与发送JSON请求非常相似。通常唯一的区别是添加--form, -f
选项,这确保数据字段被序列化为,并Content-Type
设置为, application/x-www-form-urlencoded; charset=utf-8
。可以通过配置文件使表单数据成为隐式内容类型而不是JSON 。
常规表单
$ http --form POST api.example.org/person/1 name='John Smith'
POST /person/1 HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
name=John+Smith
文件上传表单
如果存在一个或多个文件字段,则序列化和内容类型为 multipart/form-data
:
$ http -f POST example.com/jobs name='John Smith' cv@~/Documents/cv.pdf
上面的请求与提交以下HTML表单的请求相同:
<form enctype="multipart/form-data" method="post" action="http://example.com/jobs">
<input type="text" name="name" />
<input type="file" name="cv" />
</form>
请注意,@
它用于模拟文件上载表单字段,而 =@
只是将文件内容嵌入为常规文本字段值。
HTTP头
要设置自定义头,您可以使用以下Header:Value
表示法:
$ http example.org User-Agent:Bacon/1.0 'Cookie:valued-visitor=yes;foo=bar' \
X-Foo:Bar Referer:http://httpie.org/
GET / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Cookie: valued-visitor=yes;foo=bar
Host: example.org
Referer: http://httpie.org/
User-Agent: Bacon/1.0
X-Foo: Bar
默认请求标头
HTTPie设置了几个默认标头:
ET / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
User-Agent: HTTPie/<version>
Host: <taken-from-URL>
除了Host
可以覆盖其中任何一个,其中一些未设置。
空标题和标题取消设置
要取消设置先前指定的标头(例如默认标头之一),请使用Header:
:
$ http httpbin.org/headers Accept: User-Agent:
要发送包含空值的标头,请使用Header;
:
$ http httpbin.org/headers 'Header;'
cookies
HTTP客户端将cookie作为常规HTTP标头发送到服务器。这意味着,HTTPie不提供任何指定cookie的特殊语法 - 使用通常的 Header:Value
表示法:
发送一个cookie:
$ http example.org Cookie:sessionid=foo
GET / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Cookie: sessionid=foo
Host: example.org
User-Agent: HTTPie/0.9.9
发送多个cookie(注意引用标题以防止shell解释;
):
$ http example.org 'Cookie:sessionid=foo;another-cookie=bar'
GET / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Cookie: sessionid=foo;another-cookie=bar
Host: example.org
User-Agent: HTTPie/0.9.9
如果您经常在请求中处理cookie,那么您很可能会欣赏会话功能。
认证
当前支持的身份验证方案是Basic和Digest(有关更多信息,请参阅auth plugins)。有两个控制身份验证的标志:
--auth, -a |
传递一username:password 对作为参数。或者,如果您只指定用户名(-a username ),则会在发送请求之前提示您输入密码。要发送空密码,请传递username: 。该username:password@hostname URL语法,以及支持(但可通过传递凭据-a 具有更高的优先级)。 |
---|---|
--auth-type, -A |
指定身份验证机制。可能的值是 basic 和digest 。默认值是basic 经常可以省略的。 |
基本认证
$ http -a username:password example.org
摘要认证
$ http -A digest -a username:password example.org
密码提示
$ http -a username example.org
.netrc
您的~/.netrc
文件中的身份验证信息也受到尊重:
$ cat ~/.netrc
machine httpbin.org
login httpie
password test
$ http httpbin.org/basic-auth/httpie/test
HTTP/1.1 200 OK
[...]
Auth插件
可以将其他身份验证机制安装为插件。它们可以在Python Package Index中找到。这里有几个选择:
- httpie-api-auth: ApiAuth
- httpie-aws-auth: AWS / Amazon S3
- httpie-edgegrid: EdgeGrid
- httpie-hmac-auth: HMAC
- httpie-jwt-auth: JWTAuth (JSON Web Tokens)
- httpie-negotiate: SPNEGO (GSS Negotiate)
- httpie-ntlm: NTLM (NT LAN Manager)
- httpie-oauth: OAuth
- requests-hawk: Hawk
HTTP重定向
默认情况下,不会遵循HTTP重定向,只显示第一个响应:
$ http httpbin.org/redirect/3
跟随 Location
要指示HTTPie遵循响应Location
标头30x
并显示最终响应,请使用以下--follow, -F
选项:
$ http --follow httpbin.org/redirect/3
显示中间重定向响应
如果您还希望查看中间请求/响应,那么也可以使用该--all
选项:
$ http --follow --all httpbin.org/redirect/3
限制了最大重定向
要更改最大30
重定向的默认限制,请使用以下 --max-redirects=<limit>
选项:
$ http --follow --all --max-redirects=5 httpbin.org/redirect/3
代理
您可以通过--proxy
每个协议的参数指定要使用的代理(在跨协议重定向的情况下包含在值中):
$ http --proxy=http:http://10.10.1.10:3128 --proxy=https:https://10.10.1.10:1080 example.org
使用基本认证:
$ http --proxy=http:http://user:pass@10.10.1.10:3128 example.org
环境变量
您也可以通过配置环境变量代理HTTP_PROXY
和 HTTPS_PROXY
,和底层的请求图书馆将它们捡起来为好。如果要禁用通过某些主机的环境变量配置的代理,可以在中指定它们NO_PROXY
。
在你的~/.bash_profile
:
export HTTP_PROXY=http://10.10.1.10:3128
export HTTPS_PROXY=https://10.10.1.10:1080
export NO_PROXY=localhost,example.com
SOCKS
Homebrew安装的HTTPie开箱即用SOCKS代理支持。要为非Homebrew安装启用SOCKS代理支持,您需要requests[socks]
使用pip
以下方法手动安装:
$ pip install -U requests[socks]
用法与其他类型的代理相同:
$ http --proxy=http:socks5://user:pass@host:port --proxy=https:socks5://user:pass@host:port example.org
HTTPS
服务器SSL证书验证
要跳过主机的SSL证书验证,您可以传递--verify=no
(默认为yes
):
$ http --verify=no https://example.org
自定义CA捆绑
您还可以使用--verify=<CA_BUNDLE_PATH>
设置自定义CA捆绑包路径:
$ http --verify=/ssl/custom_ca_bundle https://example.org
客户端SSL证书
要使用客户端证书进行SSL通信,可以使用以下命令传递cert文件的路径--cert
:
$ http --cert=client.pem https://example.org
如果私钥未包含在cert文件中,您可以通过以下方式传递密钥文件的路径--cert-key
:
$ http --cert=client.crt --cert-key=client.key https://example.org
SSL版本
使用--ssl=<PROTOCOL>
指定要使用的协议版本。这将默认为SSL v2.3,它将协商服务器和OpenSSL安装支持的最高协议。可用的协议都ssl2.3
,ssl3
,tls1
,tls1.1
,tls1.2
,tls1.3
。(实际可用的协议集可能因OpenSSL安装而异。)
#指定易受攻击的SSL v3协议与过时的服务器通信:
$ http --ssl=ssl3 https://vulnerable.example.org
SNI(服务器名称指示)
如果您使用HTTPie 低于2.7.9的Python版本(可以验证http --debug
)并且需要与使用SNI(服务器名称指示)的服务器通信,则需要安装一些其他依赖项:
$ pip install --upgrade requests[security]
您可以使用以下命令测试SNI支持:
$ http https://sni.velox.ch
输出选项
默认情况下,HTTPie仅输出最终响应,并打印整个响应消息(标题和正文)。您可以通过以下几个选项控制应该打印的内容:
选项 | 意义 |
---|---|
--headers, -h |
仅打印响应标头。 |
--body, -b |
仅打印响应正文。 |
--verbose, -v |
打印整个HTTP交换(请求和响应)。此选项也可启用--all (见下文)。 |
--print, -p |
选择HTTP交换的部分。 |
--verbose
通常可用于调试请求和生成文档示例:
$ http --verbose PUT httpbin.org/put hello=world
PUT /put HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Content-Type: application/json
Host: httpbin.org
User-Agent: HTTPie/0.2.7dev
{
"hello": "world"
}
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 477
Content-Type: application/json
Date: Sun, 05 Aug 2012 00:25:23 GMT
Server: gunicorn/0.13.4
{
[…]
}
应该打印HTTP交换的哪些部分
所有其他输出选项都在引擎盖下,只是更强大的快捷方式--print, -p
。它接受一个字符串,每个字符代表HTTP交换的特定部分:
字符 | 代表 |
---|---|
H |
请求标头 |
B |
请求机构 |
h |
响应标头 |
b |
回应机构 |
打印请求和响应标头:
$ http --print=Hh PUT httpbin.org/put hello=world
查看中间请求/响应
要查看所有HTTP通信,即最终请求/响应以及任何可能的中间请求/响应,请使用该--all
选项。中间HTTP通信包括重定向(with --follow
),使用HTTP摘要认证时的第一个未授权请求(--auth=digest
)等。
#包括导致最终答案的所有回复:
$ http --all --follow httpbin.org/redirect/3
默认情况下,中间请求/响应根据--print, -p
(及其上述快捷方式)进行格式化 。如果您想更改它,请使用该--history-print, -P
选项。它采用相同的参数,--print, -p
但仅适用于中间请求。
#打印中间请求/响应的方式不同于最后一个:
$ http -A digest -a foo:bar --all -p Hh -P H httpbin.org/digest-auth/auth/foo/bar
有条件的主体下载
作为优化,仅当响应主体是输出的一部分时才从服务器下载响应主体。这与执行HEAD
请求类似,不同之处在于它适用于您使用的任何HTTP方法。
假设有一个API在更新时返回整个资源,但您只对响应标头感兴趣,以便在更新后查看状态代码:
$ http --headers PATCH example.org/Really-Huge-Resource name='New Name'
由于我们仅在此处打印HTTP标头,因此只要收到所有响应标头,就会关闭与服务器的连接。因此,带宽和时间不会浪费下载您不关心的主体。始终下载响应标头,即使它们不是输出的一部分
重定向输入
传递请求数据的通用方法是通过重定向stdin
(标准输入) - 管道。这些数据被缓冲,然后没有进一步处理用作请求主体。使用管道有多种有用的方法:
从文件重定向:
$ http PUT example.com/person/1 X-API-Token:123 < person.json
或者另一个程序的输出:
$ grep '401 Unauthorized' /var/log/httpd/error_log | http POST example.org/intruders
您可以使用echo
简单数据:
$ echo '{"name": "John"}' | http PATCH example.com/person/1 X-API-Token:123
您甚至可以使用HTTPie将Web服务连接在一起:
$ http GET https://api.github.com/repos/jakubroztocil/httpie | http POST httpbin.org/post
您可以使用cat
在终端上输入多行数据:
$ cat | http POST example.com
<paste>
^D
$ cat | http POST example.com/todos Content-Type:text/plain
- buy milk
- call parents
^D
在OS X上,您可以使用以下命令发送剪贴板的内容pbpaste
:
$ pbpaste | http PUT example.com
传递数据stdin
不能与命令行中指定的数据字段组合:
$ echo 'data' | http POST example.org more=data #这是无效的
要防止HTTPie读取stdin
数据,您可以使用该 --ignore-stdin
选项。
从文件名中请求数据
重定向的替代方法stdin
是指定文件名(as @/path/to/file
),其内容的使用方式与其来源相同stdin
。
它的优点Content-Type
是根据文件扩展名自动将标头设置为适当的值。例如,以下请求发送该XML文件的逐字内容Content-Type: application/xml
:
$ http PUT httpbin.org/put @/data/file.xml
终端输出
HTTPie默认做了几件事,以使其终端输出易于阅读。
颜色和格式
语法突出显示应用于HTTP标头和正文(有意义的地方)。--style
如果您不喜欢默认颜色方案,可以通过该选项选择首选颜色方案(请参阅$ http --help
可能的值)。
此外,应用以下格式:
- HTTP标头按名称排序。
- JSON数据是缩进的,按键排序,unicode转义转换为它们代表的字符。
其中一个选项可用于控制输出处理:
--pretty=all |
应用颜色和格式。终端输出的默认值。 |
---|---|
--pretty=colors |
应用颜色。 |
--pretty=format |
应用格式。 |
--pretty=none |
禁用输出处理。重定向输出的默认值。 |
二进制数据
终端输出禁止二进制数据,这样可以安全地对发送回二进制数据的URL执行请求。二进制数据在重定向时也被抑制,但是被美化输出。一旦我们知道响应主体是二进制的,连接就会关闭
$ http example.org/Movie.mov
你几乎可以立即看到这样的东西:
HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Encoding: gzip
Content-Type: video/quicktime
Transfer-Encoding: chunked
+-----------------------------------------+
| NOTE: binary data not shown in terminal |
+-----------------------------------------+
重定向输出
HTTPie对重定向输出使用一组不同的默认值,而不是 终端输出。差异是:
- 不应用格式和颜色(除非
--pretty
指定)。 - 仅打印响应正文(除非设置了其中一个输出选项)。
- 此外,不抑制二进制数据。
原因是将HTTPie的管道输出到另一个程序,下载文件没有额外的标志。大多数情况下,当重定向输出时,只有原始响应体才有意义。
下载文件:
$ http example.org/Movie.mov > Movie.mov
下载Octocat的图像,使用ImageMagick调整大小,将其上传到其他地方:
$ http octodex.github.com/images/original.jpg | convert - -resize 25% - | http example.org/Octocats
强制着色和格式化,并在less
寻呼机中显示请求和响应 :
$ http --pretty=all --verbose example.org | less -R
该-R
标志告诉less
我们解释包含HTTPie输出的颜色转义序列。
您可以通过将以下内容添加到以下内容来创建用于调用带有彩色和分页输出的HTTPie的快捷方式~/.bash_profile
:
function httpless {
# `httpless example.org'
http --pretty=all --print=hb "$@" | less -R;
}
下载模式
HTTPie具有下载模式,其行为类似于wget
。
使用该--download, -d
标志启用时,响应标头将打印到终端(stderr
),并在响应正文保存到文件时显示进度条。
$ http --download https://github.com/jakubroztocil/httpie/archive/master.tar.gz
HTTP/1.1 200 OK
Content-Disposition: attachment; filename=httpie-master.tar.gz
Content-Length: 257336
Content-Type: application/x-gzip
Downloading 251.30 kB to "httpie-master.tar.gz"
Done. 251.30 kB in 2.73862s (91.76 kB/s)
下载的文件名
如果未提供via --output, -o
,则输出文件名将由Content-Disposition
(如果可用)或URL和 Content-Type
。如果猜测的文件名已经存在,HTTPie会为其添加一个唯一的后缀。
下载时管道
您还可以将响应正文重定向到另一个程序,同时响应标头和进度仍显示在终端中:
$ http -d https://github.com/jakubroztocil/httpie/archive/master.tar.gz | tar zxf -
恢复下载
如果--output, -o
已指定,则可以使用该--continue, -c
选项恢复部分下载 。这仅适用于支持Range
请求和206 Partial Content
响应的服务器 。如果服务器不支持,则只需下载整个文件:
$ http -dco file.zip example.org/file
其他说明
- 该
--download
选项仅更改响应正文的处理方式。 - 您仍然可以设置自定义标头,使用会话
--verbose, -v
等。 -
--download
总是暗示--follow
(遵循重定向)。 -
1
如果主体尚未完全下载,HTTPie将退出状态代码(错误)。 -
Accept-Encoding
无法设置--download
。
流式响应
响应下载并以块的形式打印,允许在不使用太多内存的情况下进行流式传输和大型文件下载。但是,当应用 颜色和格式时,整个响应将被缓冲,然后立即处理。
禁用缓冲
您可以使用该--stream, -S
标志来发生两件事:
输出在更小的块中刷新而没有任何缓冲,这使得HTTPie的行为类似于tail -f
URL。即使输出被美化,流也会启用:它将应用于响应的每一行并立即刷新。这样就可以为长期存在的请求提供一个很好的输出,例如一个Twitter流API。
示例用例
Prettified流媒体响应:
$ http --stream -f -a YOUR-TWITTER-NAME https://stream.twitter.com/1/statuses/filter.json track='Justin Bieber'
通过小块流输出tail -f
:
# Send each new tweet (JSON object) mentioning "Apple" to another
# server as soon as it arrives from the Twitter streaming API:
$ http --stream -f -a YOUR-TWITTER-NAME https://stream.twitter.com/1/statuses/filter.json track=Apple \
| while read tweet; do echo "$tweet" | http POST example.org/tweets ; done
会话
默认情况下,HTTPie发出的每个请求都完全独立于同一主机的任何先前请求。
但是,HTTPie还通过该--session=SESSION_NAME_OR_PATH
选项支持持久会话。在会话中,自定义HTTP标头(以Content-
或开头的标头除外If-
), 身份验证和cookie (由服务器手动指定或发送)在对同一主机的请求之间保持不变。
#创建一个新会话
$ http --session=/tmp/session.json example.org API-Token:123
#重新使用现有会话 - 将设置API-Token:
$ http --session=/tmp/session.json example.org
所有会话数据(包括凭据,cookie数据和自定义标头)都以纯文本格式存储。这意味着还可以在文本编辑器中手动创建和编辑会话文件 - 它们是常规JSON。这也意味着任何有权访问会话文件的人都可以阅读它们。
命名会话
您可以为每个主机创建一个或多个命名会话。例如,这是你可以创建一个名为新的会话user1
为example.org
:
$ http --session=user1 -a user1:password example.org X-Foo:Bar
从现在开始,您可以通过名称来引用会话。当您选择再次使用会话时,将自动设置任何以前指定的身份验证或HTTP标头:
$ http --session=user1 example.org
要创建或重用其他会话,只需指定其他名称:
$ http --session=user2 -a user2:password example.org X-Bar:Foo
命名会话的数据存储在目录中的JSON文件中 ~/.httpie/sessions/<host>/<name>.json
(%APPDATA%\httpie\sessions\<host>\<name>.json
在Windows上)。
匿名会话
您也可以直接指定会话文件的路径,而不是名称。这允许跨多个主机重用会话:
$ http --session=/tmp/session.json example.org
$ http --session=/tmp/session.json admin.example.org
$ http --session=~/.httpie/sessions/another.example.org/test.json example.org
$ http --session-read-only=/tmp/session.json example.org
只读会话
要在创建现有会话文件而不从请求/响应交换中更新它,请通过相应的方式指定会话名称 --session-read-only=SESSION_NAME_OR_PATH
。
配置
HTTPie使用简单的JSON配置文件。
配置文件位置
配置文件的默认位置是~/.httpie/config.json
(或%APPDATA%\httpie\config.json
在Windows上)。可以通过设置HTTPIE_CONFIG_DIR
环境变量来更改config目录位置。查看确切的位置运行http --debug
。
可配置选项
JSON文件包含具有以下键的对象:
default_options
一个Array
(默认为空)默认选项,应该应用于每次HTTPie调用。
例如,您可以使用此选项更改默认样式和输出选项:"default_options": ["--style=fruity", "--body"]
另一个有用的默认选项可能是"--session=default"
使HTTPie始终使用会话(default
将自动使用一个名称)。或者,您可以通过添加--form
到列表将隐式请求内容类型从JSON更改为表单。
__meta__
HTTPie在此自动存储其部分元数据。请不要改变。
取消设置先前指定的选项
可以--no-OPTION
通过命令行传递的参数(例如,--no-style
或--no-session
)为特定调用取消设置配置文件中的默认选项,或以任何其他方式指定。
脚本
从shell脚本使用HTTPie时,设置--check-status
标志会很方便 。它指示HTTPie一个错误退出,如果HTTP状态之一3xx
,4xx
或5xx
。退出状态将分别为3
(除非--follow
已设置)4
,或5
。
#!/bin/bash
if http --check-status --ignore-stdin --timeout=2.5 HEAD example.org/health &> /dev/null; then
echo 'OK!'
else
case $? in
2) echo 'Request timed out!' ;;
3) echo 'Unexpected HTTP 3xx Redirection!' ;;
4) echo 'HTTP 4xx Client Error!' ;;
5) echo 'HTTP 5xx Server Error!' ;;
6) echo 'Exceeded --max-redirects=<n> redirects!' ;;
*) echo 'Other Error!' ;;
esac
fi
最佳做法
stdin
在非交互式调用期间,通常不需要自动读取的默认行为。您很可能希望使用该--ignore-stdin
选项来禁用它。
如果没有这个选项,HTTPie似乎会挂起,这是一个常见的问题。发生的情况是,例如从cron作业调用HTTPie时,stdin
未连接到终端。因此,重定向输入的规则适用,即HTTPie开始读取它,期望请求体将被传递。而且既然没有数据也不会EOF
,它会被卡住。因此,除非您将一些数据传递给HTTPie,否则应在脚本中使用此标志。
此外,最好将默认30
秒覆盖--timeout
到适合您的东西。
元素
界面设计
命令参数的语法与通过线路发送的实际HTTP请求密切对应。它的优点是易于记忆和阅读。通常可以通过内联请求元素将HTTP请求转换为HTTPie参数列表。例如,比较此HTTP请求:
POST /collection HTTP/1.1
X-API-Key: 123
User-Agent: Bacon/1.0
Content-Type: application/x-www-form-urlencoded
name=value&name2=value2
使用发送它的HTTPie命令:
$ http -f POST example.org/collection \
X-API-Key:123 \
User-Agent:Bacon/1.0 \
name=value \
name2=value2
请注意,元素的顺序和语法都非常相似,并且只有一小部分命令用于控制HTTPie,并且不直接对应于请求的任何部分(这里只是-f
要求HTTPie发送表单)请求)。
这两种模式--pretty=all
(默认为终端)和--pretty=none
(默认为重定向输出)允许用户友好的交互式使用和脚本使用,其中HTTPie用作通用HTTP客户端。
由于HTTPie仍在大力开发中,现有的命令行语法和一些--OPTIONS
可能会在HTTPie到达其最终版本之前稍微改变1.0
。所有更改都记录在 更改日志中。
用户支持
请使用以下支持渠道:
- GitHub问题 用于错误报告和功能请求。
- 我们的Gitter聊天室 提出问题,讨论功能,以及进行一般性讨论。
- 堆栈溢出 提问(请务必使用 httpie 标签)。
- 直接转发给@clihttp。
- 你也可以直接发推文给@jakubroztocil。
相关项目
依赖
在引擎盖下,HTTPie使用这两个惊人的库:
- 要求 - 适用于人类的Python HTTP库
- Pygments来做 - Python语法荧光笔
HTTPie的朋友
HTTPie使用以下工具非常好地运行:
备择方案
特约
请参阅CONTRIBUTING.rst。
更改日志
艺术品
执照
BSD-3-Clause:LICENSE。
作者
Jakub Roztocil (@jakubroztocil)创建了HTTPie,这些优秀人才 做出了贡献。