Cómo llamar a las operaciones de Amazon Rekognition Video - Amazon Rekognition
Comenzar el análisis de vídeoObtención del estado de realización de una solicitud de análisis de Amazon Rekognition VideoObtención de los resultados del análisis de Amazon Rekognition Video

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Cómo llamar a las operaciones de Amazon Rekognition Video

Amazon Rekognition Video es una API asincrónica que puede utilizar para analizar vídeos almacenados en un bucket de Amazon Simple Storage Service (Amazon S3). Para iniciar el análisis de un vídeo, llame a una operación de Amazon Rekognition Start Video, como. StartPersonTracking Amazon Rekognition Video publica el resultado de la solicitud de análisis en un tema de Amazon Simple Notification Service (Amazon SNS). Puede utilizar una cola del Amazon Simple Queue Service (Amazon SQS) o AWS Lambda una función para obtener el estado de finalización de la solicitud de análisis de vídeo del tema Amazon SNS. Por último, puede obtener los resultados de la solicitud de análisis de vídeo llamando a una operación de Amazon RekognitionGet, como. GetPersonTracking

La información en las secciones siguientes utiliza las operaciones de detección de etiquetas para mostrar cómo detecta Amazon Rekognition Video etiquetas (objetos, eventos, conceptos y actividades) en un vídeo que está almacenado en un bucket de Amazon S3. El mismo enfoque funciona para las demás operaciones de Amazon Rekognition Video, por ejemplo, y. StartFaceDetectionStartPersonTracking El ejemplo Análisis de un vídeo almacenado en un bucket de Amazon S3 con Java o Python (SDK) muestra cómo analizar un vídeo mediante el uso de una cola de Amazon SQS para obtener el estado de la realización a partir del tema de Amazon SNS. También se utiliza como base para otros ejemplos de Amazon Rekognition Video, como Recorridos de las personas. Para ver ejemplos, consulte. AWS CLI Analizar un vídeo con el AWS Command Line Interface

Comenzar el análisis de vídeo

Para iniciar una solicitud de detección de etiquetas de Amazon Rekognition Video, debe llamar. StartLabelDetection El siguiente es un ejemplo de una solicitud JSON que ha transferido StartLabelDetection.

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

El parámetro de entrada Video proporciona el nombre del archivo de vídeo y el bucket de Amazon S3 desde el que recuperarlo. NotificationChannel contiene el Nombre de recurso de Amazon (ARN) del tema de Amazon SNS al que Amazon Rekognition Video notifica cuando finaliza la solicitud de análisis de vídeo. El tema de Amazon SNS debe estar en la misma región de AWS que el punto de conexión de Amazon Rekognition Video al que está llamando. NotificationChannel también contiene el ARN de un rol que permite a Amazon Rekognition Video publicar en el tema de Amazon SNS. Puede conceder permisos de publicación a Amazon Rekognition a sus temas de creando un rol de servicio de IAM. Para obtener más información, consulte Configuración de Amazon Rekognition Video.

También puede especificar un parámetro de entrada opcional, JobTag, que le permite identificar el trabajo en el estado de realización que se ha publicado en el tema de Amazon SNS.

Para evitar la duplicación accidental de trabajos de análisis, tiene la opción de proporcionar un token idempotente, ClientRequestToken. Si proporciona un valor para ClientRequestToken, la operación Start devuelve el mismo JobId para varias llamadas idénticas a la operación de inicio, como por ejemplo StartLabelDetection. Un token ClientRequestToken tiene una vida útil de 7 días. Después de 7 días, puede volver a utilizarla. Si reutiliza el token durante el ciclo de vida del token, sucede lo siguiente:

  • Si reutiliza el token con la misma operación Start y los mismos parámetros de entrada, se devuelve el mismo JobId. El trabajo no se vuelve a realizar de nuevo y Amazon Rekognition Video no envía un estado de realización al tema de Amazon SNS registrado.

  • Si vuelve a utilizar el token con la misma operación Start y un cambio de parámetro de entrada menor, obtendrá una excepción IdempotentParameterMismatchException (código de estado HTTP: 400).

  • No debe reutilizar un token con diferentes operaciones Start, ya que obtendrá resultados impredecibles en Amazon Rekognition.

La respuesta a la operación StartLabelDetection es un identificador de trabajo (JobId). Utilice JobId para realizar un seguimiento de las solicitudes y obtener los resultados de análisis después de que Amazon Rekognition Video haya publicado el estado de realización en el tema de Amazon SNS. Por ejemplo:

{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}

Si inicia demasiados trabajos al mismo tiempo, las llamadas a StartLabelDetection producen una excepción LimitExceededException (código de estado HTTP: 400) hasta que el número de trabajos ejecutados simultáneamente se encuentre por debajo del límite de servicio de Amazon Rekognition.

Si descubre que las excepciones LimitExceededException se producen con picos de actividad, considere la posibilidad de usar una cola de Amazon SQS para administrar las solicitudes entrantes. Póngase en contacto con el servicio de AWS asistencia si descubre que una cola de Amazon SQS no puede gestionar su número medio de solicitudes simultáneas y sigue recibiendo excepciones. LimitExceededException

Obtención del estado de realización de una solicitud de análisis de Amazon Rekognition Video

Amazon Rekognition Video envía una notificación a la realización de análisis al tema de Amazon SNS registrado. La notificación incluye el identificador de trabajo y el estado de realización de la operación en una cadena de JSON. Una solicitud de análisis de vídeo correcta tiene un estado SUCCEEDED. Por ejemplo, el siguiente resultado muestra el procesamiento correcto de un trabajo de detección de etiqueta.

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

Para obtener más información, consulte Referencia: notificación de resultados de análisis de vídeo.

Para obtener la información de estado que Amazon Rekognition Video ha publicado en el tema de Amazon SNS, utilice una de las siguientes opciones:

  • AWS Lambda: puede suscribir una función de AWS Lambda que escriba en un tema de Amazon SNS. Se llama a la función cuando Amazon Rekognition notifica al tema de Amazon SNS que la solicitud se ha completado. Utilice una función de Lambda si desea que el código del servidor procese los resultados de una solicitud de análisis de vídeo. Por ejemplo, es posible que desee utilizar el código del servidor para anotar el vídeo o crear un informe sobre el contenido de vídeo antes de devolver la información a una aplicación cliente. También le recomendamos el procesamiento del lado del servidor de vídeos grandes, ya que la API de Amazon Rekognition podría devolver grandes volúmenes de datos.

  • Amazon Simple Queue Service: puede suscribir una cola de Amazon SQS a un tema de Amazon SNS. A continuación, sondee la cola de Amazon SQS para recuperar el estado de realización que ha publicado Amazon Rekognition cuando se completa una solicitud de análisis de vídeo. Para obtener más información, consulte Análisis de un vídeo almacenado en un bucket de Amazon S3 con Java o Python (SDK). Utilice una cola de Amazon SQS si desea llamar a operaciones de Amazon Rekognition Video solo desde una aplicación cliente.

importante

No le recomendamos obtener el estado de realización de solicitud llamando repetidamente a la operación Get de Amazon Rekognition Video. Esto se debe a que Amazon Rekognition Video limita la operación Get si se realizan demasiadas solicitudes. Si está procesando varios vídeos simultáneamente, es más sencillo y más eficaz monitorear una cola de SQS para la notificación de realización que sondear Amazon Rekognition Video para detectar el estado de cada vídeo individualmente.

Obtención de los resultados del análisis de Amazon Rekognition Video

Para obtener los resultados de una solicitud de análisis de vídeo, en primer lugar, asegúrese de que el estado de realización que se ha recuperado del tema de Amazon SNS es SUCCEEDED. A continuación, llame a GetLabelDetection, que transfiere el valor JobId que se devuelve desde StartLabelDetection. El JSON de la solicitud es similar al siguiente ejemplo:

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

JobId es el identificador de la operación de análisis de vídeo. Dado que el análisis de vídeo puede generar grandes cantidades de datos, utilice MaxResults para especificar el número máximo de resultados que debe devolver en una sola operación GET. El valor predeterminado de MaxResults es 1000. Si especifica un valor superior a 1 000, se devolverá un máximo de 1 000 resultados. Si la operación no devuelve todo el conjunto de resultados, se devuelve un token de paginación para la página siguiente en la respuesta de operación. Si tiene un token de paginación de una solicitud GET anterior, utilícelo con NextToken para obtener la siguiente página de resultados.

nota

Amazon Rekognition retiene los resultados de una operación de análisis de vídeo durante siete días. No podrá recuperar los resultados del análisis transcurrido este plazo.

El JSON de respuesta de la operación GetLabelDetection es similar al siguiente:

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

Las operaciones GetLabelDetection y GetContentModeration le permiten ordenar los resultados del análisis por marca de tiempo o por nombre de etiqueta. También puede agregar los resultados por segmento de vídeo o por marca de tiempo.

Puede ordenar los resultados por hora de detección (milisegundos desde el comienzo del vídeo) o alfabéticamente por la entidad detectada (objeto, rostro, famoso, etiqueta de moderación o persona). Para ordenar por tiempo, establezca el valor del parámetro de entrada SortBy en TIMESTAMP. Si no se especifica SortBy, el comportamiento predeterminado se ordena por tiempo. El ejemplo anterior está ordenado por tiempo. Para ordenar por entidad, utilice el parámetro de entrada SortBy con el valor que es adecuado para la operación que está realizando. Por ejemplo, para ordenar por etiqueta detectada en una llamada a GetLabelDetection, utilice el valor NAME.

Para agregar los resultados por marca de tiempo, defina el valor del parámetro AggregateBy en TIMESTAMPS. Para agregar por segmento de vídeo, defina el valor de AggregateBy en SEGMENTS. El modo de agregación de SEGMENTS agregará las etiquetas a lo largo del tiempo y TIMESTAMPS mostrará la marca temporal en la que se detectó una etiqueta, utilizando un muestreo de 2 FPS y una salida por fotograma (Nota: Esta frecuencia de muestreo actual está sujeta a cambios, por lo que no se deben hacer suposiciones sobre la frecuencia de muestreo actual). Si no se especifica ningún valor, el método de agregación predeterminado es TIMESTAMPS.