Qore CdsRestClient Module Reference  1.0
CdsRestClient::CdsRestClient Class Reference

this class provides the REST client API for communication with Microsoft Dynamics 365 Common Data Service servers More...

Inheritance diagram for CdsRestClient::CdsRestClient:

Public Member Methods

 constructor (hash< auto > opts, *softbool do_not_connect)
 creates the object with the given options More...
 
string getApi ()
 returns the CDS REST API version currently in use
 
*string getToken ()
 returns the access token
 

Static Public Member Methods

static error (string fmt)
 throws an exception due to an error
 
static hash< auto > getOptions (hash< auto > opts)
 returns options for the CdsRestClient::constructor()
 
static string getString (hash< auto > opts, string key)
 gets a string option
 

Public Attributes

const DefaultApiVersion = "9.1"
 Default API version.
 
const OAuth2AuthUrl = "https://login.microsoftonline.com"
 OAuth2 auth URL.
 
const OAuth2TokenUriPathSuffix = "/oauth2/v2.0/token"
 OAuth2 token URI path suffix.
 
const RequestUriPathPrefix = "/api/data/v"
 Request URI path prefix.
 

Private Member Methods

 loginIntern (*reference< hash< auto >> info)
 performs authentication and authorization with SAP using the OAuth2 authorization URL
 
hash< auto > sendAndDecodeResponse (*data body, string m, string path, hash< auto > hdr, *reference< hash< auto >> info, *softbool decode_errors)
 sends the outgoing HTTP message and recodes the response to data
 

Detailed Description

this class provides the REST client API for communication with Microsoft Dynamics 365 Common Data Service servers

This class requires the following options for Microsoft Dynamics 365 Common Data Service authentication and authorization to the target server:

  • client_id: the OAuth2 client ID
  • client_secret: the OAuth2 client secret
  • tenant: the tenant ID

Errors returned from Dynamics will have the following format:

  • err: will be the hex error code from Dynamics (ex: 0x8006088a)
  • desc: the exception message (ex: Resource not found for the segment 'WhoAmi'.)
  • arg: the error hash from the server plus a decoded_body argument with any decoded message body

Member Function Documentation

◆ constructor()

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

creates the object with the given options

Example:
CdsRestClient rest({
"url": "https://my-instance.crm2.dynamics.com",
"client_id": client_id,
"client_secret": client_secret,
"tenant": "bef147c4-8dd3-4e18-9af8-9573d86d3738",
});
Parameters
optsvalid options are:
  • additional_methods: Optional hash with more but not-HTTP-standardized methods to handle. It allows to create various HTTP extensions like e.g. WebDAV. 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}}
  • api: the API version for Dynamics
  • client_id: (required) the OAuth2 client ID
  • client_secret: (required) the OAuth2 client secret
  • 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)
  • data: a data serialization option; if not present defaults to "json"
  • 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
  • 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)
  • scope: the OAuth2 scope for the login; the default it to use the target URL + "/.default"
  • tenant: (required) the tenant ID
  • timeout: The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: 30s)
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
CDSRESTCLIENT-ERRORmissing or invalid required option for REST authentication or communication