Appeler les opérations de Vidéo Amazon Rekognition

Vidéo Amazon Rekognition est une API asynchrone que vous pouvez utiliser pour analyser des vidéos stockées dans un compartiment Amazon Simple Storage Service (Amazon Simple Storage Service (Amazon S3). Vous commencez l'analyse d'une vidéo en appelant une opération Amazon Rekognition Start Video, telle que. StartPersonTracking Vidéo Amazon Rekognition publie le résultat de la demande d’analyse dans une rubrique Amazon Simple Notification Service (Amazon SNS). Vous pouvez utiliser une file d'attente Amazon Simple Queue Service (Amazon SQS) ou AWS Lambda une fonction pour obtenir l'état d'avancement de la demande d'analyse vidéo à partir de la rubrique Amazon SNS. Enfin, vous obtenez les résultats de la demande d'analyse vidéo en appelant une opération Get Amazon Rekognition, telle que. GetPersonTracking

Les informations contenues dans les sections suivantes utilisent des opérations de détection d’étiquette pour montrer comment Vidéo Amazon Rekognition détecte des étiquettes (objets, événements, concepts et activités) dans une vidéo stockée dans un compartiment Amazon S3. La même approche fonctionne pour les autres opérations Amazon Rekognition Video, par exemple, et. StartFaceDetectionStartPersonTracking L’exemple Analyse d’une vidéo stockée dans un compartiment Amazon S3 avec Java or Python (SDK) présente comment analyser une vidéo en utilisant une file d’attente Amazon SQS pour obtenir le statut d’achèvement à partir de la rubrique Amazon SNS. Il est également utilisé comme base pour d’autres exemples Vidéo Amazon Rekognition tels que Tracé du parcours de personnes. Pour AWS CLI des exemples, voirAnalyse d'une vidéo à l'aide du AWS Command Line Interface.

Démarrage d’une analyse vidéo

Vous lancez une demande de détection d'étiquette Amazon Rekognition Video en appelant. StartLabelDetection L’exemple suivant est une demande JSON transmise par StartLabelDetection.

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

Le paramètre d’entrée Video contient le nom du fichier vidéo et le compartiment Amazon S3 dont ce fichier peut être extrait. NotificationChannel contient l’Amazon Resource Name (ARN) de la rubrique Amazon SNS à laquelle Vidéo Amazon Rekognition adresse une notification lorsque la demande d’analyse vidéo est terminée. La rubrique Amazon SNS doit être située dans la même région AWS que le point de terminaison Vidéo Amazon Rekognition que vous appelez. NotificationChannel contient également l’ARN pour un rôle qui permet à Vidéo Amazon Rekognition de publier dans la rubrique Amazon SNS. Vous attribuez des autorisations de publication Amazon Rekognition dans vos rubriques Amazon SNS en créant une fonction du service IAM. Pour plus d’informations, consultez Configuration de Vidéo Amazon Rekognition.

Vous pouvez également spécifier un paramètre d’entrée facultatif, JobTag, qui vous permet d’identifier la tâche dans le statut d’achèvement publié dans la rubrique Amazon SNS.

Afin d’éviter toute duplication accidentelle des tâches d’analyse, vous pouvez, si vous le souhaitez, fournir un jeton idempotent, ClientRequestToken. Si vous indiquez une valeur pour ClientRequestToken, l’opération Start renvoie le même JobId pour plusieurs appels identiques à l’opération de démarrage, par exemple StartLabelDetection. Un jeton ClientRequestToken a une durée de vie de 7 jours. Au delà de 7 jours, vous pouvez le réutiliser. Si vous réutilisez le jeton pendant sa durée de vie, ce qui suit se produit :

• Si vous réutilisez le jeton avec la même opération Start et les mêmes paramètres d’entrée, le même JobId est renvoyé. La tâche n’est pas exécutée à nouveau et Vidéo Amazon Rekognition n’envoie pas de statut d’achèvement à la rubrique Amazon SNS enregistrée.

• Si vous réutilisez le jeton avec la même opération Start et une modification mineure du paramètre d’entrée, vous obtenez une exception IdempotentParameterMismatchException (code de statut HTTP : 400).

• Vous ne devez pas réutiliser un jeton avec des opérations Start différentes, car vous obtiendrez des résultats imprévisibles d’Amazon Rekognition.

La réponse à l’opération StartLabelDetection est un identifiant de tâche (JobId). Utilisez JobId pour suivre les demandes et obtenir les résultats d’analyse une fois que Vidéo Amazon Rekognition a publié le statut d’achèvement dans la rubrique Amazon SNS. Par exemple :

{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}

Si vous lancez un trop grand nombre de tâches simultanément, les appels à StartLabelDetection génèrent une LimitExceededException (code de statut HTTP : 400) jusqu’à ce que le nombre de tâches exécutées simultanément soit inférieur à la limite de service Amazon Rekognition.

Si vous constatez que les exceptions LimitExceededException sont générées lors des pics d’activité, vous devez envisager d’utiliser une file d’attente Amazon SQS afin de gérer les demandes entrantes. Contactez le AWS support si vous constatez que votre nombre moyen de demandes simultanées ne peut pas être géré par une file d'attente Amazon SQS et que vous recevez LimitExceededException toujours des exceptions.

Obtention du statut d’achèvement d’une demande d’analyse Vidéo Amazon Rekognition

Vidéo Amazon Rekognition envoie une notification d’achèvement d’analyse à la rubrique Amazon SNS enregistrée. La notification comprend l’identifiant de la tâche et le statut d’achèvement de l’opération dans une chaîne JSON. Une demande d’analyse vidéo réussie a un statut SUCCEEDED. Par exemple, le résultat suivant montre la réussite du traitement d’une tâche de détection d’étiquette.

{
    "JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1nnnnnnnnnnnn",
    "Status": "SUCCEEDED",
    "API": "StartLabelDetection",
    "JobTag": "DetectingLabels",
    "Timestamp": 1510865364756,
    "Video": {
        "S3ObjectName": "video.mp4",
        "S3Bucket": "bucket"
    }
}

Pour plus d’informations, consultez Référence : Notification des résultats d’une analyse vidéo.

Pour obtenir les informations de statut publiées dans la rubrique Amazon SNS par Vidéo Amazon Rekognition, utilisez l’une des options suivantes :

• AWS Lambda : vous pouvez abonner une fonction AWS Lambda que vous écrivez à une rubrique Amazon SNS. La fonction est appelée quand Amazon Rekognition informe la rubrique Amazon SNS que la demande est terminée. Utilisez une fonction Lambda si vous souhaitez que le code côté serveur traite les résultats d’une demande d’analyse vidéo. Par exemple, vous pouvez utiliser du code côté serveur pour annoter la vidéo ou créer un rapport sur le contenu de la vidéo avant de renvoyer les informations vers une application cliente. Nous recommandons également un traitement côté serveur pour les vidéos volumineuses, car l’API Amazon Rekognition risque de renvoyer d’importants volumes de données.

• Amazon Simple Queue Service : vous pouvez abonner une file d’attente Amazon SQS à une rubrique Amazon SNS. Vous pouvez ensuite interroger la file d’attente Amazon SQS pour extraire le statut d’achèvement publié par Amazon Rekognition lorsqu’une demande d’analyse vidéo se termine. Pour plus d’informations, consultez Analyse d’une vidéo stockée dans un compartiment Amazon S3 avec Java or Python (SDK). Utilisez une file d’attente Amazon SQS si vous souhaitez appeler des opérations Vidéo Amazon Rekognition uniquement à partir d’une application cliente.

Important

Nous vous déconseillons d’obtenir le statut d’achèvement d’une demande en appelant de manière répétée l’opération Get Vidéo Amazon Rekognition. La raison en est que Vidéo Amazon Rekognition limite l’opération Get si de trop nombreuses demandes sont lancées. Si vous traitez plusieurs vidéos simultanément, il est plus simple et plus efficace de surveiller la création d’une notification d’achèvement dans une file d’attente SQS que d’interroger Vidéo Amazon Rekognition pour obtenir le statut de chaque vidéo individuellement.

Obtenir les résultats de l’analyse de Vidéo Amazon Rekognition

Pour obtenir les résultats d’une demande d’analyse vidéo, assurez-vous tout d’abord que le statut d’achèvement extrait de la rubrique est Amazon SNS est SUCCEEDED. Ensuite, appelez GetLabelDetection, qui transmet la valeur JobId renvoyée par StartLabelDetection. Le format JSON de la demande est similaire à l’exemple suivant :

{
    "JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3",
    "MaxResults": 10,
    "SortBy": "TIMESTAMP"
}

JobId est l'identifiant de l'opération d'analyse vidéo. Dans la mesure où l’analyse vidéo peut générer de grandes quantités de données, utilisez MaxResults pour spécifier le nombre maximum de résultats pouvant être renvoyés dans une opération Get. La valeur par défaut du paramètre MaxResults est 1000. Si vous spécifiez une valeur supérieure à 1 000, seuls 1 000 résultats sont renvoyés au maximum. Si l’opération ne renvoie pas l’ensemble des résultats, un jeton de pagination pour la page suivante est renvoyé dans la réponse de l’opération. Si vous obtenez un jeton de pagination transmis par une précédente demande Get, utilisez-le avec NextToken pour obtenir la page suivante des résultats.

Note

Amazon Rekognition conserve les résultats d’une opération d’analyse vidéo pendant 7 jours. Passé ce délai, vous ne pourrez pas récupérer les résultats de l’analyse.

Le format JSON d’une réponse d’opération GetLabelDetection est similaire à l’exemple suivant :

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

Les opérations GetLabelDetection et GetContentModeration vous permettent de trier les résultats de l’analyse par horodatage ou par nom d’étiquette. Vous pouvez également agréger les résultats par horodatage ou par segments vidéo.

Vous pouvez trier les résultats en fonction de l’heure de détection (millisecondes à partir du début de la vidéo) ou de l’entité détectée (objet, visage, célébrité, étiquette de modération ou personne), par ordre alphabétique. Pour trier en fonction de l’heure, définissez la valeur du paramètre d’entrée SortBy sur TIMESTAMP. Si SortBy n’est pas spécifié, le tri est, par défaut, effectué en fonction de l’heure. L’exemple précédent est trié en fonction de l’heure. Pour trier en fonction de l’entité, utilisez le paramètre d’entrée SortBy avec la valeur appropriée pour l’opération que vous exécutez. Par exemple, pour trier en fonction de l’étiquette détectée dans un appel à GetLabelDetection, utilisez la valeur NAME.

Pour agréger les résultats par horodatage, définissez la valeur du paramètre AggregateBy sur TIMESTAMPS. Pour agréger par segment vidéo, définissez la valeur de AggregateBy àSEGMENTS. Le mode d’agrégation SEGMENTS agrègera les étiquettes au fil du temps, tandis que TIMESTAMPS donne l’horodatage auquel une étiquette a été détectée, en utilisant un échantillonnage à 2 images par seconde et une sortie par image (Remarque : ce taux d’échantillonnage actuel est sujet à modification, aucune hypothèse ne doit être faite quant au taux d’échantillonnage actuel). Si aucune valeur n’est spécifiée, la méthode d’agrégation par défaut est TIMESTAMPS.