Appeler les opérations de Vidéo Amazon Rekognition

Amazon Rekognition Video est un outil API asynchrone que vous pouvez utiliser pour analyser des vidéos stockées dans un bucket 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 Amazon Rekognition Video publie le résultat de la demande d'analyse sur une rubrique Amazon Simple Notification Service (Amazon). SNS Vous pouvez utiliser une file d'attente ou une AWS Lambda fonction Amazon Simple Queue Service (AmazonSQS) pour connaître l'état d'avancement de la demande d'analyse vidéo à partir de la SNS rubrique Amazon. 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 ou Python (SDK) montre comment analyser une vidéo à l'aide d'une SQS file d'attente Amazon pour obtenir le statut d'achèvement à partir de la SNS rubrique Amazon. 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 Voici un exemple de JSON demande transmiseStartLabelDetection.

{
    "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 fournit le nom du fichier vidéo et le compartiment Amazon S3 à partir duquel le récupérer. NotificationChannelcontient le nom de ressource Amazon (ARN) du SNS sujet Amazon qu'Amazon Rekognition Video notifie lorsque la demande d'analyse vidéo est terminée. Le SNS sujet Amazon doit se trouver dans la même AWS région que le point de terminaison Amazon Rekognition Video que vous appelez. NotificationChannelcontient également le rôle ARN for qui permet à Amazon Rekognition Video de publier sur le sujet Amazon. SNS Vous accordez à Amazon Rekognition des autorisations de publication sur vos sujets SNS Amazon en créant un rôle de service. IAM Pour de plus amples informations, veuillez consulter Configuration de Vidéo Amazon Rekognition.

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

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 Amazon Rekognition Video n'envoie pas de statut d'achèvement au sujet Amazon enregistré. SNS

• Si vous réutilisez le jeton avec la même Start opération et une modification mineure des paramètres d'entrée, une exception IdempotentParameterMismatchException (code d'HTTPétat : 400) est déclenchée.

• 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). JobIdÀ utiliser pour suivre les demandes et obtenir les résultats de l'analyse une fois qu'Amazon Rekognition Video a publié le statut d'achèvement dans la rubrique Amazon. SNS Par exemple :

{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}

Si vous commencez un trop grand nombre de tâches simultanément, appelez pour StartLabelDetection augmenter un LimitExceededException (code d'HTTPétat : 400) jusqu'à ce que le nombre de tâches exécutées simultanément soit inférieur à la limite du service Amazon Rekognition.

Si vous constatez que LimitExceededException des exceptions sont déclenchées par des pics d'activité, pensez à utiliser une SQS file d'attente Amazon pour 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 SQS file d'attente Amazon et que vous recevez toujours LimitExceededException des exceptions.

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

Amazon Rekognition Video envoie une notification de fin d'analyse au sujet Amazon enregistré. SNS La notification inclut l'identifiant de la tâche et l'état d'achèvement de l'opération dans une JSON chaîne. 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 de plus amples informations, veuillez consulter Référence : Notification des résultats d’une analyse vidéo.

Pour obtenir les informations de statut publiées sur le SNS sujet Amazon par Amazon Rekognition Video, utilisez l'une des options suivantes :

• AWS Lambda— Vous pouvez vous abonner à une AWS Lambda fonction que vous écrivez dans un SNS sujet Amazon. La fonction est appelée lorsqu'Amazon Rekognition indique au sujet Amazon que SNS 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 le traitement côté serveur pour les vidéos volumineuses, car Amazon API Rekognition peut renvoyer de gros volumes de données.

• Amazon Simple Queue Service : vous pouvez abonner une SQS file d'attente Amazon à un SNS sujet Amazon. Vous interrogez ensuite la SQS file d'attente Amazon pour obtenir le statut d'achèvement publié par Amazon Rekognition lorsqu'une demande d'analyse vidéo est terminée. Pour de plus amples informations, veuillez consulter Analyse d'une vidéo stockée dans un compartiment Amazon S3 avec Java ou Python (SDK). Utilisez une SQS file d'attente Amazon si vous souhaitez appeler les opérations Amazon Rekognition Video 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 une SQS file d'attente pour la notification d'achèvement que de demander à Amazon Rekognition Video 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 d'abord que le statut d'achèvement extrait de la SNS rubrique Amazon est le suivantSUCCEEDED. Ensuite, appelez GetLabelDetection, qui transmet la valeur JobId renvoyée par StartLabelDetection. La demande JSON 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.

La réponse de GetLabelDetection l'opération JSON est similaire à la suivante :

{
    "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. SEGMENTSle mode d'agrégation agrègera les étiquettes au fil du tempsTIMESTAMPS, tout en indiquant l'horodatage auquel une étiquette a été détectée, en utilisant 2 FPS échantillonnages 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.