翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon Rekognition Video オペレーションを呼び出す
Amazon Rekognition Video は、Amazon Simple Storage Service (Amazon S3) バケットに保存されているビデオの分析に使用できる非同期 API です。[StartPersonTracking](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartPersonTracking.html) などの Amazon Rekognition Video の `Start` オペレーションを呼び出して、ビデオの分析を開始します。Amazon Rekognition Video は、分析リクエストの完了ステータスを Amazon Simple Notification Service (Amazon SNS) トピックに発行します。Amazon Simple Queue Service (Amazon SQS) キューまたは AWS Lambda 関数を使用して、Amazon SNS トピックからビデオ分析リクエストの完了ステータスを取得できます。最後に、[GetPersonTracking](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_GetPersonTracking.html) などの Amazon Rekognition `Get` オペレーションを呼び出して、ビデオ分析リクエストの結果を取得します。
以下のセクションでは、ラベル検出オペレーションを使用して、Amazon S3 バケットに保存されているビデオ内のラベル (オブジェクト、イベント、概念、およびアクティビティ) を Amazon Rekognition Video が検出する方法を説明します。この方法は、他の Amazon Rekognition Video オペレーション ([StartFaceDetection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartFaceDetection.html) や [StartPersonTracking](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartPersonTracking.html)) でも同様に機能します。この例 [Java または Python を使用した、Amazon S3 バケットに保存されたビデオの分析 (SDK)](video-analyzing-with-sqs.md) では、Amazon SQS キューを使用して、Amazon SNS トピックから完了ステータスを取得し、ビデオを分析する方法を説明しています。また、[人物の動線の検出](persons.md) など、他の Amazon Rekognition Video の例のベースとして使用することもできます。 AWS CLI 例については、「」を参照してください[を使用したビデオの分析 AWS Command Line Interface](video-cli-commands.md)。
**Topics**
+ [ビデオ分析のスタート](#api-video-start)
+ [Amazon Rekognition Video 分析リクエストの完了ステータスの取得](#api-video-get-status)
+ [Amazon Rekognition Video の分析結果を取得する](#api-video-get)
## ビデオ分析のスタート
[StartLabelDetection](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_StartLabelDetection.html) を呼び出して、Amazon Rekognition Video のラベル検出リクエストを開始します。以下は、`StartLabelDetection` により渡される JSON リクエストの例を示しています。
```
{
"Video": {
"S3Object": {
"Bucket": "amzn-s3-demo-bucket",
"Name": "video.mp4"
}
},
"ClientRequestToken": "LabelDetectionToken",
"MinConfidence": 50,
"NotificationChannel": {
"SNSTopicArn": "arn:aws:sns:us-east-1:nnnnnnnnnn:topic",
"RoleArn": "arn:aws:iam::nnnnnnnnnn:role/roleopic"
},
"JobTag": "DetectingLabels"
}
```
入力パラメータ `Video` はビデオファイル名を提供し、`NotificationChannel` から取得する Amazon S3 バケットには、ビデオ分析リクエストが終了したときに Amazon Rekognition Video が通知する Amazon SNS トピックの Amazon リソースネーム (ARN) が含まれます。Amazon SNS トピックは、呼び出し先の エンドポイントと同じ AWS リージョン内に存在する必要があります。`NotificationChannel` には、Amazon Rekognition Video に Amazon SNS トピックの発行を許可するためのロールの ARN も含まれています。IAM サービスロールを作成して、Amazon Rekognition に Amazon SNS トピックへの発行許可を付与します。詳細については、「[Amazon Rekognition Video の設定](api-video-roles.md)」を参照してください。
`JobTag` というオプションの入力パラメータを指定して、Amazon SNS トピックに発行された完了ステータスのジョブを特定することもできます。
`ClientRequestToken` というべき等トークンをオプションで設定すると、分析ジョブが誤って重複するのを防ぐことができます。`ClientRequestToken` の値を指定すると、`Start` オペレーションは、`StartLabelDetection` などの Start オペレーションに対する複数かつ同一の呼び出しに共通する `JobId` を返します。`ClientRequestToken` トークンの有効期間は 7 日です。7 日後に再利用することができます。トークンの有効期間中にトークンを再利用すると、以下のことが発生します。
+ 同じ `Start` オペレーション、同じ入力パラメータでトークンを再利用すると、同じ `JobId` が返されます。ジョブは再度実行されず、Amazon Rekognition Video は、登録されている Amazon SNS トピックに完了ステータスを送信しません。
+ 同じ `Start` オペレーションで、入力パラメータを少し変更してトークンを再利用すると、`IdempotentParameterMismatchException` (HTTP ステータスコード: 400) 例外を受け取ります。
+ Amazon Rekognition から予期しない結果が発生する可能性があるため、トークンを異なる `Start` オペレーションで再利用しないでください。
`StartLabelDetection` オペレーションに対する応答は、ジョブ識別子 (`JobId`) です。Amazon Rekognition Video が完了ステータスを Amazon SNS トピックに発行したら、`JobId` を使用してリクエストを追跡し、分析結果を取得します。例:
```
{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}
```
同時に開始するジョブが多すぎると、`StartLabelDetection` の呼び出しによって、同時に実行されるジョブの数が Amazon Rekognition サービスの制限を下回るまで `LimitExceededException` (HTTP ステータスコード: 400)が発生します。
アクティビティのバーストにより `LimitExceededException` 例外が発生した場合は、 Amazon SQS キューを使用して受信リクエストを管理することを検討してください。同時リクエストの平均数が Amazon SQS キューで管理できず、まだ`LimitExceededException`例外が発生している場合は、 AWS サポートにお問い合わせください。
## Amazon Rekognition Video 分析リクエストの完了ステータスの取得
Amazon Rekognition Video は、登録されている Amazon SNS トピックに分析完了の通知を送信します。通知には、ジョブ識別子およびオペレーション完了ステータスが JSON 文字列で含まれています。ビデオ分析リクエストが正常に実行された場合は `SUCCEEDED` ステータスとなります。例えば、次の結果はラベル検出ジョブが正常に処理されたことを示しています。
```
{
"JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1nnnnnnnnnnnn",
"Status": "SUCCEEDED",
"API": "StartLabelDetection",
"JobTag": "DetectingLabels",
"Timestamp": 1510865364756,
"Video": {
"S3ObjectName": "video.mp4",
"S3Bucket": "amzn-s3-demo-bucket"
}
}
```
詳細については、「[リファレンス: ビデオ分析結果の通知](video-notification-payload.md)」を参照してください。
Amazon Rekognition Video が Amazon SNS トピックに発行したステータス情報を取得するには、次のいずれかのオプションを使用します。
+ **AWS Lambda** – Amazon SNS トピックに書き込む AWS Lambda 関数をサブスクライブできます。この関数は、Amazon Rekognition によってリクエスト完了が Amazon SNS トピックに通知されると呼び出されます。ビデオ分析リクエストの結果をサーバー側のコードで処理する場合は Lambda 関数を使用します。例えば、クライアントアプリケーションに情報を返す前に、ビデオに注釈を付けたり、ビデオコンテンツに関するレポートを作成したりする場合があります。また、Amazon Rekognition API が大量のデータを返す可能性があるため、ビデオの容量が大きい場合もサーバー側での処理をお勧めします。
+ [**Amazon Simple Queue Service**]— Amazon SQS キューを Amazon SNS トピックにサブスクライブできます。次にこの Amazon SQS キューをポーリングすることで、リクエストの完了時に Amazon Rekognition によって発行される完了ステータスを取得できます。詳細については、「[Java または Python を使用した、Amazon S3 バケットに保存されたビデオの分析 (SDK)](video-analyzing-with-sqs.md)」を参照してください。Amazon SQS キューは、Amazon Rekognition Video のオペレーションをクライアントアプリケーションからのみ呼び出す場合に使用します。
**重要**
リクエストの完了ステータスを取得するために、Amazon Rekognition Video の `Get` オペレーションを繰り返し呼び出すことは推奨されません。これは、実行されるリクエストが多すぎると、Amazon Rekognition Videoによる `Get` オペレーションの調整が行われるためです。複数のビデオを同時処理する場合は、Amazon Rekognition Video をポーリングして各ビデオのステータスを個別に取得するよりも、1 つの SQS キューの完了通知をモニタリングするほうがシンプルかつ効率的です。
## Amazon Rekognition Video の分析結果を取得する
ビデオ分析リクエストの結果を取得するには、まず Amazon SNS トピックから取得された完了ステータスが `SUCCEEDED` であることを確認します。次に `GetLabelDetection` を呼び出し、`StartLabelDetection` から返された `JobId` の値を渡します。リクエストの JSON は次の例のようになります。
```
{
"JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3",
"MaxResults": 10,
"SortBy": "TIMESTAMP"
}
```
JobId はビデオ分析オペレーションの識別子です。ビデオの分析で大量のデータが生成される場合に備えて、1 回の Get オペレーションで返される結果の最大数を `MaxResults` で指定できます。`MaxResults` のデフォルト値は 1000 です。1000 より大きい値を指定した場合、最大 1000 件の結果が返されます。オペレーションが結果セット全体を返さない場合、次のページ用のページ分割トークンがオペレーションの応答で返されます。直前の Get リクエストでページ分割トークンが返された場合は、そのトークンと `NextToken` を使って次の結果ページを取得できます。
**注記**
Amazon Rekognition はビデオ分析オペレーションの結果を 7 日間保持します。この期間を過ぎると分析結果を取得できなくなります。
`GetLabelDetection` オペレーションの応答の JSON は次のようになります。
```
{
"Labels": [
{
"Timestamp": 0,
"Label": {
"Instances": [],
"Confidence": 60.51791763305664,
"Parents": [],
"Name": "Electronics"
}
},
{
"Timestamp": 0,
"Label": {
"Instances": [],
"Confidence": 99.53411102294922,
"Parents": [],
"Name": "Human"
}
},
{
"Timestamp": 0,
"Label": {
"Instances": [
{
"BoundingBox": {
"Width": 0.11109819263219833,
"Top": 0.08098889887332916,
"Left": 0.8881205320358276,
"Height": 0.9073750972747803
},
"Confidence": 99.5831298828125
},
{
"BoundingBox": {
"Width": 0.1268676072359085,
"Top": 0.14018426835536957,
"Left": 0.0003282368124928324,
"Height": 0.7993982434272766
},
"Confidence": 99.46029663085938
}
],
"Confidence": 99.53411102294922,
"Parents": [],
"Name": "Person"
}
},
.
.
.
{
"Timestamp": 166,
"Label": {
"Instances": [],
"Confidence": 73.6471176147461,
"Parents": [
{
"Name": "Clothing"
}
],
"Name": "Sleeve"
}
}
],
"LabelModelVersion": "2.0",
"JobStatus": "SUCCEEDED",
"VideoMetadata": {
"Format": "QuickTime / MOV",
"FrameRate": 23.976024627685547,
"Codec": "h264",
"DurationMillis": 5005,
"FrameHeight": 674,
"FrameWidth": 1280
}
}
```
`GetLabelDetection` および `GetContentModeration` オペレーションでは、分析結果をタイムスタンプまたはラベル名でソートできます。また、結果をビデオセグメント別またはタイムスタンプ別に集計することもできます。
結果は、検出時間 (ビデオの開始時間からミリ秒単位) または検出されたエンティティ (オブジェクト、顔、有名人、モデレーションラベル、人物) のアルファベット順で並べ替えることができます。時間で並べ替える場合は、`SortBy` 入力パラメータの値を `TIMESTAMP` に設定します。`SortBy` が指定されていない場合のデフォルトの動作は、時間による並べ替えです。上記の例は時間で並べ替えられています。エンティティで並べ替えるには、実行するオペレーションにとって適切な値を `SortBy` 入力パラメータで使用します。例えば、`GetLabelDetection` への呼び出しで検出されたラベルで並べ替える、`NAME` 値を使用します。
結果をタイムスタンプ別に集計するには、`AggregateBy` パラメータの値を `TIMESTAMPS` に設定します。ビデオセグメントでは、`AggregateBy` の値を `SEGMENTS` に設定します。`SEGMENTS` 集計モードは、ラベルを経時的に集計し、`TIMESTAMPS` は、2 FPS サンプリングとフレームごとの出力を使って、ラベルが検出されたタイムスタンプを表示します (注: 現在のサンプリングレートは変更される可能性があるため、現在のサンプリングレートを基に予測しないようにしてください)。値が指定されていない場合、デフォルトの集計方法は `TIMESTAMPS` です。