Qore AwsRestClient Module Reference 1.2
Loading...
Searching...
No Matches
AwsRestClient::AwsRestClient Class Reference

this class provides the REST client API for communication with AWS More...

#include <AwsRestClient.qm.dox.h>

Inheritance diagram for AwsRestClient::AwsRestClient:
[legend]

Public Member Methods

 constructor (hash< auto > opts, *softbool do_not_connect)
 creates the object with the given options More...
 
 constructor (string name, string description, string url, hash< auto > attributes={}, hash< auto > options={})
 creates the AwsRestConnection object More...
 
hash< ConnectionSchemeInfo > getConnectionSchemeInfoImpl ()
 Returns the ConnectionSchemeInfo hash for this object.
 
DataProvider::AbstractDataProvider getDataProvider ()
 returns a data provider object for this connection More...
 
AwsRestClient getImpl (bool connect=True, *hash< auto > rtopts)
 returns a AwsRestClient::AwsRestClient object More...
 
string getType ()
 returns "awsrest"
 
bool hasDataProvider ()
 returns True, as this connection always returns a data provider with the getDataProvider() method More...
 

Public Attributes

const AwsSignatureAlgorithm = "AWS4-HMAC-SHA256"
 AWS signature algorithm used; must match QoreDigest.
 
const AwsTermination = "aws4_request"
 Fixed termination string.
 
const DefaultSendEncoding = "gzip"
 default send encoding
 
const QoreDigest = CRYPTO_DIGEST_SHA256
 Qore digest algorithm to use for HMAC calculations; must match AwsSignatureAlgorithm.
 
const RequiredOptions = ...
 required options
 

Detailed Description

this class provides the REST client API for communication with AWS

This class requires the following options:

  • aws_keyid
  • aws_secret
  • aws_region
  • aws_service

Member Function Documentation

◆ constructor() [1/2]

AwsRestClient::AwsRestClient::constructor ( hash< auto >  opts,
*softbool  do_not_connect 
)

creates the object with the given options

Example:
AwsRestClient rest({
"url": "https://apigateway.eu-central-1.amazonaws.com",
"aws_keyid": aws_keyid,
"aws_secret": aws_secret.
});
Parameters
optsvalid options are:
  • additional_methods: Optional hash with more but not-HTTP-standardized methods to handle. It allows HTTP extensions like e.g. WebDAV to work. The hash takes the method name as a key, and the value is a boolean True or False: indicating if the method requires a message body as well. Example:
    # add new HTTP methods for WebDAV. Both of them require body posting to the server
    {"additional_methods": {"PROPFIND": True, "MKCOL": True}};
  • aws_keyid: (required) the AWS key ID
  • aws_region: the AWS region to use (ex: "us-east-1"); if it cannot be derived from the URL then it is a required option
  • was_service: the AWS service to use (ex: "iam"); if it cannot be derived from the URL then it is a required option
  • aws_secret: (required) the AWS secret access key value
  • aws_token: a temporary session token from AWS Security Token Service for this HTTP session
  • content_encoding: for possible values, see EncodingSupport; this sets the send encoding (if the "send_encoding" option is not set) and the requested response encoding (note that the RestClient class will only compress outgoing message bodies over CompressionThreshold bytes in size)
  • default_path: The default path to use for new connections if a path is not otherwise specified in the connection URL
  • default_port: The default port number to connect to if none is given in the URL
  • error_passthru: if True then HTTP status codes indicating errors will not cause a REST-RESPONSE-ERROR exception to be raised, rather such responses will be passed through to the caller like any other response
  • headers: an optional hash of headers to send with every request, these can also be overridden in request method calls
  • http_version: Either '1.0' or '1.1' (default) for the claimed HTTP protocol version compliancy in outgoing message headers
  • max_redirects: The maximum number of redirects before throwing an exception (the default is 5)
  • proxy: The proxy URL for connecting through a proxy
  • redirect_passthru: if True then redirect responses will be passed to the caller instead of processed
  • aws_s3: set to True to flag this object for use with AWS aws_s3, which requires special message encoding
  • send_encoding: a send data encoding option or the value "auto" which means to use automatic encoding; if not present defaults to "gzip" content encoding on sent message bodies (note that the RestClient class will only compress outgoing message bodies over CompressionThreshold bytes in size)
  • swagger: the path to a Swagger 2.0 REST schema file for API validation; only used if validator not provided (see the Swagger module)
  • timeout: The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: 30s)
  • url: a string giving the URL to connect to; if not given then the target URL will be taken from any validator option, if given by calling AbstractRestSchemaValidator::getTargetUrl()
  • validator: an AbstractRestSchemaValidator object to validate request and response messages; overrides swagger
do_not_connectif False (the default), then a connection will be immediately established to the remote server
Exceptions
RESTCLIENT-ERRORinvalid option passed to constructor, unsupported data serialization, etc
AWSRESTCLIENT-ERRORmissing or invalid required option for AWS REST authentication or communication
Note
the data option is always set to "json"

◆ constructor() [2/2]

AwsRestClient::AwsRestClient::constructor ( string  name,
string  description,
string  url,
hash< auto >  attributes = {},
hash< auto >  options = {} 
)

creates the AwsRestConnection object

Parameters
namethe name of the connection
descriptionconnection description
urlconnection URL (potentially with password info)
attributesvarious attributes. See below
optionsconnection options

See AbstractConnection::constructor() for attributes and options reference.

Exceptions
CONNECTION-OPTION-ERRORmissing or invalid connection option

◆ getDataProvider()

DataProvider::AbstractDataProvider AwsRestClient::AwsRestClient::getDataProvider ( )

returns a data provider object for this connection

Returns
a data provider object for this connection; the data provider is:
  • SwaggerDataProvider: if an appropriate schema is configured
  • RestClientDataProvider: if there is no schema configured
Exceptions
DATA-PROVIDER-ERRORthis object does not support the data provider API

◆ getImpl()

AwsRestClient AwsRestClient::AwsRestClient::getImpl ( bool  connect = True,
*hash< auto >  rtopts 
)

returns a AwsRestClient::AwsRestClient object

Parameters
connectif True, then the connection is returned already connected
rtoptsthis connection type does not accept any runtime options, so this parameter is ignored
Returns
a AwsRestClient object

◆ hasDataProvider()

bool AwsRestClient::AwsRestClient::hasDataProvider ( )

returns True, as this connection always returns a data provider with the getDataProvider() method

Returns
True, as this connection always returns a data provider with the getDataProvider() method
See also
getDataProvider()