Chamando as operações de Amazon Rekognition Video - Amazon Rekognition

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Chamando as operações de Amazon Rekognition Video

O Amazon Rekognition Video é uma API assíncrona que você pode usar para analisar vídeos que estão armazenados em um bucket do Amazon Simple Storage Service (Amazon S3). Inicie a análise de um vídeo chamando um Amazon Rekognition VideoStartoperação, comoStartPersonTracking. O Amazon Rekognition Video publica o resultado da solicitação de análise em um tópico do Amazon Simple Notification Service (Amazon SNS). Você pode usar uma fila do Amazon Simple Queue Service (Amazon SQS) ou umAWS LambdaPara obter o status de conclusão da solicitação de análise de vídeo do tópico do Amazon SNS. Por fim, você obtém os resultados da solicitação de análise de vídeo chamando um Amazon RekognitionGetoperação, comoGetPersonTracking.

As informações nas seções a seguir usam operações de detecção de rótulos para mostrar como o Amazon Rekognition Video detecta rótulos (objetos, eventos, conceitos e atividades) em um vídeo armazenado em um bucket do Amazon S3. A mesma abordagem funciona para as outras operações do Amazon Rekognition Video — por exemplo,StartFaceDetectioneStartPersonTracking. O exemploAnalisar um vídeo armazenado em um bucket do Amazon S3 com Java ou Python (SDK)O mostra como analisar um vídeo usando uma fila do Amazon SQS para obter o status de conclusão do tópico do Amazon SNS. Ele também é usado como referência para outros exemplos do Amazon Rekognition Video, comoDetecção de caminhos das pessoas. Para ver exemplos de AWS CLI, consulte Analisar um vídeo com aAWS Command Line Interface.

Iniciar a análise de vídeo

Você pode iniciar uma solicitação de detecção de rótulo do Amazon Rekognition Video chamandoStartLabelDetection. Veja a seguir um exemplo de uma solicitação JSON que é transmitida por 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" }

O parâmetro de entradaVideoO fornece o nome do arquivo de vídeo e o bucket do Amazon S3 do qual recuperá-lo.NotificationChannelcontém o Nome de recurso da Amazon (ARN) do tópico do Amazon SNS que o Amazon Rekognition Video notifica quando a solicitação de análise de vídeo é concluída. O tópico do Amazon SNS deve estar na mesma região da AWS que o endpoint do Amazon Rekognition Video que você está chamando.NotificationChanneltambém contém o ARN de uma função que permite que o Amazon Rekognition Video publique no tópico do Amazon SNS. Você concede ao Amazon Rekognition permissões de publicação para os tópicos do Amazon SNS criando uma função de serviço do IAM. Para obter mais informações, consulte Configurar o Amazon Rekognition Video.

Você também pode especificar um parâmetro de entrada opcional,JobTag, que permite identificar o trabalho no status de conclusão que é publicada no tópico do Amazon SNS.

Para evitar a duplicação acidental de trabalhos de análise, você pode opcionalmente fornecer um token de idempotência, ClientRequestToken. Se você fornecer um valor para ClientRequestToken, a operação Start retornará o mesmo JobId para várias chamadas idênticas para a operação inicial, como StartLabelDetection. Um token ClientRequestToken tem uma vida útil de 7 dias. Depois de 7 dias, você pode reutilizá-lo. Se você reutilizar o token durante a vida útil, o seguinte acontecerá:

  • Se você reutilizar o token com a mesma operação Start e os mesmos parâmetros de entrada, o mesmo JobId será retornado. O trabalho não é realizado novamente, e o Amazon Rekognition Video não envia um status de conclusão para o tópico do Amazon SNS registrado.

  • Se você reutilizar o token com a mesma operação Start e uma pequena alteração no parâmetro de entrada, você receberá uma exceção IdempotentParameterMismatchException (código de status HTTP: 400).

  • Você não deve reutilizar um token com diferentesStartAs operações da medida em que você obterá resultados imprevisíveis do Amazon Rekognition.

A resposta à operação StartLabelDetection é um identificador de trabalho (JobId). Usar oJobIdPara rastrear solicitações e obter os resultados da análise após o Amazon Rekognition Video publicar o status de conclusão no tópico do Amazon SNS. Por exemplo:

{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}

Se você iniciar muitos trabalhos simultaneamente, ligue paraStartLabelDetectionRAISE ALimitExceededException(Código de status HTTP: 400) até que o número de trabalhos simultâneos fique abaixo do limite de serviço do Amazon Rekognition.

Se você achar issoLimitExceededExceptionAs exceções são geradas com intermitências de atividade, considere a possibilidade de usar uma fila do Amazon SQS para gerenciar solicitações recebidas. Entre em contato com o suporte da AWS se você acredita que o número médio de solicitações simultâneas não pode ser gerenciado por uma fila do Amazon SQS e continua recebendo exceções LimitExceededException.

Obtendo o status de conclusão de uma solicitação de análise de Amazon Rekognition Video

O Amazon Rekognition Video envia uma notificação de conclusão de análise para o tópico do Amazon SNS registrado. A notificação inclui o identificador do trabalho e o status de conclusão da operação em uma string JSON. Uma solicitação de análise de vídeo bem-sucedida tem o status SUCCEEDED. Por exemplo, o resultado a seguir mostra o processamento bem-sucedido de um trabalho de detecção de rótulo.

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

Para obter mais informações, consulte Referência: Notificação de resultados de análise de.

Para obter as informações de status que são publicadas no tópico do Amazon SNS pelo Amazon Rekognition Video, use uma das seguintes opções:

  • AWS Lambda— Você pode assinar umAWS LambdaFunção do que você grava em um tópico do Amazon SNS. A função é chamada quando o Amazon Rekognition notifica o tópico do Amazon SNS que a solicitação foi concluída. Use uma função do Lambda se desejar que o código do lado do servidor processe os resultados de uma solicitação de análise de vídeo. Por exemplo, você pode usar o código do lado do servidor para anotar o vídeo ou criar um relatório sobre o conteúdo do vídeo antes de retornar as informações para um aplicativo cliente. Também recomendamos o processamento do lado do servidor para vídeos grandes porque a API do Amazon Rekognition pode retornar volumes de dados grandes.

  • Amazon Simple Queue Service— Você pode inscrever uma fila do Amazon SQS em um tópico do Amazon SNS. Em seguida, pesquise a fila do Amazon SQS para recuperar o status de conclusão que é publicado pelo Amazon Rekognition quando uma solicitação de análise de vídeo é concluída. Para obter mais informações, consulte Analisar um vídeo armazenado em um bucket do Amazon S3 com Java ou Python (SDK). Use uma fila do Amazon SQS se desejar chamar as operações do Amazon Rekognition Video apenas de um aplicativo cliente.

Importante

Nós não recomendamos obter o status de conclusão da solicitação chamando repetidamente o Amazon Rekognition VideoGetoperação. Isso ocorre porque o Amazon Rekognition Video acelera oGetOperar se muitas solicitações forem realizadas. Se você estiver processando vários vídeos simultaneamente, é mais simples e mais eficiente monitorar uma fila do SQS para a notificação de conclusão do que pesquisar no Amazon Rekognition Video pelo status de cada vídeo individualmente.

Obtendo resultados da análise de Amazon Rekognition Video

Para obter os resultados de uma solicitação de análise de vídeo, primeiro verifique se o status de conclusão que é recuperado do tópico do Amazon SNS éSUCCEEDED. Em seguida, chame GetLabelDetection, que transmite o valor JobId que é retornado de StartLabelDetection. O JSON solicitado é semelhante ao exemplo a seguir:

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

JobId é o identificador para a operação de análise de vídeo. Como a análise de vídeo pode gerar grandes quantidades de dados, use MaxResults para especificar o número máximo de resultados para retornar em uma única operação Get. O valor padrão para MaxResults é 1000. Se você especificar um valor maior que 1000, um máximo de 1000 resultados será retornado. Se a operação não retornar todo o conjunto de resultados, um token de paginação para a próxima página será retornado na resposta da operação. Se você tiver um token de paginação de uma solicitação Get anterior, use-o com NextToken para obter a próxima página de resultados.

nota

O Amazon Rekognition retém os resultados de uma operação de análise de vídeo por 7 dias. Você não poderá recuperar os resultados da análise após esse período.

O JSON solicitado da operação GetLabelDetection é similar ao seguinte:

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

Você pode classificar os resultados por tempo de detecção (milissegundos desde o início do vídeo) ou em ordem alfabética pela entidade detectada (objeto, face, celebridade, rótulo de moderação ou pessoa). Para classificar por tempo, defina o valor do parâmetro de entrada SortBy para TIMESTAMP. Se SortBy não for especificado, o comportamento padrão será classificado por tempo. O exemplo anterior é classificado por tempo. Para classificar por entidade, use o parâmetro de entrada SortBy com o valor adequado para a operação que você está executando. Por exemplo, para classificar por rótulo detectado em uma chamada para GetLabelDetection, use o valor NAME.