Calling Third-Party APIs with Custom Connectors

Scenario

You can use Huawei Cloud Astro Zero custom connectors, flows, or events to quickly connect to external service APIs. For example, you can connect to an existing RESTful service, obtain and process data through the RESTful service, and use the data in Huawei Cloud Astro Zero.

{
"request": "value"
}

{
"response": "value"
}

Procedure

Figure 1 shows the process of using a custom connector to call third-party APIs.

Figure 1 Process

Step 1: Creating a Custom Connector

1. Log in to the application designer by referring to Logging In to the Application Designer.
2. In the navigation pane, choose Integrations.
3. Click Connector Instance under Connector.
4. In the Type area, select Custom Connector.
5. Click +, configure the connector information, and click Save.
   Figure 2 Creating a custom connector
   

   Table 2 Parameters for creating a custom connector

   Parameter	Description
   Label	Custom connector label, which can be modified after being created. Value: 1–64 characters.
   Name	Custom connector name, which uniquely identifies the connector in the system and cannot be changed after the connector is created. The naming requirements are as follows: The value cannot exceed 64 characters, including the prefix namespace. To prevent duplicate data names among different tenants, each tenant must define a unique namespace when first creating an application. A tenant can create only one namespace. After being created, the namespace cannot be modified. Start with a letter and can contain only letters, digits, and underscores (_). Do not end with an underscore (_).
   Logo	Custom connector logo. You can upload an image from the local host.
   Description	Enter the description of the custom connector. Value: 1–255 characters.

6. On the Action tab page, create a custom connector action, set basic information about the action, and click Next.
   Figure 3 Setting basic information
   

   Table 3 Parameters for creating an action

   Parameter	Description
   Label	Action label, which is displayed on the page. Value: 1–64 characters.
   Name	Action name, which uniquely identifies the action in the system. The naming requirements are as follows: The value cannot exceed 64 characters, including the prefix namespace. To prevent duplicate data names among different tenants, each tenant must define a unique namespace when first creating an application. A tenant can create only one namespace. After being created, the namespace cannot be modified. Start with a letter and can contain only letters, digits, and underscores (_). Do not end with an underscore (_).
   URL	URL of the RESTful service provided by the third-party system. For example, /path/test (the host address needs to be configured for authentication information), http://www.domain name .com, or http://system parameter.
   Method	Select a method from the drop-down list. GET: obtains resources. POST: creates resources. PUT: updates resources. PATCH: updates parts of resources. DELETE: deletes resources. OPTIONS: obtains the method supported by the current URL. When Method is set to PUT or POST, you can customize input parameters of the message body. If the input parameters are of the array or non-JSON type, set them to the key-value format. When you select Key-Value for Message body format, a common variable $in, will be introduced. Array or non-JSON variables will be saved to $in, converted to the key-value format, and passed to the RESTful action.
   Content Type	The value depends on the content type supported by the third-party system and is defined in HTTP. application/json application/x-www-form-urlencoded application/xml multipart/form-data text/html text/plain
   Return Type	Return type of the API. The options are application/json and text/event-stream. If this parameter is not set (that is, the value is empty), the Content-Type in the HTTP response is used to parse the content returned by the third-party system. application/json: If selected, the system ignores the Content-Type returned by the third-party system and uses the Content-Type configured for the third-party system to parse the returned content. text/event-stream: If selected, the returned value of the API is processed as a streaming packet. Ensure that the third-party API returns streaming packets and sets the Content-Type to text/event-stream.
   Timeout	If the third-party system does not return any result within the specified period, an error will be reported. Unit: second.
   Date Format	If the input parameters of the RESTful service include a parameter of the Date type in a specified format, this parameter is mandatory. Ensure that the input parameters provided by Huawei Cloud Astro Zero meet the third-party requirements. For example, if the RESTful service has an input parameter of the Date type and the format is YYYY-MM-DD, set this parameter to YYYY-MM-DD.
   Date/Time Format	If the input parameters of the RESTful service include a parameter of the DateTime type in a specified format, this parameter is mandatory. Ensure that the input parameters provided by Huawei Cloud Astro Zero meet the third-party requirements. For example, if the RESTful service has an input parameter of the DateTime type and the format is YYYY-MM-DD hh:mm:ss, set this parameter to YYYY-MM-DD hh:mm:ss.
   Disable Request Header Normalization	Whether to disable request header normalization. If this parameter is selected, 'accept-language' will not be normalized to 'Access-Language'. This parameter is deselected by default.
   Disable HTML Character Escaping	Whether to disable HTML character escaping in the JSON request body, such as & and <>. If this parameter is selected, '&' will not be escaped to '\u0026'. This parameter is deselected by default.
   Description	Enter the action description as required. Value: 1–255 characters.

7. Click Next to configure the header input parameter.

   If this API does not have header input parameters, click to delete the first row. If there are multiple message header input parameters, click to copy them.

   Figure 4 Header input parameter configuration page
   

   Table 4 Parameters on the header input parameter configuration page

   Parameter	Description
   Label	Label of a message header input parameter, which is displayed on the page.
   Name	Unique name of a header input parameter.
   Data Type	Data type of a header input parameter. The options are as follows: Number String Boolean Sensitive Text
   Default Value	Default value of the header input parameter. You can customize the value only after selecting Default.
   Description	Enter the description of the input parameter.
   Default	Indicates whether the input parameter of the header has a default value. If this parameter is selected, you can customize the value in Default Value. If Data Type is set to Sensitive Text, the default value cannot be set.
   Required	Indicates whether the input parameter of the header is mandatory.
   Operation	Click or to copy or delete the header input parameter.

8. Click Next to configure the input parameter.

   This step configures the request path or content corresponding to the message body. Placement determines whether the parameter is a path parameter or a message body parameter.

   In this example, set the URL query parameter to key and the request body parameter to request. For details about the parameters, see Table 5.

   Figure 5 Page for configuring the input parameter
   

   Table 5 Input parameter description

   Parameter	Description
   Label	Label of an input parameter, which is displayed on the page.
   Name	Name of an input parameter, which uniquely identifies the input parameter in the system.
   Placement	Position of the input parameter. The options are as follows: Body URL Query URL Path
   Data Type	Data type of the input parameter. The options are as follows: Date: accurate to days. Date Time: accurate to seconds. Number: The value is a number. String Boolean: Only two values are allowed, for example, true and false. External Struct Map Object: Object identifier type. Sensitive Text: Such as name or mobile number.
   Namespace	If DataType is set to External Struct, you need to set the namespace to which the input parameter belongs.
   Metadata Name	When the data type is set to object, you need to select the metadata name, that is, the custom object created in the application.
   Default Value	Sets the default value of an input parameter.
   Description	Enter the description of the input parameter. Value: 1–255 characters.
   Default	Indicates whether an input parameter has a default value. If this parameter is selected, you can customize the value in Default Value. If DataType is set to Sensitive Text, the default value cannot be set.
   Required	Indicates whether an input parameter is mandatory.
   Collection	Whether the input parameter is set to the array type.
   Operation	Click or to copy or delete the input parameter.

9. Configure output parameters and click Save.

   Output parameter, which depends on the value of Placement, may come from the response header or request header. In this example, the response body contains a response parameter.

   Figure 6 Page for configuring output parameters
   

   Table 6 Parameters for configuring output parameters

   Parameter	Description
   Label	Label of an output parameter, which is displayed on the page.
   Name	Name of an output parameter, which uniquely identifies the output parameter in the system.
   Placement	Position of the output parameter. The options are as follows: Header Body
   Data Type	Data type of the output parameter. The options are as follows: Date: The value is accurate to day. Date/Time: time type, accurate to second. Number: The value is a number. Character string: The value is a character string. Boolean: The value is true or false. Global structure Key-value pair (Map): Map collection type. Object: Object identifier type.
   Namespace	If the data type is set to global structure, you need to set the namespace to which the parameter belongs.
   Metadata Name	When the data type is set to object, you need to select the metadata name, that is, the custom object created in the application.
   Description	Description of the parameter.
   Collection	Whether the input parameter is set to the array type.
   Operation	Click or to copy or delete the parameter.

10. On the Action tab page, click in the row where the action is located to enable the action.

Step 2: Configuring Connector Authentication Information

Before calling a custom connector in flows or events, you need to configure authentication information.

1. Go to the custom connector page by referring to Step 1: Creating a Custom Connector.
2. On the Authentication Information tab page, click New.
3. Set authentication information and click Save.
   Huawei Cloud Astro Zero provides various authentication types for you to select. Configure authentication information based on your service requirements.

   Figure 7 Adding authentication information - basic information
   
   Figure 8 Adding authentication information - authentication settings
   

   Table 7 Parameters for adding authentication information

   Parameter	Description
   Label	Authentication label, which is displayed on the page. Value: 1–64 characters.
   Name	Authentication name, which uniquely identifies the authentication in the system. The naming requirements are as follows: The value cannot exceed 64 characters, including the prefix namespace. To prevent duplicate data names among different tenants, each tenant must define a unique namespace when first creating an application. A tenant can create only one namespace. After being created, the namespace cannot be modified. Start with a letter and can contain only letters, digits, and underscores (_). Do not end with an underscore (_).
   Category	Category to which the authentication belongs.
   Description	Enter the authentication description as required. Value: 1–255 characters.
   Use Certificate	Whether the client certificate is required on the server and whether bidirectional authentication is required. If this parameter is selected, you need to configure the Type, Certificate, and Key. This parameter is selected by default.
   Type	This parameter is displayed only when Use Certificate is selected. Type of the certificate. The value can be CRT or P12.
   Certificate	This parameter is displayed only when Use Certificate is selected. Upload the CRT or P12 certificate from the local PC.
   Key	This parameter is displayed only when Use Certificate is selected. Enter the access key of the uploaded certificate.
   Use Root Certificate	Whether the server certificate is required on the client and whether bidirectional authentication is required. If this parameter is selected, you need to enable root certificate verification and upload the root certificate in advance. For details, see Enabling Root Certificate Authentication for Server Identity Verification. After the upload, select the corresponding certificate from the Root Certificate drop-down list.
   API Host Address	After this parameter is configured, only RESTful operation requests whose request URL starts with the specified address will be allowed. This prevents leakage of sensitive information. Each time the address is changed, the authentication information needs to be reconfigured.
   Package Current Configuration	If this parameter is selected, the connector will be packed together with applications. For example, if an application package is released to the runtime environment, the current configuration is synchronized to the runtime environment by default. This parameter is selected by default. You are advised not to select this option in information-sensitive scenarios.
   Authentication Setting	Auth Protocol: Authentication protocol. The options are OAuth, Simple headers, and JWT. Auth Mode: Set it to client credentials. Only client credentials of OAuth 2.0 are supported. Auth Address: Address for a third-party system to obtain the token through the OAuth 2.0 protocol. An example address to obtain a token is https://{host}:{port}/baas/auth/v1.0/oauth2/token. Client ID: Client ID in the OAuth 2.0 protocol. If the REST service is provided by Huawei Cloud Astro Zero, obtain the client ID by referring to Access Authentication with Client Credentials. Client Secret: Client secret in the OAuth 2.0 protocol. If the REST service is provided by Huawei Cloud Astro Zero, obtain the client secret by referring to Access Authentication with Client Credentials.
   Body Property	Mapping rules for message fields returned from authentication APIs. Figure 9 describes the response body based on the OAuth2 standard protocol. The key returned by some third-party APIs may not be the standard key. For example, some third-party APIs will return accessToken instead of access_token used in Astro Zero. Therefore, you need to configure the mapping between the keys. The message body property configured in Figure 8 is accessToken returned by a third-party system. Huawei Cloud Astro Zero uses the access_token key value to store the message body property. The final storage result is as follows: { "access_token": ${accessToken} }
   Header Property	Mapping rules for message headers in requests to service APIs. According to OAuth 2.0, the token is put in the request header: Authorization: Bearer ${access_token}. However, some APIs do not comply with this rule. For example, for an API used to access the platform, the token is put in the request header Access-Token and does not need the prefix Bearer. The message header property configured in Figure 8 indicates that you need to obtain the value of access_token from the message body and put the value in the request header Access-Token.

   Figure 9 Response body
   

Step 3: Calling a Custom Connector Using a Flow

Create a flow. Then, call the created custom connector using the flow, and use the data processed by the RESTful service in Huawei Cloud Astro Zero.

1. Log in to the application designer by referring to Logging In to the Application Designer.
2. In the navigation pane, choose Logic.
3. Click next to Flow. On the displayed dialog box, specify the flow label and name and click Add.
   Figure 10 Adding a flow
   

4. In the navigation pane of the flow designer page, choose Connector > Custom > Service name, and drag the RESTful service icon created in Step 1: Creating a Custom Connector to the canvas.

   Ensure that authentication information (such as Step 2: Configuring Connector Authentication Information) has been added to the custom connector. Otherwise, the custom connector cannot be dragged.

5. Configure the action to be called.
   Figure 11 Configuring the action to be called
   

6. Click in the upper part of the flow designer page to save the flow.
7. Click to activate the flow.

   If the RESTful service fails to be called, click Tracer on the toolbar to view run logs. For example, the most common gateway is unreachable.

   Figure 12 Gateway unreachable
   

   After the flow is debugged successfully, you can apply the flow to your service logic.

Related Documents

You can use a custom connector to integrate a third-party database into Huawei Cloud Astro Zero. For details, see Connecting to Third-Party Databases with a Connector.