WOLFRAM

Wolfram Language & System Documentation Center
"AWS" (Service Connection)

"AWS" (Service Connection)

Interact with 200+ Amazon Web Services product APIs.

Connecting & Authenticating

ServiceConnect["AWS"] creates a connection to Amazon Web Services.
ServiceExecute["AWS",<|"GetService""service"|>] retrieves a child ServiceObject representing the AWS service named "service", such as "EC2" or "CloudFormation".
Consult the Authenticate with Amazon Web Services workflow for instructions on authenticating a new service connection with your AWS credentials.

Meta Requests

ServiceExecute["AWS","request",params] performs an operation on the master AWS service connection, using parameters params. The following give possible requests.

Service Metadata

Requests:

"Services" — list available AWS services

Obtain Child Service Objects

Requests:

"GetService" — obtain a child ServiceObject representing a single AWS service

Parameters:
  • "Name"(required)AWS service to access

    • Child Service Requests

    After using ServiceExecute["AWS","GetService",<|"Name""service"|>] to obtain a child ServiceObject obj representing a single AWS service "service", ServiceExecute[obj,"request",params] sends a request to "service" using parameters params.
    A service's available requests can be listed with ServiceExecute[obj,"Requests"]. Request and parameter names correspond to those used in AWS official API documentation.
    The following additional meta requests are applicable to all child services.

    List Requests

    Requests:

    "Requests" — list available requests for the service

    Request Metadata

    Requests:

    "RequestTemplate" — show the expected structure of a request's payload

    "ResponseTemplate" — show the expected structure of a request's response data

    Parameters:
  • "Request"(required)name of request to inspect

    • Parameter Details

    The following meta parameters are available for all service requests, in addition to those parameters given by each request's "RequestTemplate":
  • "IncludeBodyByteArray"Falseinclude ByteArray of raw response body
    "RawResponse"Falsereturn full response and failure data
    "RequestEndpoint"Automaticcustom HTTP endpoint
    "RequestRegion"Automaticoverride globally specified AWS region
    "ValidateRequest"Truevalidate request structure before sending
    • Setting "IncludeBodyByteArray"True causes a ByteArray containing the raw, unparsed response body to be included in the response metadata association. "IncludeBodyByteArray" is relevant only if "RawResponse" is also True.
    Setting "RawResponse"True causes ServiceExecute to return an association containing response metadata as well as the parsed response data. If a request error occurred, the association also contains rich failure data.
    The value of the "RequestEndpoint" parameter can be a verbatim string like "https://abcd1234.mediaconvert.us-west-1.amazonaws.com" or a string containing template variables "{service}" or "{region}", like "{service}.{region}.c2s.ic.gov". If no URL scheme is indicated, the default for the service is assumed.
    The default setting "ValidateRequest"True causes the service connection to validate supplied request parameters locally before sending a request to the server.

    Examples

    open all close all

    Basic Examples  (2)

    Create a connection to AWS:

    Wolfram Language code: aws = ServiceConnect["AWS"]

    List the available AWS services:

    Wolfram Language code: ServiceExecute["AWS", "Services"]//Short

    Obtain a child ServiceObject representing Amazon Translate:

    Wolfram Language code: translate = ServiceExecute[aws, "GetService", <|"Name" -> "Translate"|>]

    List available requests for the service:

    Wolfram Language code: translate["Requests"]

    Obtain a request template for the "TranslateText" request:

    Wolfram Language code: translate["RequestTemplate", <|"Request" -> "TranslateText"|>]

    Send a "TranslateText" request:

    Wolfram Language code: translate["TranslateText", <| "Text" -> "今日は良い一日だった", "SourceLanguageCode" -> "auto", "TargetLanguageCode" -> "en"|> ]

    Obtain a response template for a request:

    Wolfram Language code: ec2 = ServiceExecute["AWS", "GetService", "Name" -> "EC2"]; ec2["ResponseTemplate", "Request" -> "GetReservedInstancesExchangeQuote"]

    Request Parameters  (5)

    "IncludeBodyByteArray"  (1)

    Setting "IncludeBodyByteArray"True causes a "BodyByteArray" key to be included in the raw response association:

    Wolfram Language code: ec2 = ServiceExecute["AWS", "GetService", <|"Name" -> "EC2"|>]; ec2["DescribeVolumes", <|"RawResponse" -> True, "IncludeBodyByteArray" -> True|>]

    The value of "BodyByteArray" is the raw response body directly from the server:

    Wolfram Language code: %["BodyByteArray"]//ByteArrayToString

    If a request fails, "BodyByteArray" will be included regardless of the "IncludeBodyByteArray" setting:

    Wolfram Language code: ec2["DescribeVolumes", <|"NextToken" -> "foo", "RawResponse" -> True|>]

    "RawResponse"  (1)

    Setting "RawResponse"True causes an association containing response data and metadata to be returned:

    Wolfram Language code: ec2 = ServiceExecute["AWS", <|"GetService", "Name" -> "EC2"|>]; ec2["DescribeVolumes", <|"RawResponse" -> True|>]

    If the request fails, the value of the "Data" key will be a Failure object:

    Wolfram Language code: ec2["DescribeVolumes", <|"NextToken" -> "foo", "RawResponse" -> True|>]

    "RequestEndpoint"  (1)

    Certain situations may call for the use of a nondefault service endpoint:

    Wolfram Language code: mediaconvert = ServiceExecute["AWS", "GetService", <|"Name" -> "MediaConvert"|>]; mediaconvert["ListJobs"]

    Supply a custom endpoint with the "RequestEndpoint" parameter:

    Wolfram Language code: mediaconvert["ListJobs", <|"RequestEndpoint" -> "https://abcd1234.mediaconvert.us-east-1.amazonaws.com"|>]["Jobs", 1]

    "RequestRegion"  (1)

    Some services are available only in certain regions:

    Wolfram Language code: groundstation = ServiceExecute["AWS", "GetService", <|"Name" -> "GroundStation"|>]; groundstation["ListSatellites"]

    The "RequestRegion" parameter overrides the default region on a per-request basis:

    Wolfram Language code: groundstation["ListSatellites", <|"RequestRegion" -> "me-south-1"|>]

    "ValidateRequest"  (1)

    By default, request parameters are validated against the expected structure before sending the request:

    Wolfram Language code: translate = ServiceExecute["AWS", "GetService", "Name" -> "Translate"]; translate["TranslateText", <|"Text" -> "今日は良い一日だった", "SourceLanguageCode" -> "auto"|> ]

    With "ValidateRequest"False, local validation is disabled, which may result in server errors:

    Wolfram Language code: translate["TranslateText", <|"Text" -> "今日は良い一日だった", "SourceLanguageCode" -> "auto", "ValidateRequest" -> False|> ]

    Possible Issues  (1)

    With default settings, a server error will cause ServiceExecute to emit a message and return unevaluated:

    Wolfram Language code: ec2 = ServiceExecute["AWS", "GetService", <|"Name" -> "EC2"|>]; ec2["DescribeVolumes", <|"NextToken" -> "foo"|>]

    Use "RawResponse"True to instead return an association containing a Failure object:

    Wolfram Language code: ec2["DescribeVolumes", <|"NextToken" -> "foo", "RawResponse" -> True|>]