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

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

以下のセクションでは、ラベル検出オペレーションを使用して、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。

ビデオ分析のスタート

StartLabelDetection を呼び出して、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 の設定」を参照してください。

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"
    }
}

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

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)」を参照してください。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 です。