GetBatchImportTask-阿里云帮助中心

Queries a batch import task. The task ID is returned after a batch import task is created by calling BatchImportHttpApis. Pass an empty string to list all existing batch import tasks.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

apig:GetBatchImportTask

none

*All Resource

*

None

Request syntax

GET /v1/http-api-batch-import-tasks/{taskId} HTTP/1.1

Path Parameters

Parameter	Type	Required	Description	Example
taskId	string	Yes	The task ID. Call BatchImportHttpApis to create a batch import task first, and obtain the value of this parameter from the taskId field in the response. Pass an empty string to list all existing batch import tasks.	async-task-xxx

Request parameters

Parameter

Type

Required

Description

Example

No parameters required.

Response elements

Element	Type	Description	Example
	object	Schema of Response
requestId	string	The request ID.	CE534E1D-FCE4-5930-B784-E055EC1AEE6F
code	string	The response status code.	Ok
message	string	The response message.	success
data	object	The response data.
taskId	string	The task ID.	async-task-xxx
taskType	string	The task type.	BatchImport
status	string	The task status. Valid values: Pending, Running, Success, PartialSuccess, and Failed. Valid values: Failed : Failed. Running : Running. PartialSuccess : Partially succeeded. Pending : Pending execution. Success : Succeeded.	Running
totalCount	integer	The total count.	10
processedCount	integer	The number of processed items.	5
result	object	The task result details.
apiType	string	The API type.	Http
gatewayId	string	The gateway instance ID.	gw-xxx
dryRun	boolean	Indicates whether the task is in dry run mode.	true
importRequest	object	The formal import request body. This field is returned only for dry run tasks and can be resubmitted as the request body of BatchImportHttpApis. The dryRun parameter is fixed to false. Temporary specFileUrl values are still subject to URL expiration constraints.
specFileUrl	string	The download URL of the OAS ZIP file. This value is consistent with the dry run request.	https://oss-cn-hangzhou.aliyuncs.com/my-bucket/imports/batch.zip
specOssConfig	object	The OSS configuration for the OAS file. This value is consistent with the dry run request.
regionId	string	The region ID of the OSS bucket.	cn-hangzhou
bucketName	string	The name of the OSS bucket.	my-bucket
objectKey	string	The object key of the specification file in the OSS bucket.	imports/batch.zip
gatewayId	string	The gateway instance ID.	gw-xxx
apiType	string	The API type.	Http
strategy	string	The conflict merge strategy used during import.	ExistFirst
withGatewayExtension	boolean	Specifies whether to import with gateway extension configurations.
dryRun	boolean	Indicates whether the task is in dry run mode. This value is fixed to false in the formal import request body.	false
allowUpdate	boolean	Specifies whether to allow overwriting existing APIs.
resourceGroupId	string	The resource group ID.	rg-xxx
successItems	array<object>	The list of successfully processed APIs.
	object	The success item.
fileName	string	The file name.	petstore.yaml
apiId	string	The ID of the API.	api-xxx
apiName	string	The API name. The value unknown is returned if the name cannot be identified.	petstore
errorMessage	string	The error message.	invalid oas format
failureItems	array<object>	The list of APIs that failed to be processed.
	object	The failure item.
fileName	string	The file name.	petstore.yaml
apiId	string	The ID of the API.	api-xxx
apiName	string	The API name. The value unknown is returned if the name cannot be identified.	petstore
errorMessage	string	The error message.	invalid oas format
dryRunResults	array<object>	The list of dry run results.
	array<object>	The dry run result item.
fileName	string	The file name.	petstore.yaml
apiName	string	The API name. The value unknown is returned if the name cannot be identified.	petstore
dryRunInfo	object	The dry run details, including the operations, routes, components, and error or warning messages planned for creation or update in this file.
successOperations	array<object>	The list of REST API operations that passed the dry run.
	object	The REST API operation item that passed the dry run.
action	string	The action type to be performed after the dry run.	Create
name	string	The name of the REST API operation.	getPetById
path	string	The path of the REST API operation.	/pets/{petId}
method	string	The HTTP method of the REST API operation.	GET
failureOperations	array<object>	The list of REST API operations that failed the dry run.
	object	The REST API operation item that failed the dry run.
path	string	The path of the REST API operation.	/pets/{petId}
method	string	The HTTP method of the REST API operation.	GET
errorMessage	string	The reason for the dry run failure.	unsupported operation
successComponents	array<object>	The list of data structures that passed the dry run.
	object	The data structure item that passed the dry run.
action	string	The action type to be performed after the dry run.	Create
name	string	The name of the data structure.	Pet
failureComponents	array<object>	The list of data structures that failed the dry run.
	object	The data structure item that failed the dry run.
name	string	The name of the data structure.	Pet
errorMessage	string	The reason for the dry run failure.	invalid schema
successRoutes	array<object>	The list of routes that passed the dry run.
	object	The route item that passed the dry run.
action	string	The action type to be performed after the dry run.	Create
name	string	The name of the route.	route-pets
failureRoutes	array<object>	The list of routes that failed the dry run.
	object	The route item that failed the dry run.
name	string	The name of the route.	route-pets
errorMessage	string	The reason for the dry run failure.	domain not found
errorMessages	array	The list of dry run error messages.
	string	The dry run error message.	invalid oas format
warningMessages	array	The list of dry run warning messages.
	string	The dry run warning message.	operation will be overwritten
existHttpApiInfo	object	The basic information about the existing HTTP API matched during import.
httpApiId	string	The ID of the HTTP API.	api-xxx
name	string	The API name.	petstore
type	string	The API type.	Rest
basePath	string	The API base path.	/v1
gatewayId	string	The gateway instance ID.	gw-xxx
versionInfo	object	The API versioning information.
enable	boolean	Indicates whether versioning is enabled.	true
scheme	string	The versioning scheme.	Query
headerName	string	The key in the specified header parameter when the header versioning scheme is used.	my-version
queryName	string	The key in the specified query parameter when the query versioning scheme is used.	myVersion
version	string	The version number.	v1
error	string	The dry run error message.	unsupported oas version
errorMessage	string	The error message.	some apis import failed
createTime	string	The task creation time. The time is in UTC and follows the RFC 3339 format.	2026-05-15T10:00:00Z

Examples

Success response

JSON format

{
  "requestId": "CE534E1D-FCE4-5930-B784-E055EC1AEE6F",
  "code": "Ok",
  "message": "success",
  "data": {
    "taskId": "async-task-xxx",
    "taskType": "BatchImport",
    "status": "Running",
    "totalCount": 10,
    "processedCount": 5,
    "result": {
      "apiType": "Http",
      "gatewayId": "gw-xxx",
      "dryRun": true,
      "importRequest": {
        "specFileUrl": "https://oss-cn-hangzhou.aliyuncs.com/my-bucket/imports/batch.zip",
        "specOssConfig": {
          "regionId": "cn-hangzhou",
          "bucketName": "my-bucket",
          "objectKey": "imports/batch.zip"
        },
        "gatewayId": "gw-xxx",
        "apiType": "Http",
        "strategy": "ExistFirst",
        "withGatewayExtension": false,
        "dryRun": false,
        "allowUpdate": false,
        "resourceGroupId": "rg-xxx"
      },
      "successItems": [
        {
          "fileName": "petstore.yaml",
          "apiId": "api-xxx",
          "apiName": "petstore",
          "errorMessage": "invalid oas format"
        }
      ],
      "failureItems": [
        {
          "fileName": "petstore.yaml",
          "apiId": "api-xxx",
          "apiName": "petstore",
          "errorMessage": "invalid oas format"
        }
      ],
      "dryRunResults": [
        {
          "fileName": "petstore.yaml",
          "apiName": "petstore",
          "dryRunInfo": {
            "successOperations": [
              {
                "action": "Create",
                "name": "getPetById",
                "path": "/pets/{petId}",
                "method": "GET"
              }
            ],
            "failureOperations": [
              {
                "path": "/pets/{petId}",
                "method": "GET",
                "errorMessage": "unsupported operation"
              }
            ],
            "successComponents": [
              {
                "action": "Create",
                "name": "Pet"
              }
            ],
            "failureComponents": [
              {
                "name": "Pet",
                "errorMessage": "invalid schema"
              }
            ],
            "successRoutes": [
              {
                "action": "Create",
                "name": "route-pets"
              }
            ],
            "failureRoutes": [
              {
                "name": "route-pets",
                "errorMessage": "domain not found"
              }
            ],
            "errorMessages": [
              "invalid oas format"
            ],
            "warningMessages": [
              "operation will be overwritten"
            ],
            "existHttpApiInfo": {
              "httpApiId": "api-xxx",
              "name": "petstore",
              "type": "Rest",
              "basePath": "/v1",
              "gatewayId": "gw-xxx",
              "versionInfo": {
                "enable": true,
                "scheme": "Query",
                "headerName": "my-version",
                "queryName": "myVersion",
                "version": "v1"
              }
            }
          },
          "error": "unsupported oas version"
        }
      ]
    },
    "errorMessage": "some apis import failed",
    "createTime": "2026-05-15T10:00:00Z"
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.