SubmitSnapshotJob API による非同期スナップショットの自動化 - ApsaraVideo MPS - Alibaba Cloud - ApsaraVideo Media Processing

スナップショットジョブを送信します。Media Processing Service (MPS) は、入力ファイルからスクリーンショットを取得し、スプライトイメージを生成します。

操作説明

単一の入力ファイルの最大サイズは 100 GB です。この制限を超えると、ジョブが失敗する可能性があります。
スナップショットジョブを送信する前に、ファイルが OSS に正常にアップロードされていることを確認してください。そうでない場合、ジョブが失敗する可能性があります。OSS コールバックを設定して、ファイルのアップロードステータスを確認できます。
スナップショットジョブは、同期モードと非同期モードの両方をサポートしています。
- 同期モードは単一のスナップショットのみをサポートし、API 呼び出しが返されたときにイメージを生成します。
- 非同期モードでは、即時処理は保証されません。スナップショットジョブを送信すると、ジョブはパイプラインに追加され、キューイングされて実行がスケジュールされます。そのため、API 呼び出しが返されたときにスナップショットが生成されるとは限りません。ジョブが完了した後、スナップショットジョブの結果のクエリ API を呼び出して結果をポーリングするか、パイプラインに Message Service (MNS) をバインドしてメッセージ通知を受信できます。詳細については、「メッセージ通知の受信」をご参照ください。
- Interval または Num パラメーターを指定すると、非同期モードがトリガーされます。
現在、JPG フォーマットのイメージのみがサポートされています。
スナップショットに関する一般的な問題の詳細については、「スナップショットに関するよくある質問」をご参照ください。

QPS 制限

この API の QPS 制限は、ユーザーあたり毎秒 50 リクエストです。この制限を超える API 呼び出しは速度制限の対象となり、ビジネスに影響を与える可能性があります。この API は適切なレートで呼び出してください。詳細については、「QPS 制限」をご参照ください。

今すぐお試しください

この API を OpenAPI Explorer でお試しください。手作業による署名は必要ありません。呼び出しに成功すると、入力したパラメーターに基づき、資格情報が組み込まれた SDK コードが自動的に生成されます。このコードをダウンロードしてローカルで使用できます。

テスト

RAM 認証

下表に、この API を呼び出すために必要な認証情報を示します。認証情報は、RAM (Resource Access Management) ポリシーを使用して定義できます。以下で各列名について説明します。

アクション：特定のリソースに対して実行可能な操作。ポリシー構文ではAction要素として指定します。
API：アクションを具体的に実行するための API。
アクセスレベル：各 API に対して事前定義されているアクセスの種類。有効な値：create、list、get、update、delete。
リソースタイプ：アクションが作用するリソースの種類。リソースレベルでの権限をサポートするかどうかを示すことができます。ポリシーの有効性を確保するため、アクションの対象として適切なリソースを指定してください。
- リソースレベルの権限を持つ API の場合、必要なリソースタイプはアスタリスク (*) でマークされます。ポリシーのResource要素で対応する ARN を指定してください。
- リソースレベルの権限を持たない API の場合、「すべてのリソース」と表示され、ポリシーのResource要素でアスタリスク (*) でマークされます。
条件キー：サービスによって定義された条件のキー。このキーにより、きめ細やかなアクセス制御が可能になります。この制御は、アクション単体に適用することも、特定のリソースに対するアクションに適用することもできます。Alibaba Cloud は、サービス固有の条件キーに加えて、すべての RAM 統合サービスに適用可能な一連の共通条件キーを提供しています。
依存アクション：ある特定のアクションを実行するために、前提として実行が必要となる他のアクション。依存アクションの権限も RAM ユーザーまたは RAM ロールに付与する必要があります。

アクション

アクセスレベル

リソースタイプ

条件キー

依存アクション

mts:SubmitSnapshotJob

create

*All Resource

*

なし

リクエストパラメーター

パラメーター	型	必須 / 任意	説明	例
Input	string	必須	ジョブ入力。詳細については、「入力」をご参照ください。説明 ApsaraVideo for Media Processing (MPS) API では、`Object` の値を UTF-8 で URL エンコードする必要があります。 OSS リージョンは MPS リージョンと同じである必要があります。	{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"}
SnapshotConfig	string	必須	スナップショット設定。詳細については、「SnapshotConfig」をご参照ください。	{"OutputFile":{"Bucket":"example-001","Location":"example-location","Object":"{Count}.jpg"},"Time":"5","Num":"10","Interval":"20"}
UserData	string	任意	カスタムデータ。値には文字、数字、ハイフン (-) を含めることができますが、特殊文字で始めることはできません。値の長さは最大 1,024 バイトです。	testid-001
PipelineId	string	任意	MPS キューの ID。詳細については、「基本概念」をご参照ください。 MPS コンソールで [グローバル設定] > [パイプライン] を選択して、MPS キューを表示または作成できます。非同期通知を受信するには、MNS キューを MPS キューにバインドする必要があります。詳細については、「メッセージ通知の受信」をご参照ください。	dd3dae411e704030b921e52698e5****

レスポンスフィールド

フィールド	型	説明	例
	object	レスポンスパラメーター。
RequestId	string	リクエスト ID。	19B6D8C5-A5DD-467A-B435-29D393C71E2D
SnapshotJob	object	スナップショットジョブ。
CreationTime	string	ジョブが作成された時刻。	2021-05-19T03:11:48Z
SnapshotConfig	object	スナップショット設定。
Time	string	スナップショットの開始時刻。単位：ミリ秒。	5
TileOut	object	タイル設定。
Padding	string	イメージ間のパディング。デフォルト値：0。単位：ピクセル。	0
Color	string	背景色。デフォルト値：black。有効な値：色のキーワードまたは random。説明色のキーワードは 3 つのフォーマットで指定できます。たとえば、黒を指定するには、`Black`、`black`、または `#000000` を使用できます。	black
CellSelStep	string	タイル出力に含める個々のイメージを選択するためのステップ。	3
CellHeight	string	タイル出力における個々のイメージの高さ。デフォルトでは、出力スナップショットの高さになります。	100
CellWidth	string	タイル出力における個々のイメージの幅。デフォルトでは、出力スナップショットの幅になります。	100
Margin	string	タイル画像の外部マージンの幅。デフォルト値：0。単位：ピクセル。	5
Columns	string	タイル画像の列数。デフォルト値：10。	10
IsKeepCellPic	string	個々のスナップショットを保持するかどうかを指定します。有効な値： true：個々のスナップショットを保持します。 false：個々のスナップショットを削除します。デフォルト値：true。	false
Lines	string	タイル画像の行数。デフォルト値：10。	10
Interval	string	連続したスナップショットをキャプチャする間隔。値は 0 より大きい必要があります。単位：秒。デフォルト値：10。	20
FrameType	string	キャプチャするフレームの種類。デフォルト値：normal。有効な値： normal：通常フレーム。 intra：I フレーム (キーフレーム)。説明このパラメーターを `intra` に設定すると、キーフレームのみがキャプチャされます。指定された時点がキーフレームでない場合、システムは最も近いキーフレームを使用します。キーフレームのキャプチャは、通常フレームのキャプチャよりも高速です。	intra
Width	string	出力スナップショットの幅。	8
Height	string	出力スナップショットの高さ。	8
OutputFile	object	出力スナップショットの OSS 設定。
RoleArn	string	ロールの ARN。フォーマット：`acs:ram::$accountID:role/$roleName`。	acs:ram::1:role/testrole
Object	string	出力 OSS オブジェクトの名前。	test.png
Location	string	出力 OSS バケットのデータセンター。	example-location
Bucket	string	出力ファイルの OSS バケット。	example
Num	string	シーケンスでキャプチャするスナップショットの数。	10
TileOutputFile	object	出力タイル画像の OSS 設定。
RoleArn	string	ロールの ARN。フォーマット：`acs:ram::$accountID:role/$roleName`。	acs:ram::1:role/testrole
Object	string	出力 OSS オブジェクトの名前。	example.png
Location	string	出力 OSS バケットのデータセンター。	example-location
Bucket	string	出力ファイルの OSS バケット。	example
TimeArray	object
TimePointList	array	タイムポイントの配列。
	integer	スナップショットをキャプチャする最大 100 個の時系列ポイント (ミリ秒単位) の配列。値は、小数点以下 2 桁までの浮動小数点数にすることができます。時系列ポイントは任意の順序で送信でき、重複を含めることもできます。MPS は自動的にソートします。このパラメーターを指定する場合、`Num`、`Time`、または `Interval` パラメーターは使用しないでください。使用した場合、API は `InvalidParameter.Ambiguity` エラーを返します。	[10050, 50000, 110000, 1000500, 1100500]
State	string	スナップショットジョブの状態。有効な値： Submitted：ジョブは送信済みです。 Snapshotting：スナップショットジョブは進行中です。 Success：ジョブは成功しました。 Fail：ジョブは失敗しました。	Snapshoting
Message	string	エラーメッセージ。このパラメーターは、ジョブが失敗した場合にのみ返されます。	The resource operated InputFile is bad
MNSMessageResult	object	ジョブ完了時にユーザーに送信された MNS 通知の結果。
MessageId	string	MNS メッセージの ID。このパラメーターは、通知が成功した場合にのみ返されます。	799454621135656C7F815F198A76****
ErrorMessage	string	エラーメッセージ。MNS 通知が失敗した場合にのみ返されます。	The resource operated InputFile is bad
ErrorCode	string	エラーコード。MNS 通知が失敗した場合にのみ返されます。	InvalidParameter
Input	object	ジョブ入力。
RoleArn	string	ロールの ARN。フォーマット：`acs:ram::$accountID:role/$roleName`。	acs:ram::1:role/testrole
Object	string	入力 OSS オブジェクトの名前。	example.flv
Location	string	入力 OSS バケットのデータセンター。	example-location'
Bucket	string	入力ファイルを含む OSS バケット。	example
Count	string	キャプチャされたスナップショットの総数。	1
TileCount	string	タイル画像の数。	5
UserData	string	ユーザー定義データ。	testid-001
Code	string	エラーコード。このパラメーターは、ジョブのステータスが Fail の場合にのみ返されます。	ResourceContentBad
PipelineId	string	パイプライン ID。	dd3dae411e704030b921e52698e5****
Id	string	スナップショットジョブの ID。	f4e3b9ba9f3840c39d6e288056f0****

例

成功レスポンス

JSONJSON

{
  "RequestId": "19B6D8C5-A5DD-467A-B435-29D393C71E2D",
  "SnapshotJob": {
    "CreationTime": "2021-05-19T03:11:48Z",
    "SnapshotConfig": {
      "Time": "5",
      "TileOut": {
        "Padding": "0",
        "Color": "black",
        "CellSelStep": "3",
        "CellHeight": "100",
        "CellWidth": "100",
        "Margin": "5",
        "Columns": "10",
        "IsKeepCellPic": "false",
        "Lines": "10"
      },
      "Interval": "20",
      "FrameType": "intra",
      "Width": "8",
      "Height": "8",
      "OutputFile": {
        "RoleArn": "acs:ram::1:role/testrole",
        "Object": "test.png",
        "Location": "example-location",
        "Bucket": "example"
      },
      "Num": "10",
      "TileOutputFile": {
        "RoleArn": "acs:ram::1:role/testrole",
        "Object": "example.png",
        "Location": "example-location",
        "Bucket": "example"
      },
      "TimeArray": {
        "TimePointList": [
          0
        ]
      }
    },
    "State": "Snapshoting",
    "Message": "The resource operated InputFile is bad",
    "MNSMessageResult": {
      "MessageId": "799454621135656C7F815F198A76****",
      "ErrorMessage": "The resource operated InputFile is bad",
      "ErrorCode": "InvalidParameter"
    },
    "Input": {
      "RoleArn": "acs:ram::1:role/testrole",
      "Object": "example.flv",
      "Location": "example-location'",
      "Bucket": "example"
    },
    "Count": "1",
    "TileCount": "5",
    "UserData": "testid-001",
    "Code": "ResourceContentBad",
    "PipelineId": "dd3dae411e704030b921e52698e5****",
    "Id": "f4e3b9ba9f3840c39d6e288056f0****"
  }
}

エラーコード

完全なリストについては、「エラーコード」をご参照ください。

変更履歴

完全なリストについては、「変更履歴」をご参照ください。