Close
    logoCloudomation Docs

    TaskREST

    class tasks.task_rest.TaskREST

    Call a REST service.

    Inputs

    NameTypeDefaultDescription
    allow_redirectsboolTrueIf set to False do not follow redirects. True by default.
    base_pathstrNoneA part of the path. The full path will be [base path]/[path].
    cacertstrNoneTo attach self-signed certificates (ca = certificate authority, cert = certificate) To access https:// urls, you need to sign your request. Certificates trusted by default by debian jessie will work. To disable certificate verification set verify_ssl to False.
    connect_timeoutfloatNoneA timeout in seconds for connecting to a peer. Can be disabled by setting to 0 or None
    cookiesdictNone
    dataobjectsentinel.NotSetDEPRECATED: a JSON body
    expected_status_codelist[200, 201, 202, 204]HTTP status codes which result in ENDED_SUCCESS. All other HTTP status codes will result in ENDED_ERROR.
    grantstrNoneThe name of an oauth grant to use for authentication
    headersdictNone
    hostnamestrNoneThe host to connect to. Either url or hostname must be set.
    jsonobjectsentinel.NotSetA JSON body
    max_redirectsint10Maximum number of redirects to follow. 10 by default.
    methodstrget
    multipartdictNoneA multipart body
    paramsdictNoneQuery string parameters. Will be urlencoded automatically
    pass_user_tokenboolFalseOnly for accessing the Cloudomation API. If set to True, a short-lived token is generated for the user who started the execution. This token is passed in the header to the Cloudomation API.
    pathstrNoneA part of the path. The full path will be [base path]/[path].
    read_timeoutfloatNoneA timeout in seconds for reading a portion of data from a peer. Can be disabled by setting to 0 or None
    retry_backoffdict{'initial': 1, 'maximum': 60, 'multiplier': 2, 'deadline': 600}Configration of retries. Possible keys: - initial: float - how many seconds to wait before the first retry. - maximum: float - maximum seconds to wait between retries. - multiplier: float - the delay between each retry is multiplied by this value. - deadline: float - after how many seconds of retrying to stop and fail. the minimum delay between two tries is 1 second.
    retry_status_codelist[502, 503, 504]HTTP status codes on which a retry is performed
    schemestrhttpsThe scheme to use. Currently supported are "http" and "https" (default)
    textstrNoneA text body
    total_timeoutfloatNoneTotal timeout in seconds for the whole request. Can be disabled by setting to 0 or None
    urlstrNoneThe URL to connect to. Use the format [scheme]://[hostname]/[path]. Either url or hostname must be set.
    urlencodeddictNoneA dictionary, with key-value pairs, which are to be sent as urlencoded request.
    verify_sslboolTruePerform validation of ssl certificates. This can be disabled to use self-signed certificates where the cacert is not available.

    Outputs

    NameTypeDefaultDescription
    cookiesdict
    encodingstr
    headersdict
    jsonobjectThe json output will contain the response body if it can be successfully parsed as json.
    loglist
    status_codeint
    textstrThe text output will contain the response body.
    execution_idintThe ID of the task execution
    messagestrThe ended message for the task. If the task ended with an error, the message will contain information about what went wrong
    statusstrThe ended status for the task. Either "success" or "error".

    Constants

    input_list = ['allow_redirects', 'base_path', 'cacert', 'connect_timeout', 'cookies', 'data', 'expected_status_code', 'grant', 'headers', 'hostname', 'json', 'max_redirects', 'method', 'multipart', 'params', 'pass_user_token', 'path', 'read_timeout', 'retry_backoff', 'retry_status_code', 'scheme', 'text', 'total_timeout', 'url', 'urlencoded', 'verify_ssl']output_list = ['cookies', 'encoding', 'headers', 'json', 'log', 'status_code', 'text']version = 1

    Methods

    run ()

    Example

    import flow_api
    def handler(system: flow_api.System, this: flow_api.Execution):
    # create a REST task and run it
    task = this.task('REST', url='https://api.icndb.com/jokes/random')
    # access a field of the JSON response
    joke = task.get('output_value')['json']['value']['joke']
    # end with a joke
    return this.success(message=joke)

    More

    Specify parts of URL

    Alternatively to specifying the full URL it is possible to specify different parts of the URL separately:

    import flow_api
    def handler(system: flow_api.System, this: flow_api.Execution):
    # the resulting URL will be
    # https://httpbin.org/anything/some/path?query=parameter
    task = this.task(
    'REST',
    hostname='httpbin.org',
    base_url='anything'
    url='some/path'
    params={
    'query': 'parameter',
    },
    )
    return this.success('all done')

    Sending multipart POST requests

    The Cloudomation REST connector can be used to upload files using a multipart POST request. Here are some usage examples:

    Basic example

    Specify a value in the part for a string payload, or specify a file in the part to upload a file from the Cloudomation files resource.

    this.task(
    'REST',
    url='https://httpbin.org/post',
    method='POST',
    multipart={
    'parts': [
    {
    'name': 'string-field',
    'value': 'spam & eggs',
    },
    {
    'name': 'file',
    'file': 'report.txt',
    },
    ],
    },
    )

    The example above will generate the following request:

    Content-Length: '991'
    Content-Type: multipart/mixed; boundary=aec30e9afc384303b6cb67e44aaa0f9c
    --aec30e9afc384303b6cb67e44aaa0f9c
    Content-Type: text/plain; charset=utf-8
    Content-Disposition: form-data; name="string-field"
    Content-Length: 11
    spam & eggs
    --aec30e9afc384303b6cb67e44aaa0f9c
    Content-Type: text/plain; charset=utf-8
    Content-Disposition: form-data; name="file"; filename="report.txt"
    Content-Length: 608
    ...content of the report.txt file...
    --aec30e9afc384303b6cb67e44aaa0f9c--
    Full example

    It is possible to modifiy the request being generated.

    • Specify a custom content-type or boundary in the multipart dictionary to override the default values.
    • Specify a custom content-type, content-disposition, or content-length in the part dictionary to override the default values.
    • Specify False for content-type, content-disposition, or content-length in the part dictionary to omit the field in the request.
    this.task(
    'REST',
    url='https://httpbin.org/post',
    method='POST',
    multipart={
    'content-type': 'application/my-custom-content-type',
    'boundary': 'my-custom-boundary',
    'parts': [
    {
    'name': 'string-field',
    'value': '<pre>spam & eggs</pre>',
    'content-type': 'text/html',
    'content-disposition': False,
    'content-length': False,
    },
    {
    'name': 'file',
    'file': 'report.txt',
    'content-disposition': 'form-data; filename="report.txt"',
    },
    ],
    },
    )

    The example above will generate the following request:

    Content-Length: '848'
    Content-Type: application/my-custom-content-type; boundary=my-custom-boundary
    --my-custom-boundary
    Content-Type: text/html
    <pre>spam & eggs</pre>
    --my-custom-boundary
    Content-Type: text/plain; charset=utf-8
    Content-Disposition: form-data; filename="report.txt"
    Content-Length: 608
    ...content of the report.txt file...
    --my-custom-boundary--
    Previous
    TaskREDIS
    Next
    TaskSCP