模块 http

http 模块还在开发中，如果有没有的功能请告知开发团队并先使用 curl 替代

• 函数原型
• 函数参数
  • 参数 url（必填）
  • 参数 headers
  • 参数 params
  • 参数 auth
  • 参数 body
  • 参数 json
  • 参数 form
• 返回 响应对象 Response
  • .url: str
  • .status_code: int 响应返回值
  • .headers: {[header_name: str]: header_values: [str]}
  • .body() -> str
  • .json() -> any
  • assert
• 虚拟 hostname

函数原型

目前提供了 http.get http.post http.put http.delete http.patch 五个方法，这几个可以接收的参数和返回值是完全相同的。

例如对于 get 而言，函数原型是 get(url: str, *, params: {[query_name: str]: query_value: str} = {}, headers: {[header_name: str]: header_value: <str / [str]>} = {}, body: str?, json: any?, form: {[query_name: str]: query_value: str} = {}, auth: (username: str, password: str)?) -> Response

函数参数

参数 url（必填）

要请求的 url，str 类型，例如 https://www.baidu.com

https 请求的证书目前是完全忽略的状态，即类似于 curl 中的 -k 始终被开启

参数 headers

要传递的请求 headers，类型为 dict，dict 的 key 为 request header name，类型为 str；value 的类型可以是 str 或 [str]，即传递 [str] 时会对生成多个同名的 request header

headers 参数为选填

因为类型是 dict，因此顺序是不被保证的，确实有需要按一定的顺序传递 headers 的需求请暂时使用 curl 并告知 ambot-script 开发团队

参数 params

要传递的 url query，类型为 Dict[str, str]，会合并入传入的 url 参数的 query string 部分

因为类型是 dict，因此顺序是不被保证的，确实有需要按一定的顺序传递 params 的需求请暂时使用 curl 并告知 ambot-script 开发团队

参数 auth

如果需要使用 basic 认证，可以传递 auth 参数。auth 参数为一个 Tuple[str, str]，元组的第一个元素为用户名、第二个元素为密码。

auth 参数用于生成 Basic Auth 的 Authorization headers，即例如传递 auth=("admin", "123456")，事实上等同于添加 Request Headers Authorization: Basic YWRtaW46MTIzNDU2

当前 auth 专为 basic auth 实现，因此如果有其他的认证需求请自行通过添加 headers 实现，对于比较常用的认证方式也可以联系 ambot-script 开发团队申请添加入 ambot-script http 标准库中

参数 body

用于传递请求 body，类型为 str，默认不会发送任何 body

body 参数的类型为 str，如果确实需要发送 bytes 数据可以直接考虑能否转换为 str，如果不能请暂时使用 curl 实现并告知 ambot-script 开发团队该场景的信息

参数 json

会对传递的数据进行 JSON encode 后作为 body 传送，理论上支持所有内置的数据类型。同时使用该项会设定 Content-Type 为 application/json

json 参数理论上支持所有内置的数据类型，如果出现问题请暂时手动转换为 dict 并告知 ambot-script 开发团队出现异常的类型信息

参数 form

会对传递的数据进行 percent encode，接收的参数类型是 Dict[str, str]，同时使用该项会设定 Content-Type 为 application/x-www-form-urlencoded

如需利用 form 上传文件，请使用 curl 实现；对于 multiparty/form-data 的实现在计划列表中

返回 响应对象 Response

http 的相关函数返回的都是 http.Response 对象

• url: str 原始请求 URL
• status_code: int 返回值
• headers 响应头
• body() -> str body 信息
• json() -> any body 信息，并进行 JSON decode

.url: str

等于 request 时的 url + params 的值

.status_code: int 响应返回值

一般我们认为返回值在 [200, 400) 的请求是成功的

在编写脚本的过程中，调用 request 方法后的第一件事应该就是判断 status_code，可以手动判断也可以利用 assert

.headers: {[header_name: str]: header_values: [str]}

headers 为服务器的响应头，key 为 header name，value 为 header value，注意 value 的类型是一个 list（因为可能存在同一个 headers 有多个返回值的情况）

.body() -> str

body 方法用于获得响应 body，返回值是 str 类型

.json() -> any

body 方法用于获得响应 body，并进行 JSON decode，返回 decode 以后的类型

assert

对于 response 进行 assert 等同于 assert(response.status_code >= 200, esponse.status_code < 400)

虚拟 hostname

虚拟 hostname 的功能的支持在 ambot-script engine v1.3 系中 v1.3.8 或更高版本、v1.4 系中 v1.4.0-rc.16 或更高版本添加

如果请求时的 host 域名以 .ambot 结尾，则会进行 ambot 虚拟 hostname 解析，具体规则请参考 core.resolve_domain