API request and response nodes-阿里云帮助中心

An online workflow uses a system-generated API request node and an API response node to define the input and output data contract for an online service. This document describes how to configure the API request node and API response node.

Prerequisites

To use the workflow and full data service features, purchase Unstructured Data - Standard Edition + Advanced Extension Pack and enable the data service feature for your instance.
You have created an online workflow. For detailed steps, see Create a workflow.

Limitations

The system automatically generates the API request node and API response node when you create an online workflow. You cannot manually add or delete them.
An online workflow can contain only one API request node and one API response node.

Configure API request node

The API request node is the root node of an online workflow. It injects request parameters from the caller into the workflow variable context for downstream operators.

Click the API request node on the canvas and configure the following parameters in the configuration pane:

Parameter	Description
Step Name	The name of the node. The default name is API Request. The name can be up to 256 characters long and can contain any characters.
Bound API	Select an API dataset and its version. You can select any submitted API dataset within the current tenant. Basic information for the selected API dataset, including its name, path, method, invocation mode, API timeout, and execution timeout, is displayed below. Click View Details for more information.
Request Parameters	The fields in the request parameters list are synchronized from the selected API dataset and cannot be modified.

After configuration, downstream operators can reference the output variables of the API request node using {api_request.<parameter_name>}, for example, {api_request.file_url}.

Configure API response node

The API response node is the leaf node of an online workflow. It uses the output from upstream operators as the HTTP response body.

Click the API response node on the canvas and configure the following parameters in the configuration pane:

Parameter	Description
Step Name	The name of the node. The default name is API Response. The name can be up to 256 characters long and can contain any characters. The API dataset selected in the API request node is displayed below and cannot be modified here. To change the API, you must create a new workflow.
Field Mapping	The field list is synchronized from the return parameters of the selected API dataset. The Parameter Name and its Type cannot be modified. You must select a Source for each field, which can be an output field from an upstream node or the Do not return this field option. For a URL-type field, use File Copy to control whether the file at the URL is copied from temporary storage to persistent storage. If enabled, the file is copied and a new URL is returned. If disabled, the original URL from temporary storage is returned. You can disable this option only for URL-type fields sourced from the API request node. For URL fields from other operators, file copying is mandatory.
View Error Code Descriptions	Click View Error Code Descriptions to view the response `code` and meaning for error codes 408, 402, 502, and 503.

Important

If any API response fields are not configured when you submit the workflow, the submission fails.
The platform runtime injects error body fields, such as code, message, and traceId. These fields are not included in the API response field list and do not require configuration.

Field mapping rules

The field mapping rules for the API response node depend on the operation type of the bound API dataset. Neither operation type supports referencing the intermediate results of sub-operators within a ForEach loop operator. You can directly reference the output results of other operators.

GET: The results field always returns a single row of data. An array output from an upstream ForEach loop operator can only be returned as a single field of type STRING, ARRAY, or OBJECT. All other fields are single-value. You cannot reference a specific element in an array by its index. To return an element with a specific business meaning, add a sorting or result processing operator after the ForEach loop operator to generate the required field, and then reference it.
List: The number of data rows returned in results matches the number of elements in the selected source array. You must first select a Result Source, which is the main array to be expanded into multiple rows. You can select any ARRAY-type field from the outputs of all reachable upstream operators on the canvas. After selection, reference fields within that array by using the array_field_name[*].field_name syntax. Each array element becomes a row of data. If you reference a single-value field, the same value is returned for all data rows. If you change the Result Source, you must reconfigure the field mappings for fields that previously referenced a different array.

The following table describes the relationship between the target parameter type and the mapping expression.

Target parameter type	Mapping expression	Description	Applicable operation type
Scalar types, such as STRING and INTEGER	`array_field_name[*].field_name`	Each element of the array is expanded into a row of data.	List
ARRAY<OBJECT>	`array_field_name`	The entire array is returned as the value of this field without being expanded.	GET, List
ARRAY<STRING>, ARRAY<INTEGER>	`array_field_name[*].field_name`	Creates an array composed of the specified field values from each element of the source array.	GET, List
Single-value types	`operator_name.field_name`	The value is used directly as the value of the field. For the List operation type, all data rows return the same value.	GET, List

Mapping change synchronization rules

When you modify and submit the bound API dataset, the system synchronizes parameter changes to the bound online workflow according to the following rules.

Change scenario	Handling policy
Add a return parameter	A new row is added to the response field list with an empty source. The workflow status changes from submitted to draft and must be resubmitted.
Delete a return parameter	The corresponding row is deleted from the response field list. If the source for this row was not empty, the system prompts that the field has been removed from the data contract and will no longer be output by this node.
Rename a parameter	The parameter is renamed. If the parameter in the API request node is referenced by other nodes, the system prompts that an upstream parameter name has changed and that you should review downstream nodes.
Change a parameter type	The type is changed. If the new type is incompatible with downstream nodes, the system reports an error.
Modify the value path	Only the display expression in the parameter name column of the response field list is updated. This does not affect the workflow status.

Asynchronous invocation mode

The field mapping for the API response node is always based on the return parameters defined in the API dataset, regardless of the invocation mode. The Data Service Gateway handles capabilities such as status polling and task retrieval for asynchronous invocation. You do not need to configure them in the workflow canvas.

When the invocation mode of the bound API dataset is asynchronous invocation, the caller must poll for the task result using the GetJobStatus API. For more information about the asynchronous invocation process, see Create an API in Direct Connection Mode (Query Type).