http.put()

在此页面上

定义

使用
例子
参数
返回值
规则模板
用户只能向特定主机发送请求
请求 URL 必须包含特定查询参数
请求正文必须包含特定字段
请求正文必须包含具有特定值的字段

Atlas Device Sync 、 Atlas Edge Server 、 Data API和HTTPS endpoints均已弃用。有关详细信息，请参阅弃用页面。

定义

http.put()

发送HTTP PUT 使用URL 向指定Atlas App ServicesHTTP Service 请求。

使用

例子

注意

此示例假设您已配置名为 "myHttp" 的HTTP Service 。如果不需要使用服务规则验证此HTTP动作，则可以使用发送HTTP请求 ( context.http )模块。

exports = function() {
  const http = context.services.get("myHttp");
  return http.put({
    url: "https://www.example.com/messages",
    body: { msg: "This is in the body of a PUT request!" },
    encodeBodyAsJSON: true
  })
  .then(response => {
    // The response body is encoded as raw BSON.Binary. Parse it to JSON.
    const ejson_body = EJSON.parse(response.body.text());
    return ejson_body;
  })
};

参数

http.put() 操作接受以下形式的一个参数：

{
    "url": <string>,
    "headers": <document>,
    "body": <string>,
    "form": <document>,
    "cookies": <string>,
    "authUrl": <string>,
    "followRedirects": <boolean>
}

字段

说明

Request URL

url: <string>

必需。 HTTP请求的目标URL 。或者，您可以将URL的组件指定为根级字段。请参阅备用URL参数。

Request Body

body: <string>

必需。 HTTP 请求的字符串化正文。如果请求有效负载的内容类型为multipart/form-data ，请使用form参数而不是body 。

Form Request Body

form: <document>

每个字段都映射到 multipart/form-data 请求中的字段的文档。您不能将此参数与 body 参数同时使用。

注意

使用 form 参数的请求还应包含 Content-Type: multipart/form-data 标头。

例子

"form": {
  "to-address": "name@example.com",
  "from-address": "other-name@example.com",
  "subject": "test subject please ignore",
  "message-body": "hello from the message body"
}

Request Headers

headers: <document>

可选。一种文档，其中每个字段名称对应一种 HTTP 标头，每个字段值都是该标头的一个或多个字符串值的数组。

例子

{
  "Content-Type": [ "application/json" ]
}

Request Cookies

cookies: <document>

可选。一个文档，其中每个字段名称对应一个 cookie 名称，每个字段值都是该 cookie 的字符串值。

例子

{
  "favoriteTeam": "Chicago Cubs"
}

Digest Authentication

digestAuth: <boolean>

可选。如果true ，则App Services使用摘要式身份验证验证对请求进行身份验证。您必须指定username和password （作为请求文档中的字段或作为URL的一部分）才能使用摘要式身份验证。有关更多详细信息，请参阅请求身份验证。

Request Authentication URL

authUrl: <string>

可选。一个返回 HTTP 请求的授权 Cookie 的 URL。

Follow Redirects

followRedirects: <boolean>

可选。如果为 true，则请求将遵循它收到的目标 URL 的任何 HTTP 重定向。

备用 URL 参数

如果需要指定请求目标 URL 的各个组件，请省略 url 字段并将组件指定为根级字段。以下 URL 组件字段可用：

<scheme>://<host>/<path>?<query>#<fragment>

{
   "scheme": <string>,
   "host": <string>,
   "path": <string>,
   "query": <document>,
   "fragment": <string>,
   "username": <string>,
   "password": <string>
}

名称

scheme

Optional. Default: "http".

Valid options: https, http

URL 模式。

例子

// https://www.example.com/
{ scheme: "https" }

host

Required.

目标资源的主机名。

例子

// https://www.example.com/
{ host: "www.example.com" }

path

Optional.

目标资源的路径。

例子

// https://www.example.com/api/v1/users
{ path: "/api/v1/users" }

query

Optional.

一种文档，其中每个字段都映射到 URL 查询字符串中的一个参数。每个字段的值都是一个字符串数组，其中包含参数的所有参数值。

例子

// https://www.example.com/?id=8675309&color=red&color=blue
{
  query: {
    "id": ["8675309"],
    "color": ["red", "blue"]
  }
}

fragment

Optional.

URL 片段。URL 的这一部分包括哈希 (#) 符号之后的所有内容。

例子

// https://www.example.com/?id=8675309#someFragment
{ fragment: "someFragment" }

username

Optional.

用于对请求进行身份验证的用户名。用户通常将此参数与 password 参数一起使用。

password

Optional.

用于验证请求的密码。密码应与 username 参数中指定的用户相对应。

返回值

http.put() 操作会返回 promise，可以解析为具有以下形式的文档：

{
   "status": <string>,
   "statusCode": <integer>,
   "contentLength": <integer>,
   "headers": <document>,
   "cookies": <array>,
   "body": <binary>
}

字段

类型

说明

status

字符串

HTTP 请求状态消息。

statusCode

整型

HTTP 请求状态代码。

contentLength

整型

响应 body 中返回的字节数。

headers

文档

一种文档，其中每个字段名称对应一种 HTTP 标头，每个字段值都是该标头的一个或多个字符串值的数组。

例子

{
  "Content-Type": [ "application/json" ]
}

cookies

文档

一种文档，其中每个字段名称对应一个 cookie 名称，每个字段值都是该 cookie 的字符串值。

例子

{
  "favoriteTeam": "Chicago Cubs"
}

body

二进制文件

HTTP 响应的二进制编码正文。

请求身份验证

您可以使用标准 HTTP 身份验证方案之一对出站 HTTP 请求进行身份验证。Atlas App Services 支持以下身份验证方案：

基本身份验证

HTTP 基本身份验证要求传入请求包含所请求服务的有效用户名和密码。您可以在请求文档的和字段中、直接在usernamepasswordurlstring 中或在授权HTTP 标头。

例子

以下示例演示使用基本身份验证对 HTTP 服务请求进行身份验证的三种等效方法。这些示例均使用用户名 MyUser 和密码 Mypassw0rd。您可以将这些对象之一作为参数传递给给定的 HTTP 方法。

直接指定凭证（最佳方法）

{
  "scheme": "https",
  "username": "MyUser",
  "password": "Mypassw0rd",
  "domain": "www.example.com"
}

在 URL 中嵌入凭证

{
  "url": "https://MyUser:Mypassw0rd@www.example.com"
}

包括授权标头

{
  "url": "https://www.example.com",
  "headers": {
    "Authorization": [
      `Basic ${BSON.Binary.fromText("MyUser:Mypassw0rd").toBase64()}`
    ]
  }
}

摘要式身份验证

HTTP 摘要式身份验证要求传入请求包含授权密钥，该密钥基于服务器返回的随机 nonce 值。App Services 可以自动构建密钥并在给定有效用户名和密码的情况下授权请求。

要将请求配置为使用摘要式身份验证，请将 digestAuth 字段设置为 true，并在请求文档的 username 和 password 字段中或直接在 url 字符串中指定用户凭证。

例子

以下示例演示使用摘要式身份验证对 HTTP 服务请求进行身份验证的两种等效方法。这些示例均使用用户名 MyUser 和密码 Mypassw0rd。

直接指定凭证（最佳方法）

{
  "scheme": "https",
  "username": "MyUser",
  "password": "Mypassw0rd",
  "domain": "www.example.com",
  "digestAuth": true
}

在 URL 中嵌入凭证

{
  "url": "https://MyUser:Mypassw0rd@www.example.com",
  "digestAuth": true
}

规则模板

用户只能向特定主机发送请求

{
  "%%args.url.host": "example.com"
}

请求 URL 必须包含特定查询参数

{
  "%%args.url.query.someParameter": "importantValue"
}

请求正文必须包含特定字段

{
  "body.name": { "%exists": 1 }
}

请求正文必须包含具有特定值的字段

{
  "body.city": "New York City"
}

后退

http.post()

来年

http.patch()