HTTP Client

The HTTP Client destination writes data to an HTTP endpoint. The destination sends requests to an HTTP resource URL. Use the HTTP Client destination to perform a range of standard requests or use an expression to determine the request for each record.

When you configure the HTTP Client destination, you define the resource URL, headers, and method to use for the requests. You configure the destination to generate one request for each record or it to generate a single request containing all records in the batch.

You can configure the timeout, request transfer encoding, and authentication type. You can configure the destination to use the Gzip or Snappy compression format to write the messages. You can optionally use an HTTP proxy and configure SSL/TLS properties.

You can also configure the destination to use the OAuth 2 protocol to connect to an HTTP service.

HTTP Method

You can use the following methods with the HTTP Client destination:
  • GET
  • PUT
  • POST
  • DELETE
  • HEAD
  • Expression - An expression that evaluates to one of the other methods.

Expression Method

The Expression method allows you to write an expression that evaluates to a standard HTTP method. Use the Expression method to generate a workflow. For example, you can use an expression that passes data to the server (PUT) based on the data in a field.

Number of Requests

The HTTP Client destination can generate one HTTP request for each record, or it can generate a single request containing all records in the batch.

Configure the destination to generate requests in one of the following ways:

Multiple requests per batch
By default, the destination generates one HTTP request for each record in the batch and sends multiple requests at a time. To preserve record order, the destination waits until all requests for the entire batch are completed before processing the next batch.
When the destination generates multiple requests per batch, you specify the maximum number of parallel requests. Default is 1. Increasing the number of parallel requests can improve performance but increases the load on the server. Network latency can also significantly impact the performance when sending multiple parallel requests.
Single request per batch
If you enable the One Request per Batch property, the destination generates a single HTTP request containing all records in the batch.
When the destination generates a single request per batch, it ignores the value entered for the maximum number of parallel requests. Generating a single request per batch can improve performance, depending on the amount of data sent in the request.

OAuth 2 Authorization

You can configure the HTTP Client destination to use the OAuth 2 protocol to connect to an HTTP service that uses basic, digest, or universal authentication, OAuth 2 client credentials, OAuth 2 username and password, or OAuth 2 JSON Web Tokens (JWT).

The OAuth 2 protocol authorizes third-party access to HTTP service resources without sharing credentials. The HTTP Client destination uses credentials to request an access token from the service. The service returns the token to the destination, and then the destination includes the token in a header in each request to the resource URL.

The credentials that you enter to request an access token depend on the credentials grant type required by the HTTP service. You can define the following OAuth 2 credentials grant types for HTTP Client:
Client credentials grant

HTTP Client sends its own credentials - the client ID and client secret or the basic, digest, or universal authentication credentials - to the HTTP service. For example, use the client credentials grant to process data from the Twitter API or from the Microsoft Azure Active Directory (Azure AD) API.

For more information about the client credentials grant, see https://tools.ietf.org/html/rfc6749#section-4.4.

Resource owner password credentials grant

HTTP Client sends the credentials for the resource owner - the resource owner username and password - to the HTTP service. Or, you can use this grant type to migrate existing clients using basic, digest, or universal authentication to OAuth 2 by converting the stored credentials to an access token.

For example, use this grant to process data from the Getty Images API. For more information about using OAuth 2 to connect to the Getty Images API, see http://developers.gettyimages.com/api/docs/v3/oauth2.html.

For more information about the resource owner password credentials grant, see https://tools.ietf.org/html/rfc6749#section-4.3.

JSON Web Tokens (JWT)

HTTP Client sends a JSON-based security token encoding to the HTTP service. For example, use JSON Web Tokens to process data from the Google API.

Let’s look at some examples of how to configure authentication and OAuth 2 authorization to process data from Twitter, Microsoft Azure AD, and Google APIs.

Example for Twitter

To use OAuth 2 authorization to write to Twitter, configure HTTP Client to use basic authentication and the client credentials grant.

For more information about configuring OAuth 2 authorization for Twitter, see https://dev.twitter.com/oauth/application-only.

  1. On the HTTP tab, set Authentication Type to Basic, and then select Use OAuth 2.
  2. On the Credentials tab, enter the Twitter consumer key and consumer secret for the Username and Password properties.
    Tip: To secure sensitive information such as the consumer key and secret, you can use runtime resources or Hashicorp Vault secrets. For more information, see Using Runtime Resources or Accessing Hashicorp Vault Secrets.
  3. On the OAuth 2 tab, select Client Credentials Grant for the grant type.
  4. In the Token URL property, enter the following URL used to request the access token:
    https://api.twitter.com/oauth2/token
The following image shows the OAuth 2 tab configured for Twitter:

Example for Microsoft Azure AD

To use OAuth 2 authorization to write to Microsoft Azure AD, configure HTTP Client to use no authentication and the client credentials grant.

Note: This example uses Microsoft Azure AD version 1.0.

For more information about configuring OAuth 2 authorization for Microsoft Azure AD, see https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-code.

  1. On the HTTP tab, set Authentication Type to None, and then select Use OAuth 2.
  2. On the OAuth 2 tab, select Client Credentials Grant for the grant type.
  3. In the Token URL property, enter the following URL used to request the access token:
    https://login.microsoftonline.com/<tenant identifier>/oauth2/token

    Where <tenant identifier> is the Azure AD tenant identifier.

  4. Enter the OAuth 2 client ID and secret.

    The client ID is the Application Id assigned to your app when you registered it with Azure AD, found in the Azure Classic Portal.

    The client secret is the application secret that you created in the app registration portal for your app.

    Tip: To secure sensitive information such as the client ID and secret, you can use runtime resources or Hashicorp Vault secrets. For more information, see Using Runtime Resources or Accessing Hashicorp Vault Secrets.
  5. Add any key-value pairs that the HTTP service requires in the token request.
    In our example, we are accessing the graph.microsoft.com API in our resource URL, so we need to add the following key-value pair:
    resource : https://graph.microsoft.com/
The following image shows the OAuth 2 tab configured for Microsoft Azure AD version 1.0:

Example for Google

To use OAuth 2 authorization to write to Google service accounts, configure HTTP Client to use no authentication and the JSON Web Tokens grant.

For more information about configuring OAuth 2 authorization for Google, see https://developers.google.com/identity/protocols/OAuth2.

  1. On the HTTP tab, set Authentication Type to None, and then select Use OAuth 2.
  2. On the OAuth 2 tab, select JSON Web Tokens for the grant type.
  3. In the Token URL property, enter the following URL used to request the access token:
    https://www.googleapis.com/oauth2/v4/token
  4. Select the following algorithm to sign the JWT: RSASSA-PKCS-v1_5 using SHA-256.
  5. Enter the Base64 encoded key used to sign the JWT.

    To access the key, download the JSON key file when you generate the Google credentials. Locate the "private_key" field in the file, which contains a string version of the key. Copy the string into the JWT Signing Key property, and then replace all "\n" literals with new lines.

    Tip: To secure sensitive information such as the JWT signing key, you can use runtime resources or Hashicorp Vault secrets. For more information, see Using Runtime Resources or Accessing Hashicorp Vault Secrets.
  6. In the JWT Claims property, enter the required claims to use with the JWT token request, in JSON format.

    For a list of the required claims for Google service accounts, see https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatingjwt.

    For example, enter the claims in the following JSON format:
    {
       "iss":"my_name@my_account.iam.gserviceaccount.com",
       "scope":"https://www.googleapis.com/auth/drive",
       "aud":"https://www.googleapis.com/oauth2/v4/token",
       "exp":${(time:dateTimeToMilliseconds(time:now())/1000) + 50 * MINUTES},
       "iat":${time:dateTimeToMilliseconds(time:now())/1000}
    }

    You can include the expression language in the JWT claims. For example, in the sample claim above, both the "exp" (expiration time) claim and the "iat" (issued at) claim include Data Collector time functions to set the expiration time and the issue time.

    Tip: Google access tokens expire after 60 minutes. As a result, set the expiration time claim to be slightly less than 60 minutes so that HTTP Client can request a new token within the time limit.
The following image shows the OAuth 2 tab configured for Google service accounts:

Data Formats

HTTP Client writes data to HTTP endpoints based on the data format that you select. You can use the following data formats:

Binary
The destination writes binary data from a single field in the record.
JSON
The destination writes records as JSON data. You can use one of the following formats:
  • Array - Each file includes a single array. In the array, each element is a JSON representation of each record.
  • Multiple objects - Each file includes multiple JSON objects. Each object is a JSON representation of a record.
SDC Record
The destination writes records in the SDC Record data format.
Text
The destination writes data from a single text field to the destination system. When you configure the stage, you select the field to use. When necessary, merge record data into the field earlier in the pipeline.
You can configure the characters to use as record separators. By default, the destination uses a Unix-style line ending (\n) to separate records.
When a record contains no data in the text field, you can configure the destination to write the record separator characters, creating an empty line. By default, the destination discards the record.

Configuring an HTTP Client Destination

Configure an HTTP Client destination to write data to an HTTP endpoint.

  1. In the Properties panel, on the General tab, configure the following properties:
    General Property Description
    Name Stage name.
    Description Optional description.
    Required Fields Fields that must include data for the record to be passed into the stage.
    Tip: You might include fields that the stage uses.

    Records that do not include all required fields are processed based on the error handling configured for the pipeline.

    Preconditions Conditions that must evaluate to TRUE to allow a record to enter the stage for processing. Click Add to create additional preconditions.

    Records that do not meet all preconditions are processed based on the error handling configured for the stage.

    On Record Error Error record handling for the stage:
    • Discard - Discards the record.
    • Send to Error - Sends the record to the pipeline for error handling.
    • Stop Pipeline - Stops the pipeline. Not valid for cluster pipelines.
  2. On the HTTP tab, configure the following properties:
    HTTP Property Description
    Resource URL HTTP resource URL.
    Headers The headers to include in the request. Use the Add icon to add additional headers.
    HTTP Method HTTP request method. Use one of the standard methods or use Expression to enter an expression.
    HTTP Method Expression Expression that evaluates to a standard HTTP method.

    Used for the Expression method only.

    Request Transfer Encoding Use one of the following encoding types:
    • Buffered - The standard transfer encoding type.
    • Chunked - Transfers data in chunks. Not supported by all servers.

    The default is Chunked.

    HTTP Compression Compression format for the messages:
    • None
    • Snappy
    • Gzip
    Connect Timeout Maximum number of milliseconds to wait for a connection.

    Use 0 to wait indefinitely.

    Read Timeout Maximum number of milliseconds to wait for data.

    Use 0 to wait indefinitely.

    Maximum Parallel Requests Maximum number of requests to send to the server at one time when the destination generates one request for each record in the batch.
    One Request per Batch Enables generating a single request containing all records in the batch.
    Authentication Type Determines the authentication type used to connect to the server:
    • None - Performs no authentication.
    • Basic - Uses basic authentication. Requires a username and password.

      Use with HTTPS to avoid passing unencrypted credentials.

    • Digest - Uses digest authentication. Requires a username and password.
    • Universal - Makes an anonymous connection, then provides authentication credentials upon receiving a 401 status and a WWW-Authenticate header request.

      Requires a username and password associated with basic or digest authentication.

      Use only with servers that respond to this workflow.

    • OAuth - Uses OAuth 1.0 authentication. Requires OAuth credentials.
    Use OAuth 2 Enables using OAuth 2 authorization to request access tokens.

    You can use OAuth 2 authorization with none, basic, digest, or universal authentication.

    Use Proxy

    Enables using an HTTP proxy to connect to the system.

    Rate Limit Maximum number of requests to make per second. Set a rate limit when sending requests to a rate-limited API.

    Default is 0, which means there is no delay between requests.

    Maximum Request Time Maximum number of seconds to wait for a request to complete.
  3. When using authentication, on the Credentials tab, configure the following properties:
    Credentials Property Description
    Username User name for basic, digest, or universal authentication.
    Password Password for basic, digest, or universal authentication.
    Tip: To secure sensitive information such as usernames and passwords, you can use runtime resources or Hashicorp Vault secrets. For more information, see Using Runtime Resources or Accessing Hashicorp Vault Secrets.
    Consumer Key Consumer key for OAuth 1.0 authentication.
    Consumer Secret Consumer secret for OAuth 1.0 authentication.
    Token Consumer token for OAuth 1.0 authentication.
    Token Secret Token secret for OAuth 1.0 authentication.
  4. When using OAuth 2 authorization, on the OAuth 2 tab, configure the following properties.
    For more information about OAuth 2 and for example OAuth 2 configurations to read from Twitter, Microsoft Azure AD, or Google APIs, see OAuth 2 Authorization.
    OAuth 2 Property Description
    Credentials Grant Type Type of client credentials grant type required by the HTTP service:
    • Client credentials grant
    • Resource owner password credentials grant
    • JSON Web Tokens (JWT)
    Token URL URL to request the access token.
    Client ID Client ID that the HTTP service uses to identify the HTTP client.

    Enter for the client credentials grant that uses a client ID and secret for authentication. Or, for the resource owner password credentials grant that requires a client ID and secret.

    Client Secret Client secret that the HTTP service uses to authenticate the HTTP client.

    Enter for the client credentials grant that uses a client ID and secret for authentication. Or, for the resource owner password credentials grant that requires a client ID and secret.

    Tip: To secure sensitive information such as the client ID and secret, you can use runtime resources or Hashicorp Vault secrets. For more information, see Using Runtime Resources or Accessing Hashicorp Vault Secrets.
    User Name Resource owner user name.

    Enter for the resource owner password credentials grant.

    Password Resource owner password.

    Enter for the resource owner password credentials grant.

    Tip: To secure sensitive information such as usernames and passwords, you can use runtime resources or Hashicorp Vault secrets. For more information, see Using Runtime Resources or Accessing Hashicorp Vault Secrets.
    JWT Signing Algorithm Algorithm used to sign the JSON Web Token (JWT).

    Default is none. Enter for the JSON Web Tokens grant.

    JWT Signing Key Base64 encoded key used to sign the JSON Web Token, if you selected a signing algorithm.
    Tip: To secure sensitive information such as the JWT signing key, you can use runtime resources or Hashicorp Vault secrets. For more information, see Using Runtime Resources or Accessing Hashicorp Vault Secrets.

    Enter for the JSON Web Tokens grant.

    JWT Claims Claims to use in the JSON Web Token request, entered in JSON format. Enter each claim required by the HTTP service. You can include the expression language in the JWT claims.

    For example, to read from Google service accounts, enter the following claims with the appropriate values:

    {
      "iss":"my_name@my_account.iam.gserviceaccount.com",
      "scope":"https://www.googleapis.com/auth/drive",
      "aud":"https://www.googleapis.com/oauth2/v4/token",
      "exp":${(time:dateTimeToMilliseconds(time:now())/1000) + 50 * 60},
      "iat":${time:dateTimeToMilliseconds(time:now())/1000}
    }

    Enter for the JSON Web Tokens grant.

    Request Transfer Encoding Form of encoding to use when the stage requests an access token: buffered or chunked.

    Default is buffered.

    Additional Key-Value Pairs Optional key-value pairs to send to the token URL when requesting an access token. For example, you can define the OAuth 2 scope request parameter.

    Use the Add icon to add additional key-value pairs.

  5. To use an HTTP proxy, on the Proxy tab, configure the following properties:
    HTTP Proxy Property Description
    Proxy URI Proxy URI.
    Username Proxy user name.
    Password Proxy password.
    Tip: To secure sensitive information such as usernames and passwords, you can use runtime resources or Hashicorp Vault secrets. For more information, see Using Runtime Resources or Accessing Hashicorp Vault Secrets.
  6. To use SSL/TLS, on the TLS tab, configure the following properties:
    TLS Property Description
    Enable TLS

    Enables the use of TLS.

    Truststore File The path to the truststore file. Enter an absolute path to the file or a path relative to the Data Collector resources directory: $SDC_RESOURCES.

    For more information about environment variables, see Data Collector Environment Configuration.

    By default, no truststore is used.

    Truststore Type Type of truststore to use. Use one of the following types:
    • Java Keystore File (JKS)
    • PKCS-12 (p12 file)

    Default is Java Keystore File (JKS).

    Truststore Password Password to the truststore file. A password is optional, but recommended.
    Tip: To secure sensitive information such as passwords, you can use runtime resources or Hashicorp Vault secrets. For more information, see Using Runtime Resources or Accessing Hashicorp Vault Secrets.
    Truststore Key Algorithm The algorithm used to manage the truststore.

    Default is SunX509.

    Use Default Protocols Determines the transport layer security (TLS) protocol to use. The default protocol is TLSv1.2. To use a different protocol, clear this option.
    Transport Protocols The TLS protocols to use. To use a protocol other than the default TLSv1.2, click the Add icon and enter the protocol name.
    Note: Older protocols are not as secure as TLSv1.2.
    Use Default Cipher Suites Determines the cipher suite to use when performing the SSL/TLS handshake.

    Data Collector provides a set of cipher suites that it can use by default. For a full list, see Cipher Suites.

    Cipher Suites Cipher suites to use. To use a cipher suite that is not a part of the default set, click the Add icon and enter the name of the cipher suite.

    Enter the Java Secure Socket Extension (JSSE) name for the additional cipher suites that you want to use.

  7. On the Data Format tab, configure the following property:
    Data Format Property Description
    Data Format Data format for messages:
    • Binary
    • JSON
    • SDC Record
    • Text
  8. For binary data, on the Data Format tab, configure the following property:
    Binary Property Description
    Binary Field Path Field that contains the binary data.
  9. For JSON data, on the Data Format tab, configure the following property:
    JSON Property Description
    JSON Content Determines how JSON data is written:
    • JSON Array of Objects - Each file includes a single array. In the array, each element is a JSON representation of each record.
    • Multiple JSON Objects - Each file includes multiple JSON objects. Each object is a JSON representation of a record.
    Charset Character set to use when writing data.
  10. For text data, on the Data Format tab, configure the following properties:
    Text Property Description
    Text Field Path Field that contains the text data to be written. All data must be incorporated into the specified field.
    Record Separator Characters to use to separate records. Use any valid Java string literal. For example, when writing to Windows, you might use \r\n to separate records.

    By default, the destination uses \n.

    Insert Record Separator if No Text When a record does not include the text field, inserts the configured record separator string to create an empty line.

    When not selected, records without the text field are discarded.

    Charset Character set to use when writing data.