Qore SalesforceRestClient Module Reference
1.5.1
|
this class provides the REST client API for communication with Salesforce.com More...
Public Member Methods | |
hash< auto > | bulkGet (string path, auto body, *reference< hash< auto >> info, *hash< auto > hdr) |
sends an HTTP GET request to the REST server using the Salesforce.com Bulk REST API and returns the response More... | |
hash< auto > | bulkJobAddBatch (string jobid, data batch_data, string job_content_type, *reference< hash< auto >> info, *hash< auto > hdr) |
add a batch to a job using the Bulk REST API More... | |
hash< auto > | bulkJobClose (string jobid, *reference< hash< auto >> info, *hash< auto > hdr) |
sends a Bulk REST API job close POST request to the server and returns the deserialized result message body More... | |
hash< auto > | bulkJobCreate (string operation, string object, string job_content_type, *reference< hash< auto >> info, *hash< auto > hdr) |
creates a Salesforce.com batch job and returns the job information as a hash More... | |
hash< auto > | bulkPost (string path, auto body, *reference< hash< auto >> info, *hash< auto > hdr) |
sends an HTTP POST request to the REST server using the Salesforce.com Bulk REST API and returns the response More... | |
checkClientOptions (hash< auto > opts) | |
verifies that the options passed match the configured options More... | |
constructor (*hash< auto > opts, *softbool do_not_connect) | |
creates the object with the given options (which include the following mandatory options for Salesforce.com authentication: client_id , client_secret , username , password ) More... | |
hash< auto > | doBulkRequest (string m, string path, auto body, *reference< hash< auto >> info, softbool decode_errors=True, *hash< auto > hdr) |
sends a Bulk API REST request to the Salesforce.com server using "rawxml" serialization and returns the response; performs an implicit login to Salesforce.com if necessary More... | |
hash< auto > | doRequest (string m, string path, auto body, *reference< hash< auto >> info, softbool decode_errors=True, *hash< auto > hdr) |
sends an HTTP request to the REST server and returns the response; performs an implicit login to Salesforce.com if necessary More... | |
string | getApi () |
returns the Salesforce.com REST API version currently in use | |
*string | getToken () |
returns the access token | |
login (*reference< hash< auto >> info) | |
logs in to Salesforce.com with the credentials provided in the constructor() More... | |
logout (*reference< hash< auto >> info) | |
logs out of Salesforce.com by revoking the access token More... | |
hash< auto > | patch (string path, auto body, *reference< hash< auto >> info, *hash< auto > hdr) |
sends an HTTP PATCH request to the Salesforce.com REST server and returns the response; performs an implicit login to Salesforce.com if necessary More... | |
Static Public Member Methods | |
static string | getBulkDate (date d) |
returns a date string for use with Salesforce.com Bulk REST API requests More... | |
static string | getGmtDate (date d) |
returns a date string in GMT for use in Salesforce.com requests | |
Public Attributes | |
const | AsyncDataloadNs = "http://www.force.com/2009/06/asyncapi/dataload" |
Salesforce.com async dataload namespace. | |
const | Defaults |
defaults for direct member values | |
const | DefaultSendEncoding = "gzip" |
default send encoding | |
const | JobInfoAttributes = ... |
Salesforce.com XML jobInfo attributes. | |
const | RequiredOptions = ... |
required options | |
Private Member Methods | |
loginIntern (*reference< hash > info) | |
performs authentication and authorization with Salesforce.com using the OAuth2 authorization URL More... | |
Mutex | m () |
Mutex for token acquisition. | |
Static Private Member Methods | |
static hash | getOptions (*hash< auto > opts) |
returns options for the RestClient::constructor() | |
Private Attributes | |
string | api |
Salesforce.com REST API version to be used ("auto" = latest version) | |
hash< auto > | api_hash |
hash of APIs retrieved from GET /services/data; keyed by API version string; values: "label" , "url" | |
string | api_used |
Salesforce.com REST API version currently in use. | |
string | client_id |
Salesforce.com "consumer key". | |
string | client_secret |
Salesforce.com "consumer secret". | |
string | oauth_url_auth |
Salesforce.com OAuth2 Authorization URL. | |
string | oauth_url_revoke |
Salesforce.com OAuth2 Revoke Token URL. | |
string | oauth_url_token |
Salesforce.com OAuth2 Get Token URL. | |
string | password |
Salesforce.com password. | |
string | token |
Salesforce.com token. | |
string | username |
Salesforce.com username. | |
this class provides the REST client API for communication with Salesforce.com
This class requires the following options for Salesforce.com authentication and authorization to the target Connected App:
client_id:
the Salesforce.com "consumer key"client_secret:
the Salesforce.com "consumer secret"username:
the Salesforce.com account usernamepassword:
the Salesforce.com account passwordThe following options can be overridden; default values are provided as follows:
api:
default value "auto"
for the Salesforce.com REST API version; "auto"
means use the latest version availableoauth_url_auth:
default value "https://login.salesforce.com/services/oauth2/authorize"
oauth_url_token:
default value "https://login.salesforce.com/services/oauth2/token"
(used for logging in to Salesforce.com)oauth_url_revoke:
default value "https://login.salesforce.com/services/oauth2/revoke"
This class also automatically adds support for the "PATCH"
HTTP method used by Salesforce.com for updates to existing objects, as well as the SalesforceRestClient::patch() method
The SalesforceRestClient::patchdoRequest() method is overridden in this class to provide transparent authentication and authorization to Salesforce.com. With every REST request, if no token has been acquired, first a login token will be acquired, the internal URL set to the target URL provided by the token call, and then the requested REST call will be made.
When logging in to Salesforce.com (see SalesforceRestClient::login()), the Authorization
header is set by default to be included with any future calls made through this object (or with RestClient methods in the parent class).
When sending headers to Salesforce.com, any headers with date values are converted to GMT format; for example, the "If-Modified-Since"
and "If-Unmodified-Since"
headers can be set to date/time values, and this object will convert them to date strings in GMT format; ex:
In a request sent from the call above in the Europe/Prague
time zone, the "If-Modified-Since"
header would be sent as:
If-Modified-Since: Thu, 24 Nov 2016 23:00:00 GMT
The following methods support communication with the Salesforce.com Bulk REST API:
hash<auto> SalesforceRestClient::SalesforceRestClient::bulkGet | ( | string | path, |
auto | body, | ||
*reference< hash< auto >> | info, | ||
*hash< auto > | hdr | ||
) |
sends an HTTP GET
request to the REST server using the Salesforce.com Bulk REST API and returns the response
path | the URI path to add (will be appended to any root path given in the constructor) |
body | an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor() |
info | an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
|
hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body"
keyDESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
|
Note that this exception is not raised for HTTP status codes indicating an error if the error_passthru
option is set to True
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
hash<auto> SalesforceRestClient::SalesforceRestClient::bulkJobAddBatch | ( | string | jobid, |
data | batch_data, | ||
string | job_content_type, | ||
*reference< hash< auto >> | info, | ||
*hash< auto > | hdr | ||
) |
add a batch to a job using the Bulk REST API
jobid | the job ID to add the batch to |
batch_data | the data for the job; this data is not serialized but rather sent as-is using the MIME Content-Type associated with the job content type value |
job_content_type | the content type of the job; see Salesforce.com Bulk REST API Job Content Types for valid values |
info | an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
|
hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
INVALID-CONTENT-TYPE | invalid job content type passed; see BulkJobContentTypes for valid values |
hash<auto> SalesforceRestClient::SalesforceRestClient::bulkJobClose | ( | string | jobid, |
*reference< hash< auto >> | info, | ||
*hash< auto > | hdr | ||
) |
sends a Bulk REST API job close POST
request to the server and returns the deserialized result message body
jobid | the job ID to close |
info | an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
|
hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
hash<auto> SalesforceRestClient::SalesforceRestClient::bulkJobCreate | ( | string | operation, |
string | object, | ||
string | job_content_type, | ||
*reference< hash< auto >> | info, | ||
*hash< auto > | hdr | ||
) |
creates a Salesforce.com batch job and returns the job information as a hash
operation | the operation to create; see Salesforce.com Bulk REST API Job Operations for valid values |
object | the API object to operate on |
job_content_type | the content type of the job; see Salesforce.com Bulk REST API Job Content Types for valid values |
info | an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
|
hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
INVALID-OPERATION | invalid operation passed; see BulkJobContentTypes for valid values |
INVALID-CONTENT-TYPE | invalid job content type passed; see BulkJobContentTypes for valid values |
hash<auto> SalesforceRestClient::SalesforceRestClient::bulkPost | ( | string | path, |
auto | body, | ||
*reference< hash< auto >> | info, | ||
*hash< auto > | hdr | ||
) |
sends an HTTP POST
request to the REST server using the Salesforce.com Bulk REST API and returns the response
path | the URI path to add (will be appended to any root path given in the constructor) |
body | an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor() |
info | an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
|
hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body"
keyDESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
|
Note that this exception is not raised for HTTP status codes indicating an error if the error_passthru
option is set to True
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
SalesforceRestClient::SalesforceRestClient::checkClientOptions | ( | hash< auto > | opts | ) |
verifies that the options passed match the configured options
SALESFORCE-REST-OPTION-ERROR | one or more options does not match |
SalesforceRestClient::SalesforceRestClient::constructor | ( | *hash< auto > | opts, |
*softbool | do_not_connect | ||
) |
creates the object with the given options (which include the following mandatory options for Salesforce.com authentication: client_id
, client_secret
, username
, password
)
opts | valid options are:
|
do_not_connect | if False (the default), then a connection will be immediately established to the remote server and a token will be received |
RESTCLIENT-ERROR | invalid option passed to constructor, unsupported data serialization, etc |
SALESFORCERESTCLIENT-ERROR | missing or invalid connection option |
hash<auto> SalesforceRestClient::SalesforceRestClient::doBulkRequest | ( | string | m, |
string | path, | ||
auto | body, | ||
*reference< hash< auto >> | info, | ||
softbool | decode_errors = True , |
||
*hash< auto > | hdr | ||
) |
sends a Bulk API REST request to the Salesforce.com server using "rawxml"
serialization and returns the response; performs an implicit login to Salesforce.com if necessary
m | the HTTP method to be used; case is ignored (if not a valid method an HTTP-CLIENT-METHOD-ERROR exception is raised) |
path | the URI path to add (will be appended to any root path given in the constructor) |
body | an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor() |
info | an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
|
decode_errors | decode the message body with HTTP error responses and throw an exception based on the message body |
hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body"
keyDESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
HTTP-CLIENT-METHOD-ERROR | invalid HTTP method argument passed |
REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
|
Note that this exception is not raised for HTTP status codes indicating an error if the error_passthru
option is set to True
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
hash<auto> SalesforceRestClient::SalesforceRestClient::doRequest | ( | string | m, |
string | path, | ||
auto | body, | ||
*reference< hash< auto >> | info, | ||
softbool | decode_errors = True , |
||
*hash< auto > | hdr | ||
) |
sends an HTTP request to the REST server and returns the response; performs an implicit login to Salesforce.com if necessary
m | the HTTP method to be used; case is ignored (if not a valid method an HTTP-CLIENT-METHOD-ERROR exception is raised) |
path | the URI path to add (will be appended to any root path given in the constructor) |
body | an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor() |
info | an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
|
decode_errors | decode the message body with HTTP error responses and throw an exception based on the message body |
hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body"
keyDESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
HTTP-CLIENT-METHOD-ERROR | invalid HTTP method argument passed |
REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
|
Note that this exception is not raised for HTTP status codes indicating an error if the error_passthru
option is set to True
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.
returns a date string for use with Salesforce.com Bulk REST API requests
d | the date to return as a formatted string using "YYYY-MM-DDTHH:mm:SSZ" |
SalesforceRestClient::SalesforceRestClient::login | ( | *reference< hash< auto >> | info | ) |
logs in to Salesforce.com with the credentials provided in the constructor()
info | an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
|
|
private |
performs authentication and authorization with Salesforce.com using the OAuth2 authorization URL
called with the Mutex held
SalesforceRestClient::SalesforceRestClient::logout | ( | *reference< hash< auto >> | info | ) |
logs out of Salesforce.com by revoking the access token
if not logged in then this method returns immediately
info | an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
|
hash<auto> SalesforceRestClient::SalesforceRestClient::patch | ( | string | path, |
auto | body, | ||
*reference< hash< auto >> | info, | ||
*hash< auto > | hdr | ||
) |
sends an HTTP PATCH
request to the Salesforce.com REST server and returns the response; performs an implicit login to Salesforce.com if necessary
path | the URI path to add (will be appended to any root path given in the constructor) |
body | an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor() |
info | an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
|
hdr | any headers to be sent with the request; headers here will override default headers for the object as well |
"body"
keyDESERIALIZATION-ERROR | the response body could not be deserialized (unknown Content-Type or invalid serialization) |
REST-RESPONSE-ERROR | if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
|
Note that this exception is not raised for HTTP status codes indicating an error if the error_passthru
option is set to True
Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.