Amazon Rekognition Video オペレーションを呼び出す

Amazon Rekognition Video は、Amazon Simple Storage Service (Amazon S3) バケットに保存されているビデオの検索に使用できる非同期 API です。Amazon Rekognition Video を呼び出すことで、ビデオの分析が開始されます。Startなどの操作StartPersonTracking。Amazon Rekognition Video は、分析リクエストの結果を Amazon Simple Notification Service (Amazon SNS) トピックに発行します。Amazon Simple Queue Service (Amazon SQS) キューまたはAWS Lambdaは、Amazon SNS トピックからビデオ分析リクエストの完了ステータスを取得する関数です。最後に、Amazon Rekognition を呼び出して、ビデオ分析リクエストの結果を取得します。Getなどの操作GetPersonTracking。

以下のセクションでは、Amazon S3 バケットに保存されているビデオ内のラベル (オブジェクト、イベント、概念、アクティビティ) を Amazon Rekognition Video が検出する方法を、ラベル検出オペレーションを使って説明しています。同じ方法を、たとえば、以下の Amazon Rekognition Video オペレーションでも使うことができます。StartFaceDetectionそしてStartPersonTracking。の例Java または Python を使用した、Amazon S3 バケットに保存されているビデオの分析 (SDK)には、Amazon SQS キューを使用して Amazon SNS トピックから完了ステータスを取得し、ビデオを分析する方法を説明しています。これはその他の Amazon Rekognition Video の例の基礎として使用することもできます次に例を示します。人物の検出。AWS CLI の例については、「を使用したビデオの分析AWS Command Line Interface」を参照してください。

ビデオ分析の開始

Amazon Rekognition Video ラベルリクエストを開始するには、を呼び出します。StartLabelDetection。以下は、StartLabelDetection により渡される JSON リクエストの例を示しています。

{
    "Video": {
        "S3Object": {
            "Bucket": "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は、ビデオのファイル名と、取得先の Amazon S3 バケットを提供します。NotificationChannelには、Amazon SNS トピックの Amazon リソースネーム (ARN) と、Amazon Rekognition Video がビデオ分析リクエストの完了時に通知する Amazon SNS トピックが含まれています。Amazon SNS トピックは、呼び出し先の Amazon Rekognition Video エンドポイントと同じ AWS リージョン内に存在する必要があります。NotificationChannelには、Amazon Rekognition Video を Amazon SNS トピックに発行できるようにするためのロールの ARN も含まれています。IAM サービスロールを作成すると、Amazon SNS トピックへの Amazon Rekognition 発行アクセス権限がに付与されます。詳細については、「Amazon Rekognition Video の設定」を参照してください。

オプションの入力パラメータを指定することもできます。JobTagを選択すると、Amazon SNS トピックに発行された完了ステータスのジョブを特定できます。

ClientRequestToken というべき等トークンをオプションで設定すると、分析ジョブが誤って重複するのを防ぐことができます。ClientRequestToken の値を指定すると、Start オペレーションは、StartLabelDetection などの Start オペレーションに対する複数かつ同一の呼び出しに共通する JobId を返します。ClientRequestToken トークンの有効期間は 7 日です。7 日後に再利用することができます。トークンの有効期間中にトークンを再利用すると、以下のことが発生します。

• 同じ Start オペレーション、同じ入力パラメータでトークンを再利用すると、同じ JobId が返されます。ジョブは再度実行されず、Amazon Rekognition Video は、登録されている Amazon SNS トピックに完了ステータスを送信しません。

• 同じ Start オペレーションで、入力パラメータを少し変更してトークンを再利用すると、IdempotentParameterMismatchException (HTTP ステータスコード: 400) 例外を受け取ります。

• 別のトークンを再利用しないでください。StartAmazon Rekognition から予測できない結果を得るため、のオペレーション。

StartLabelDetection オペレーションに対する応答は、ジョブ識別子 (JobId) です。を使用するJobIdをクリックして、Amazon Rekognition Video が Amazon SNS トピックに完了ステータスを発行したら、リクエストを追跡し、分析結果を取得します。例:

{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}

同時に開始するジョブが多すぎると、StartLabelDetectionをレイズLimitExceededException同時に実行されるジョブの数が Amazon Rekognition サービスの制限を下回るまで、(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": "bucket"
    }
}

詳細については、「リファレンス: ビデオ解析結果の通知」を参照してください。

Amazon Rekognition Video で Amazon SNS トピックに発行されたステータス情報を取得するには、以下のいずれかのオプションを使用します。

• AWS Lambda— をサブスクライブできます。AWS LambdaAmazon SNS トピックに書き込む関数。この関数は、Amazon Rekognition によってリクエスト完了が Amazon SNS トピックに通知されると呼び出されます。ビデオ分析リクエストの結果をサーバー側のコードで処理する場合は Lambda 関数を使用します。たとえば、クライアントアプリケーションに情報を返す前に、ビデオに注釈を付けたり、ビデオコンテンツに関するレポートを作成したりする場合があります。また、Amazon Rekognition API が大量のデータを返す可能性があるため、ビデオの容量が大きい場合もサーバー側での処理をお勧めします。

• Amazon Simple Queue Service— Amazon SNS トピックに Amazon SQS キューをサブスクライブできます。この Amazon SQS キューをポーリングすることで、リクエストの完了時に Amazon Rekognition が発行する完了ステータスを取得できます。詳細については、「Java または Python を使用した、Amazon S3 バケットに保存されているビデオの分析 (SDK)」を参照してください。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
    }
}

結果は、検出時間 (ビデオの開始時間からミリ秒単位) または検出されたエンティティ (オブジェクト、顔、有名人、モデレーションラベル、人物) のアルファベット順で並べ替えることができます。時間で並べ替える場合は、SortBy 入力パラメータの値を TIMESTAMP に設定します。SortBy が指定されていない場合のデフォルトの動作は、時間による並べ替えです。上記の例は時間で並べ替えられています。エンティティで並べ替えるには、実行するオペレーションにとって適切な値を SortBy 入力パラメータで使用します。たとえば、GetLabelDetection への呼び出しで検出されたラベルで並べ替える、NAME 値を使用します。