非同期 API オペレーションの仕組み - Intelligent Media Management

IMM はさまざまなデータ出力操作をサポートしています。これらの操作の中には実行時間が長く、単一の同期リクエスト内で結果を返せないものがあります。このようなケースに対応するため、IMM では CreateXXXTask 形式の非同期 API オペレーションと、結果を取得するための通知メカニズムを提供しています。

説明

IMM の非同期 API オペレーションは、単一の同期リクエストで結果を返せない長時間実行ジョブ向けに設計されています。この非同期アプローチにより、クライアントのブロッキングを回避し、システムパフォーマンスを向上させるとともに、リソース集約型またはスケジュールされたジョブをバックグラウンドで実行してユーザーエクスペリエンスに影響を与えないようにします。

仕組み

ご利用のソースデータを Alibaba Cloud Object Storage Service (OSS) にアップロードします。
CreateXXXTask などの IMM API オペレーションを呼び出して、非同期タスクを開始します。
IMM は指定された OSS URI からソースデータを取得して処理します。
IMM は処理結果を指定された OSS URI に書き込みます。
タスクが完了すると、IMM はタスクステータスを指定された MNS または ApsaraMQ for RocketMQ のトピックに送信します。
MNS または ApsaraMQ for RocketMQ は、通知メッセージをアプリケーションまたはサービスにプッシュします。

タスクの入力と出力

入力データのパラメーターには通常、Source というプレフィックスが付きます。利用可能なパラメーターは以下のとおりです。
- SourceURI：入力データの場所。OSS URI のみがサポートされます。
- Sources：複数の入力 URI を含む配列。
- Source：複数の入力 URI を含むオブジェクト。
出力データのパラメーターには通常、Target というプレフィックスが付きます。利用可能なパラメーターは以下のとおりです。
- TargetURI：出力の送信先。このパラメーターはテンプレート構文をサポートします。
- TargetURIPrefix：出力送信先 URI のプレフィックス。
- Target：複数の出力 URI を含むオブジェクト。

重要

入力データおよび出力データは、IMM サービスと同じリージョン内にある必要があります。

OSS URI

OSS URI は OSS 内のリソースを一意に識別し、oss://<bucket>/<object> という形式を使用します（例：oss://test-bucket/test-object/test.docx）。

説明

<bucket> はプロジェクトと同じリージョンにある OSS バケットの名前です。<object> は拡張子を含むファイルの完全なパスです。

一般的な無効な形式は以下のとおりです。

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

`TargetURI` テンプレート

TargetURI テンプレートを使用すると、URI 内にプレースホルダーを記述できます。これらのプレースホルダーはランタイム時に実際の値に置き換えられ、最終的な出力 URI が動的に生成されます。例：oss://{bucket}/{tags.custom}/{dirname}/{barename}.{autoext}。

詳細については、「TargetURI テンプレート」をご参照ください。

認可

非同期タスクでは、IMM が指定された場所から入力データを読み取り、出力データを書き込むための権限を付与する必要があります。これらの権限は、リクエスト内の プロジェクト名 パラメーターによって決定されます。このパラメーターはプロジェクトとその関連付けられたサービリンクロールを識別します。Create Project API オペレーションの サービスロール パラメーターを使用して、プロジェクト用のこのロールを指定します。デフォルトでは、サービスを有効化した際に自動作成される AliyunIMMDefaultRole が使用されます。タスク処理中、IMM はこのロールを偽装してデータにアクセスします。

タスクステータスの取得

MNS または ApsaraMQ for RocketMQ を使用する場合

「仕組み」セクションで説明したとおり、MNS または ApsaraMQ for RocketMQ を設定して IMM タスクステータスの通知を受信できます。この方法が推奨されます。通知フォーマットの詳細については、「非同期通知メッセージフォーマット」をご参照ください。

重要

MNS または ApsaraMQ for RocketMQ は IMM と同じリージョン内にある必要があります。

（推奨）Notification パラメーターを使用して、非同期通知用の MNS または ApsaraMQ for RocketMQ の構成を指定します。
- MNS：Notification パラメーター内の MNS フィールドを使用して、MNS エンドポイントとトピックを指定します。
```
{
  "Notification": {
    "MNS": {
      "Endpoint": "The MNS endpoint",
      "TopicName": "The MNS topic"
    }
  }
}
```
- ApsaraMQ for RocketMQ：Notification パラメーター内の RocketMQ フィールドを使用して、ApsaraMQ for RocketMQ のエンドポイント、トピック、インスタンス ID を指定します。
```
{
  "Notification": {
    "RocketMQ": {
      "Endpoint": "The ApsaraMQ for RocketMQ endpoint",
      "TopicName": "The ApsaraMQ for RocketMQ topic",
      "InstanceId": "The ApsaraMQ for RocketMQ instance ID"
    }
  }
}
```
NotifyEndpoint パラメーターおよび NotifyTopicName パラメーターを使用して、非同期メッセージ通知を受信するための MNS エンドポイントとトピックを指定します。
- NotifyEndpoint：通知を受信するための MNS エンドポイント。デフォルトでは、呼び出し元の MNS エンドポイントが使用されます。
- NotifyTopicName：MNS トピックの名前。このパラメーターを空のままにすると、通知は送信されません。

GetTask API を使用する場合

IMM はタスクのステータスを照会するための GetTask API オペレーションも提供しています。

GetTask API オペレーションを繰り返し呼び出してポーリングを行い、タスクが完了するまでステータスを確認することも可能ですが、この方法は非効率であり、本番環境では推奨されません。長時間実行タスクの場合、多数の GetTask 呼び出しが発生する可能性があります。多くのタスクがキューイングされている場合、グローバル速度制限がトリガーされ、他の API 呼び出しに影響を及ぼすことがあります。さらに、ポーリングには遅延が伴います。タスクはポーリング間隔の任意のタイミングで完了しますが、次のポーリングまで完了を検知できず、平均してポーリング間隔の半分に相当する遅延が生じます。

説明

タスク情報はタスク開始後 7 日間のみ保持され、その後は取得できなくなります。

タグの使用

リクエスト内のタグパラメーターを使用すると、タスクにタグを付与できます。タグは以下の用途で使用できます。

タグによるタスクの検索。
TargetURI テンプレート内で変数としてタグを使用。