スナップショットジョブを送信します。この API を呼び出すと、ApsaraVideo Media Processing (MPS) が入力ファイルに対してスナップショットの取得およびイメージのタイル処理（画像並べ）を実行します。
操作説明
-
単一の入力ファイルの最大サイズは 100 GB です。このサイズを超えるファイルでは、ジョブが失敗する可能性があります。
-
スナップショットジョブを送信する前に、ファイルが正しく Object Storage Service (OSS) にアップロード済みであることを確認してください。そうでない場合、ジョブは失敗します。OSS コールバックメッセージを設定することで、ファイルのアップロード状況を確認できます。
-
スナップショットジョブは同期モードおよび非同期モードをサポートしています。
同期モードでは、単一のスナップショットのみの取得が可能です。イメージは API の応答返却時に生成されます。
非同期モードでは、タイムリネスは保証されません。スナップショットジョブを送信すると、タスクは MPS キューに登録され、スケジューリングおよび実行待ちとなります。そのため、API の応答返却時にはスナップショットがまだ生成されていない場合があります。ジョブ完了後は、スナップショットジョブ結果の照会 API を定期的に呼び出して結果をポーリングするか、MPS キューに MNS トピックをアタッチして MNS メッセージ経由で結果を受信する必要があります。詳細については、「」および「メッセージ通知の受信」をご参照ください。
Interval または Num パラメーターのいずれかが設定されている場合、非同期モードが使用されます。
-
現在、出力形式として JPG 形式のイメージのみがサポートされています。
-
スナップショットに関するその他のよくある質問については、「スナップショット FAQ」をご参照ください。
クエリ/秒 (QPS) 制限
この API の QPS 制限は、ユーザーあたり 50 クエリ/秒です。この制限を超えると、レート制限が適用され、業務に影響を及ぼす可能性があります。適切な頻度でこの API を呼び出してください。詳細については、「QPS 制限」をご参照ください。
今すぐお試しください
テスト
RAM 認証
|
アクション |
アクセスレベル |
リソースタイプ |
条件キー |
依存アクション |
|
mts:SubmitSnapshotJob |
create |
*All Resource
|
なし | なし |
リクエストパラメーター
|
パラメーター |
型 |
必須 / 任意 |
説明 |
例 |
| Input |
string |
必須 |
ジョブ入力に関する情報です。値は JSON オブジェクトである必要があります。ジョブ入力として使用する OSS オブジェクトを格納する OSS バケットを、MPS コンソールのメディアバケットとして登録する必要があります。OSS バケットをメディアバケットとして登録するには、MPS コンソールにログインし、左側のナビゲーションウィンドウから [ワークフロー] ＞ [メディアバケット] を選択して、[バケットの追加] をクリックします。OSS バケットがメディアバケットとして登録された後は、OSS オブジェクトに対して URL エンコーディングを実行する必要があります。例： 説明
OSS バケットは、ご利用の MPS サービスと同じリージョンに存在している必要があります。 |
{"Bucket":"example-bucket","Location":"example-location","Object":"example%2Ftest.flv"} |
| SnapshotConfig |
string |
必須 |
スナップショットの構成です。「データ型」トピックの「AliyunSnapshotConfig」セクションをご参照ください。 説明
SnapshotConfig 内にネストされた Interval パラメーターを設定した場合、指定された間隔でスナップショットが取得されます。Interval パラメーターのデフォルト値は 10（単位：秒）です。入力動画の長さが短いにもかかわらず、Num および Interval パラメーターの両方に大きな値を指定した場合、実際に取得されるスナップショットの数は指定数より少なくなることがあります。たとえば、10 秒の動画に対して Num を 5、Interval を 3 に設定した場合、取得可能なスナップショットの数は 5 に達しません。 |
{"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 です。ID を取得するには、MPS コンソール にログインし、左側のナビゲーションウィンドウから [グローバル設定] ＞ [パイプライン] を選択します。 説明
指定した MPS キューに利用可能な Message Service (MNS) トピックがバインドされていることを確認してください。そうでない場合、関連するメッセージが期待通りに送信されない可能性があります。 |
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 |
| Color |
string |
背景色です。
説明
背景色を黒に設定する場合は、カラーキーワードを次のいずれかの形式で指定できます：Black、black、#000000。 |
black |
| CellSelStep |
string |
単一イメージを選択する際のステップです。 |
3 |
| CellHeight |
string |
単一イメージの高さです。デフォルト値は出力スナップショットの高さです。 |
100 |
| CellWidth |
string |
単一イメージの幅です。デフォルト値は出力スナップショットの幅です。 |
100 |
| Margin |
string |
タイル化されたイメージのマージン幅です。
|
5 |
| Columns |
string |
タイル化されたイメージに含まれる列数です。デフォルト値：10。 |
10 |
| IsKeepCellPic |
string |
単一イメージを保持するかどうかを示します。有効な値：
|
false |
| Lines |
string |
タイル化されたイメージに含まれる行数です。デフォルト値：10。 |
10 |
| Interval |
string |
スナップショット取得の間隔です。
|
20 |
| FrameType |
string |
スナップショットの種別です。デフォルト値：Normal。有効な値：
説明
リクエストで FrameType パラメーターを intra に設定した場合、キーフレームのみが取得されます。指定された時刻にキーフレームが見つからない場合は、最も近いキーフレームが取得されます。同じスナップショットルールを適用した場合、キーフレームの取得は通常フレームよりも高速です。 |
intra |
| Width |
string |
出力スナップショットの幅です。 |
8 |
| Height |
string |
出力スナップショットの高さです。 |
8 |
| OutputFile |
object |
スナップショットジョブの出力ファイルに関する情報です。 |
|
| RoleArn |
string |
指定した RAM ロールの Alibaba Cloud リソースネーム (ARN) です。フォーマット：acs:ram::$accountID:role/$roleName。 |
acs:ram::1:role/testrole |
| Object |
string |
スナップショットジョブの出力ファイルとして生成される OSS オブジェクトです。 |
test.png |
| Location |
string |
出力スナップショットを格納する OSS バケットが存在する OSS リージョンです。 |
example-location |
| Bucket |
string |
出力スナップショットを格納する OSS バケットです。 |
example |
| Num |
string |
スナップショットの数です。リクエストで Num パラメーターを設定した場合、指定された間隔でスナップショットが取得されます。 |
10 |
| TileOutputFile |
object |
タイル処理ジョブの出力ファイルに関する情報です。 |
|
| RoleArn |
string |
指定した RAM ロールの ARN です。フォーマット：acs:ram::$accountID:role/$roleName。 |
acs:ram::1:role/testrole |
| Object |
string |
タイル処理ジョブの出力ファイルとして生成される OSS オブジェクトです。 |
example.png |
| Location |
string |
オブジェクトを格納する OSS バケットが存在するリージョンの ID です。 |
example-location |
| Bucket |
string |
オブジェクトを格納する OSS バケットです。 |
example |
| TimeArray |
object |
||
| TimePointList |
array |
指定された時刻ポイントの配列です。 |
|
|
integer |
指定された時刻ポイントの配列です。単位はミリ秒で、小数点以下 2 桁の浮動小数点数で表されます。値は重複可能であり、任意の順序で送信できます。MPS が自動的にソートを行います。最大 100 個の時刻ポイントを指定できます。このパラメーターを指定した場合、Num、Time、Interval のいずれのパラメーターも指定してはいけません。いずれかが指定された場合、システムはエラー「InvalidParameter.Ambiguity」を返します。 |
[10050, 50000, 110000, 1000500, 1100500] |
|
| State |
string |
スナップショットジョブのステータスです。有効な値：
|
Snapshoting |
| Message |
string |
ジョブが失敗した場合に返されるエラーメッセージです。ジョブが成功した場合は、このパラメーターは返されません。 |
The resource operated InputFile is bad |
| MNSMessageResult |
object |
MNS が送信する、ジョブ結果を通知するメッセージです。 |
|
| MessageId |
string |
メッセージの ID です。ジョブが失敗した場合は、このパラメーターは返されません。 |
799454621135656C7F815F198A76**** |
| ErrorMessage |
string |
ジョブが失敗した場合に返されるエラーメッセージです。ジョブが成功した場合は、このパラメーターは返されません。 |
The resource operated InputFile is bad |
| ErrorCode |
string |
ジョブが失敗した場合に返されるエラーコードです。ジョブが成功した場合は、このパラメーターは返されません。 |
InvalidParameter |
| Input |
object |
ジョブ入力に関する情報です。 |
|
| RoleArn |
string |
指定した RAM ロールの 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 |
ジョブが失敗した場合に返されるエラーコードです。ジョブが成功した場合は、このパラメーターは返されません。 |
ResourceContentBad |
| PipelineId |
string |
スナップショットジョブが送信された MPS キューの 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****"
}
}エラーコード
完全なリストについては、「エラーコード」をご参照ください。
変更履歴
完全なリストについては、「変更履歴」をご参照ください。