Link Search Menu Expand Document

HTTPS Client

Dec 6 2023 at 12:00 AM

  1. Introduction
  2. Example Options File
    1. Property Details
    2. Authorization Options
    3. Custom Api Options
    4. Authorization Types
  3. Configuration of the HTTPS data source node

Introduction

The HTTPS Client data source is designed to send an HTTPS request to the specified URL each time the device is executed. Subsequently, the payload data will be extracted and loaded from the response content.

Example Options File

{
  "Devices": {
    "Device1": {
      "DeviceType": "Generic",
      ...
      "DataSource": {
        "DataSourceType": "HttpsClient",
        "Url": "https//myserver.com/api/telemetry",
        "MethodType": "Get",
        "Headers": {
          "SomeKey": "SomeValue"
        },
        "Authorization": {
           "Authorization": "DigestAuth",
           "UserName": "MyUser",
           "Password": "MyPassword"
        }
      },
      ...
    }
  }  
}

Property Details


Here is an overview of the parameters for configuring the HTTPS Client data source:

Property NameDescription
DataSourceTypeIndicates the type of data source being utilised, and its value in this context is specified as “HttpsClient”.
UrlSpecifies the URL to which the request is sent.
MethodTypeDefines the type of request method to be used, with valid values being “Get” and “Post”. The default is set to “Get”.
HeadersA dictionary containing key, and value pairs that will be incorporated into the request headers when sending the request.
AuthorizationRefers to the authorization options, the details of which can be found in the section below.

Authorization Options


Here is an overview of the HTTPS Client Authorization Options:

Property NameDescription
AuthorizationSpecifies the type of authorization to be performed, with a default value of “None”.
AuthUrlThe authorization URL used when the “Authorization” is set to ‘OAuth2Password’, ‘OAuth2Client’, or ‘CustomApiBearerToken’.
AuthHeadersA dictionary of key, and value pairs loaded into the authorization request headers when sending the request. This is used when “Authorization” is set to ‘CustomApiBearerToken’.
ApiKeyThe API key used for authorization, This is used when “Authorization” is set to ‘ApiKey’.
UserNameThe user name for authorization. This is used when “Authorization” is set to ‘BasicAuth’, ‘DigestAuth’, ‘OAuth2Password’, or ‘CustomApiBearerToken’.
PasswordThe password for authorization. This is used when “Authorization” is set to ‘BasicAuth’, ‘DigestAuth’, ‘OAuth2Password’, or ‘CustomApiBearerToken’.
BearerTokenThe bearer token used for authorization. This is used when “Authorization” is set to ‘BearerToken’.
ClientIdThe client identifier used for authorization. This is used when “Authorization” is set to ‘OAuth2Password’ or ‘OAuth2Client’.
ClientSecretThe client secret used for authorization. This is used when “Authorization” is set to ‘OAuth2Password’ or ‘OAuth2Client’.
CustomApiOptionsRefer to the ‘Custom Api Options’ table for further details.
DisableServerCertificateValidationIf set to true, the server certificate will not undergo validation. The default is false.

Custom Api Options


Here is an overview of the HTTPS Client Custom Api Options:

Property NameDescription
RequestDocumentNameSpecifies the name of the request root document in the case of XML data.
RequestUserPathIndicates the path to the UserName property.
This will be JsonPath or XmlPath based on the chosen HTTP client type. The value corresponds to the configuration in the Authorization Options UserName property.
RequestPasswordPathRepresents the path to the Password property.
This will be JsonPath or XmlPath based on the HTTP client type. The value corresponds to the configuration in the Authorization Options Password property.
ResponseTokenPathSpecifies the path to the token value in the response.
This will be JsonPath or XmlPath depending on the type of the HTTP Client chosen.

Authorization Types


Here is an overview of the HTTPS Client Authorization Types:

Authorization TypeValueDescription
None0No authorization will be performed.
ServiceToken1Authorization via the Raptor Service Token.
ApiKey2Authorization via a provided API key. The API key is loaded into the header as a bearer token.

Required Authorization Properties:
- ApiKey
BasicAuth3Authorization via a provided User Name and Password.

Required Authorization Properties:
- UserName
- Password
UserContext4Authorization via the provided bearer token in the user HTTP context.
BearerToken5Authorization via a provided bearer token.

Required Authorization Properties:
- BearerToken
DigestAuth6Digest Authorization requires a provided User Name and Password

Required Authorization Properties:
- UserName
- Password
OAuth2Password7OAuth 2.0 authorization using Password Credentials.

Required Authorization Properties:
- AuthUrl
- UserName
- Password
- ClientId
- ClientSecret
OAuth2Client8OAuth 2.0 authorization using Client Credentials.

Required Authorization Properties:
- AuthUrl
- ClientId
- ClientSecret
CustomApiBearerToken9Authorization will be done via a bearer token that will be obtained via a call to a custom api.

Required Authorization Properties:
- AuthUrl
- AuthHeaders
- UserName
- Password
- CustomApiOptions

Configuration of the HTTPS data source node

Every device should include the Device Information, Data Source, and Filter nodes. To initiate the creation of a device, click the + icon positioned on the top-left side of the ‘Create Device’ screen as illustrated Figure 1. This action prompts a window to open, facilitating the device configuration. Within the same screen, users can select and add the necessary nodes. The ‘Add Node’ window is accessible and displayed as shown in Figure 2.

Generic Driver

Figure 1 - Create Device

The window below enables users to add and configure a data source node.

Generic Driver

Figure 2 - Add Node

The HTTPS client node consists of features to:

  1. Configure the node: Allows users to customize and adjust the settings of the selected node according to their requirements.
  2. Show nodes compatible with the selected node: Displays nodes that are compatible with the selected node, providing a streamlined view of related options.
  3. Bring up the help centre for the node: Directs users to the help centre for the selected node, offering detailed guidance and documentation.
  4. Copy icon: Permits users to duplicate the selected node, facilitating efficient replication of configurations.
  5. Delete the node: Enables users to remove the selected node from the configuration, allowing for adjustments and refining the setup.

Generic Driver

Figure 3 - Node Features

Upon selecting the Configure the node button in Figure 3, the HTTPS client data source node screen is presented as illustrated in Figure 4. Within this interface, users can input and edit relevant information.

Generic Driver

Figure 4 - HTTPS Client data source node

  1. Data Source Options: This feature enables users to establish the origin and method type of the data source.
    • Data source type
    • URL
    • Method type
    • Headers: Header key and header value
  2. Authorization Options: This feature enables users to authenticate with various clients.
    • Authorization
    • API Key
    • Username
    • Password
    • Bearer Token
  3. Disable Server Certificate Validation: This checkbox is a user interface element that, when selected, instructs the system or application to bypass the validation of server certificates during an HTTPS connection. When the Disable Server Certificate Validation checkbox is checked, it means that the usual validation process, which includes checking the certificate against a trusted authority, verifying its expiration, and ensuring its integrity, is skipped.

Continue reading