How asynchronous API operations work - Intelligent Media Management

IMM supports various data output operations. Some of these operations are long-running and cannot return results within a single synchronous request. To handle these cases, IMM provides asynchronous API operations, typically named in the CreateXXXTask format, and a notification mechanism for retrieving results.

Note

The asynchronous API operations in IMM are designed for long-running jobs that cannot return results in a single synchronous request. This asynchronous approach prevents client blocking, improves system performance, and runs resource-intensive or scheduled jobs in the background without affecting the user experience.

How it works

Upload your source data to Alibaba Cloud Object Storage Service (OSS).
Call an IMM API operation, such as CreateXXXTask, to initiate an asynchronous task.
IMM retrieves and processes the source data from the specified OSS URI.
IMM writes the processing results to the specified OSS URI.
After the task is complete, IMM sends the task status to your specified MNS or ApsaraMQ for RocketMQ topic.
MNS or ApsaraMQ for RocketMQ then pushes the notification message to your application or service.

Task input and output

Input data parameters are typically prefixed with Source. The following parameters are available:
- SourceURI: The location of the input data. Only OSS URIs are supported.
- Sources: An array of multiple input URIs.
- Source: An object containing multiple input URIs.
Output data parameters are typically prefixed with Target. The following parameters are available:
- TargetURI: The destination for the output. This parameter supports template syntax.
- TargetURIPrefix: The prefix for the output destination URI.
- Target: An object containing multiple output URIs.

Important

The input and output data must be in the same region as the IMM service.

OSS URI

An OSS URI uniquely identifies a resource in OSS and uses the format oss://<bucket>/<object>, for example, oss://test-bucket/test-object/test.docx.

Note

<bucket> is the name of an OSS bucket in the same region as your project. <object> is the full path to the file, including its extension.

Common invalid formats include:

http://bucket.oss-cn-hangzhou.aliyuncs.com/test-object/test.docx
oss://bucket.oss-cn-hangzhou.aliyuncs.com/test-object/test.docx

TargetURI template

A TargetURI template allows you to use placeholders in a URI. These placeholders are replaced with actual values at runtime to dynamically generate the final output URI. For example: oss://{bucket}/{tags.custom}/{dirname}/{barename}.{autoext}.

For more information, see TargetURI template.

Authorization

For an asynchronous task, you must grant IMM permissions to read input data from and write output data to the locations you provide. These permissions are determined by the Project Name parameter in your request, which identifies the project and its associated service-link role. You specify this role for the project using the Service Role parameter in the Create Project API operation. By default, the AliyunIMMDefaultRole is used, which is automatically created when you activate the service. During task processing, IMM assumes this role to access your data.

Getting task status

Using MNS or ApsaraMQ for RocketMQ

As described in the How it works section, you can configure MNS or ApsaraMQ for RocketMQ to receive IMM task status notifications. This is the recommended method. For details on the notification format, see Asynchronous notification message format.

Important

MNS or ApsaraMQ for RocketMQ must be in the same region as IMM.

(Recommended) Use the Notification parameter to specify the MNS or ApsaraMQ for RocketMQ configuration for asynchronous notifications.
- MNS: Use the MNS field in the Notification parameter to specify the MNS endpoint and topic.
```
{
  "Notification": {
    "MNS": {
      "Endpoint": "The MNS endpoint",
      "TopicName": "The MNS topic"
    }
  }
}
```
- ApsaraMQ for RocketMQ: Use the RocketMQ field in the Notification parameter to specify the ApsaraMQ for RocketMQ endpoint, topic, and instance ID.
```
{
  "Notification": {
    "RocketMQ": {
      "Endpoint": "The ApsaraMQ for RocketMQ endpoint",
      "TopicName": "The ApsaraMQ for RocketMQ topic",
      "InstanceId": "The ApsaraMQ for RocketMQ instance ID"
    }
  }
}
```
Use the NotifyEndpoint and NotifyTopicName parameters to specify the MNS endpoint and topic for receiving asynchronous message notifications.
- NotifyEndpoint: The MNS endpoint for receiving notifications. By default, this is the MNS endpoint of the caller.
- NotifyTopicName: The name of the MNS topic. If this parameter is left empty, no notifications are sent.

Using the GetTask API

IMM also provides the GetTask API operation to query the status of a task.

While you can repeatedly call the GetTask API operation to poll a task's status until it completes, this method is inefficient and not recommended for production environments. For long-running tasks, polling can result in a large number of GetTask calls. If many tasks are queued, this may trigger global throttling and affect other API calls. Furthermore, polling introduces latency. A task may finish at any time between polls, but you will not learn of its completion until the next poll, introducing an average delay of half the polling interval.

Note

Task information is retained for only 7 days after a task starts, after which it can no longer be retrieved.

Using tags

The Tags parameter in your request lets you tag a task. You can use tags in the following ways:

Search for tasks by tag.
Use tags as variables in a TargetURI template.