http.put()
On this page
Definition
Sends an HTTP PUT request to the specified URL using the Atlas App Services HTTP Service.
Usage
Example
Note
This example assumes you have configured an HTTP service called
"myHttp". If you do not need this
HTTP action validated with Service Rules,
you can use the Send an HTTP Request (context.http
) module.
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; }) };
Parameters
The http.put()
action accepts one argument of the
following form:
{ "url": <string>, "headers": <document>, "body": <string>, "form": <document>, "cookies": <string>, "authUrl": <string>, "followRedirects": <boolean> }
Field | Description | ||||||
---|---|---|---|---|---|---|---|
Request URL url: <string> | Required. The target URL for the HTTP request. Alternatively,
you can specify the components of the URL as root-level fields.
See Alternative URL Arguments. | ||||||
Request Body body: <string> | Required. The stringified body of the HTTP request.
If the request payload has a content type of
multipart/form-data , use the form parameter instead of
body . | ||||||
Form Request Body form: <document> | A document where each field maps to a field in a
NoteRequests that use the Example
| ||||||
Request Headers headers: <document> | Optional. A document where each field name corresponds to a type of HTTP header and each field value is an array of one or more string values for that header. Example
| ||||||
Request Cookies cookies: <document> | Optional. A document where each field name corresponds to a cookie name and each field value is that cookie's string value. Example
| ||||||
Digest Authentication digestAuth: <boolean> | Optional. If true , App Services authenticates the request using
digest authentication. You must specify a
username and password (either as fields in the request
document or as part of the URL) to use digest authentication.
For more details, see Request Authentication. | ||||||
Request Authentication URL authUrl: <string> | Optional. A URL that returns an Authorization cookie for the
HTTP request. | ||||||
Follow Redirects followRedirects: <boolean> | Optional. If true , the request will follow any HTTP
redirects it receives for the target URL. |
Alternative URL Parameters
If you need to specify the individual components of the request's
target URL, omit the url
field and specify the components as
root-level fields. The following URL component fields are available:
<scheme>://<host>/<path>?<query>#<fragment>
{ "scheme": <string>, "host": <string>, "path": <string>, "query": <document>, "fragment": <string>, "username": <string>, "password": <string> }
Name | Contents | |||||||
---|---|---|---|---|---|---|---|---|
scheme | Optional. Default: "http" .Valid options: https , http The URL scheme. Example
| |||||||
host | Required. The hostname of the target resource. Example
| |||||||
path | Optional. The path of the target resource. Example
| |||||||
query | Optional. A document where each field maps to a parameter in the URL query string. The value of each field is an array of strings that contains all arguments for the parameter. Example
| |||||||
fragment | Optional. The URL fragment. This portion of the URL includes everything
after the hash ( Example
| |||||||
username | Optional. The username with which to authenticate the request. Typically,
users utilize this argument with the | |||||||
password | Optional. The password with which to authenticate the request. The
password should correspond to the user specified in the
|
Return Value
The http.put()
action returns a promise that resolves to a
document with the following form:
{ "status": <string>, "statusCode": <integer>, "contentLength": <integer>, "headers": <document>, "cookies": <array>, "body": <binary> }
Field | Type | Description | |||
---|---|---|---|---|---|
status | string | The HTTP Request status message. | |||
statusCode | integer | The HTTP Request status code. | |||
contentLength | integer | The number of bytes returned in the response body . | |||
headers | document | A document where each field name corresponds to a type of HTTP header and each field value is an array of one or more string values for that header. Example
| |||
cookies | document | A document where each field name corresponds to a cookie name, and each field value is that cookie's string value. Example
| |||
body | binary | The binary-encoded body of the HTTP response. |
Request Authentication
You can authenticate an outbound HTTP request using one of the standard HTTP authentication schemes. Atlas App Services supports the following authentication schemes:
Basic Authentication
HTTP basic authentication
requires that incoming requests include a valid username and password
for the requested service. You can specify the user credentials in the
username
and password
fields of the request document, directly
in a url
string, or in an Authorization HTTP header.
Example
The following examples demonstrate three equivalent ways to
authenticate an HTTP service request using basic authentication. The
examples all use the username MyUser
and the password
Mypassw0rd
. You would pass one of these objects as an argument to
the given HTTP method.
{ "scheme": "https", "username": "MyUser", "password": "Mypassw0rd", "domain": "www.example.com" }
{ "url": "https://MyUser:Mypassw0rd@www.example.com" }
{ "url": "https://www.example.com", "headers": { "Authorization": [ `Basic ${BSON.Binary.fromText("MyUser:Mypassw0rd").toBase64()}` ] } }
Digest Authentication
HTTP digest authentication requires that incoming requests include an authorization key based on a random nonce value returned from the server. App Services can automatically construct the key and authorize requests given a valid username and password.
To configure a request to use digest authentication, set the
digestAuth
field to true
and specify the user credentials in the
username
and password
fields of the request document or directly
in a url
string.
Example
The following examples demonstrate two equivalent ways to
authenticate an HTTP service request using digest authentication. The
examples all use the username MyUser
and the password
Mypassw0rd
.
{ "scheme": "https", "username": "MyUser", "password": "Mypassw0rd", "domain": "www.example.com", "digestAuth": true }
{ "url": "https://MyUser:Mypassw0rd@www.example.com", "digestAuth": true }
Rule Templates
Users Can Only Send Requests to a Specific Host
{ "%%args.url.host": "example.com" }
Requests URLs Must Include a Specific Query Parameter
{ "%%args.url.query.someParameter": "importantValue" }
Request Bodies Must Include a Specific Field
{ "body.name": { "%exists": 1 } }
Request Bodies Must Include Fields with Specific Values
{ "body.city": "New York City" }