Chamando operações assíncronas do Amazon Textract - Amazon Textract

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 operações assíncronas do Amazon Textract

O Amazon Textract fornece uma API assíncrona que você pode usar para processar documentos de várias páginas em formato PDF ou TIFF. Você também pode usar operações assíncronas para processar documentos de página única que estão no formato JPEG, PNG, TIFF ou PDF.

As informações neste tópico usam operações de detecção de texto para mostrar como usar operações assíncronas do Amazon Textract. A mesma abordagem funciona com as operações de análise de texto doStartDocumentAnalysiseGetDocumentAnalysis. Também funciona da mesma maneira comStartExpenseAnalysiseGetExpenseAnalysis.

Para ver um exemplo, consulte Detectando ou analisando texto em um documento de várias páginas.

Amazon Textract processa assíncrona um documento armazenado em um bucket do Amazon S3. Você começa a processar chamando umStartoperação, comoStartDocumentTextDetection. O status de conclusão da solicitação é publicada em um tópico do Amazon Simple Notification Service (Amazon SNS). Para obter o status de conclusão do tópico do Amazon SNS, use uma fila do Amazon Simple Queue Service (Amazon SQS) ou umaAWS Lambdafunção. Ao receber o status de conclusão, chame uma operação Get, como a GetDocumentTextDetection para obter os resultados da solicitação.

Os resultados de chamadas assíncronas são criptografados e armazenados por 7 dias em um bucket de propriedade do Amazon Textract por padrão, a menos que você especifique um bucket do Amazon S3 usando uma operaçãoOutputConfigArgumento.

A tabela a seguir mostra as operações Iniciar e Get correspondentes para os diferentes tipos de processamento assíncrono suportados pelo Amazon Textract:

Iniciar/obter operações de API para operações assíncronas do Amazon Textract
Tipo de processamento API Iniciar Obter API
Detecção de texto StartDocumentTextDetection GetDocumentTextDetection
Análise de texto StartDocumentAnalysis GetDocumentAnalysis
Análise de despesas StarTExpenseAnalysis GetExpenseAnalysis

Para um exemplo que usaAWS Lambdafunções, consulteProcessamento de documentos em grande escala com o Amazon Textract.

O diagrama a seguir mostra o processo para detectar o texto do documento em uma imagem de documento armazenada em um bucket do Amazon S3. No diagrama, uma fila do Amazon SQS obtém o status de conclusão do tópico do Amazon SNS.

O processo exibido pelo diagrama anterior é o mesmo para analisar texto e faturas/recibos. Você começa a analisar o texto chamandoStartDocumentAnalysise comece a analisar faturas/recibos ligandoStartExpenseAnalysisVocê obtém os resultados ligandoGetDocumentAnalysisouGetExpenseAnalysisrespectivamente.

Iniciar a detecção de texto

Você pode iniciar uma solicitação de detecção de texto do Amazon Textract chamandoStartDocumentTextDetection. Veja a seguir um exemplo de uma solicitação JSON que é transmitida por StartDocumentTextDetection.

{ "DocumentLocation": { "S3Object": { "Bucket": "bucket", "Name": "image.pdf" } }, "ClientRequestToken": "DocumentDetectionToken", "NotificationChannel": { "SNSTopicArn": "arn:aws:sns:us-east-1:nnnnnnnnnn:topic", "RoleArn": "arn:aws:iam::nnnnnnnnnn:role/roleTopic" }, "JobTag": "Receipt" }

O parâmetro de entradaDocumentLocationfornece o nome do arquivo do documento 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 Textract notifica quando a solicitação de detecção de texto é concluída. O tópico do Amazon SNS deve estar na mesma região da AWS que o endpoint do Amazon Textract que você está chamando.NotificationChanneltambém contém o ARN para uma função que permite que o Amazon Textract publique no tópico do Amazon SNS. Você concede permissões de publicação Amazon Textract para os tópicos do Amazon SNS criando uma função de serviço do IAM. Para obter mais informações, consulte Configurando o Amazon Textract para operações assíncronas.

Você também pode especificar um parâmetro de entrada opcional,JobTag, que permite identificar o trabalho ou grupos de trabalhos no status de conclusão que é publicada no tópico do Amazon SNS. Por exemplo, você pode usarJobTagpara identificar o tipo de documento que está sendo processado, como um formulário fiscal ou recibo.

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 paraClientRequestToken, oStartA operação retorna o mesmoJobIdpara várias chamadas idênticas aoStartoperação, comoStartDocumentTextDetection. 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 Textract não envia um status de conclusão ao 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).

  • Se você reutilizar o token com uma operação Start diferente, a operação será bem-sucedida.

Outro parâmetro opcional disponível éOutputConfig, que permite ajustar onde sua saída será colocada. Por padrão, o Amazon Textract armazenará os resultados internamente e só poderá ser acessado pelas operações Get API. comOutputConfighabilitado, você pode definir o nome do bucket para o qual a saída será enviada e o prefixo do arquivo dos resultados, onde você pode baixar seus resultados. Além disso, você pode definir oKMSKeyIDparâmetro para uma chave gerenciada pelo cliente para criptografar sua saída. Sem esse conjunto de parâmetros, o Amazon Textract criptografará o lado do servidor usando oChave gerenciada pela AWSpara Amazon S3

nota

Antes de usar esse parâmetro, certifique-se de ter a permissão PutObject para o bucket de saída. Além disso, certifique-se de ter as permissões Decrypt, ReEnCrypt, GenerateDataKey e DescribeKey para oAWS KMSchave se você decidir usá-lo.

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

{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}

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

Se você acredita que exceções LimitExceededException estão sendo geradas com intermitências de atividade, considere a possibilidade de usar uma fila do Amazon SQS para gerenciar as solicitações recebidas. ContatoAWSSupport 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 você ainda está recebendoLimitExceededExceptionexceções.

Obter o status de conclusão de uma solicitação de análise do Amazon Textract

Amazon Textract 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 detecção de texto bem-sucedida tem umSUCCEEDEDStatus. Por exemplo, o resultado a seguir mostra o processamento bem-sucedido de um trabalho de detecção de texto.

{ "JobId": "642492aea78a86a40665555dc375ee97bc963f342b29cd05030f19bd8fd1bc5f", "Status": "SUCCEEDED", "API": "StartDocumentTextDetection", "JobTag": "Receipt", "Timestamp": 1543599965969, "DocumentLocation": { "S3ObjectName": "document", "S3Bucket": "bucket" } }

Para obter mais informações, consulte Notificação de resultados do Amazon Textract.

Para obter as informações de status publicadas no tópico do Amazon SNS pelo Amazon Textract, 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 Textract 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 detecção de texto. Por exemplo, você pode usar o código do lado do servidor para anotar a imagem ou criar um relatório no texto detectado antes de retornar as informações para um aplicativo cliente.

  • Amazon SQS— 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 publicado pelo Amazon Textract quando uma solicitação de detecção de texto é concluída. Para obter mais informações, consulte Detectando ou analisando texto em um documento de várias páginas. Use uma fila do Amazon SQS se desejar chamar as operações Amazon Textract somente a partir de um aplicativo cliente.

Importante

Nós não recomendamos obter o status de conclusão da solicitação chamando repetidamente o Amazon TextractGetoperação. Isso ocorre porque o Amazon Textract acelera oGetSe muitas solicitações forem realizadas. Se você estiver processando vários documentos ao mesmo tempo, é mais simples e mais eficiente monitorar uma fila do SQS para a notificação de conclusão do que pesquisar no Amazon Textract para o status de cada trabalho individualmente.

Obtendo resultados de detecção de texto Amazon Textract

Para obter os resultados de uma solicitação de detecção de texto, primeiro verifique se o status de conclusão que é recuperado do tópico do Amazon SNS éSUCCEEDED. Em seguida, chame GetDocumentTextDetection, que transmite o valor JobId que é retornado de StartDocumentTextDetection. O JSON solicitado é semelhante ao exemplo a seguir:

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

JobIdé o identificador da operação de detecção de texto. Como a detecção de texto pode gerar grandes quantidades de dados, useMaxResultsPara especificar o número máximo de resultados a serem retornados em um únicoGetoperação. O valor padrão paraMaxResultsÉ 1.000. Se você especificar um valor maior que 1.000, somente 1.000 resultados serão retornados. Se a operação não retornar todos os resultados, um token de paginação para a próxima página será retornado. Para obter a próxima página de resultados, especifique o token noNextTokenparâmetro .

nota

O Amazon Textract retém os resultados de operações assíncronas por 7 dias. Você não pode recuperar os resultados após esse período.

OGetDocumentTextDetectionO JSON solicitado da operação é semelhante ao seguinte. O número total de páginas detectadas é retornado emDocumentMetadata. O texto detectado é retornado noBlocksmatriz. Para obter mais informações sobre oBlockobjetos, consulteObjetos de resposta de detecção de texto e análise de.

{ "DocumentMetadata": { "Pages": 1 }, "JobStatus": "SUCCEEDED", "Blocks": [ { "BlockType": "PAGE", "Geometry": { "BoundingBox": { "Width": 1.0, "Height": 1.0, "Left": 0.0, "Top": 0.0 }, "Polygon": [ { "X": 0.0, "Y": 0.0 }, { "X": 1.0, "Y": 0.0 }, { "X": 1.0, "Y": 1.0 }, { "X": 0.0, "Y": 1.0 } ] }, "Id": "64533157-c47e-401a-930e-7ca1bb3ac3fa", "Relationships": [ { "Type": "CHILD", "Ids": [ "4297834d-dcb1-413b-8908-3b96866ebbb5", "1d85ba24-2877-4d09-b8b2-393833d769e9", "193e9c47-fd87-475a-ba09-3fda210d8784", "bd8aeb62-961b-4b47-b78a-e4ed9eeecd0f" ] } ], "Page": 1 }, { "BlockType": "LINE", "Confidence": 53.301639556884766, "Text": "ellooworio", "Geometry": { "BoundingBox": { "Width": 0.9999999403953552, "Height": 0.5365243554115295, "Left": 0.0, "Top": 0.46347561478614807 }, "Polygon": [ { "X": 0.0, "Y": 0.46347561478614807 }, { "X": 0.9999999403953552, "Y": 0.46347561478614807 }, { "X": 0.9999999403953552, "Y": 1.0 }, { "X": 0.0, "Y": 1.0 } ] }, "Id": "4297834d-dcb1-413b-8908-3b96866ebbb5", "Relationships": [ { "Type": "CHILD", "Ids": [ "170c3eb9-5155-4bec-8c44-173bba537e70" ] } ], "Page": 1 }, { "BlockType": "LINE", "Confidence": 89.15632629394531, "Text": "He llo,", "Geometry": { "BoundingBox": { "Width": 0.33642634749412537, "Height": 0.49159330129623413, "Left": 0.13885067403316498, "Top": 0.17169663310050964 }, "Polygon": [ { "X": 0.13885067403316498, "Y": 0.17169663310050964 }, { "X": 0.47527703642845154, "Y": 0.17169663310050964 }, { "X": 0.47527703642845154, "Y": 0.6632899641990662 }, { "X": 0.13885067403316498, "Y": 0.6632899641990662 } ] }, "Id": "1d85ba24-2877-4d09-b8b2-393833d769e9", "Relationships": [ { "Type": "CHILD", "Ids": [ "516ae823-3bab-4f9a-9d74-ad7150d128ab", "6bcf4ea8-bbe8-4686-91be-b98dd63bc6a6" ] } ], "Page": 1 }, { "BlockType": "LINE", "Confidence": 82.44834899902344, "Text": "worlo", "Geometry": { "BoundingBox": { "Width": 0.33182239532470703, "Height": 0.3766750991344452, "Left": 0.5091826915740967, "Top": 0.23131252825260162 }, "Polygon": [ { "X": 0.5091826915740967, "Y": 0.23131252825260162 }, { "X": 0.8410050868988037, "Y": 0.23131252825260162 }, { "X": 0.8410050868988037, "Y": 0.607987642288208 }, { "X": 0.5091826915740967, "Y": 0.607987642288208 } ] }, "Id": "193e9c47-fd87-475a-ba09-3fda210d8784", "Relationships": [ { "Type": "CHILD", "Ids": [ "ed135c3b-35dd-4085-8f00-26aedab0125f" ] } ], "Page": 1 }, { "BlockType": "LINE", "Confidence": 88.50325775146484, "Text": "world", "Geometry": { "BoundingBox": { "Width": 0.35004907846450806, "Height": 0.19635874032974243, "Left": 0.527581512928009, "Top": 0.30100569128990173 }, "Polygon": [ { "X": 0.527581512928009, "Y": 0.30100569128990173 }, { "X": 0.8776305913925171, "Y": 0.30100569128990173 }, { "X": 0.8776305913925171, "Y": 0.49736443161964417 }, { "X": 0.527581512928009, "Y": 0.49736443161964417 } ] }, "Id": "bd8aeb62-961b-4b47-b78a-e4ed9eeecd0f", "Relationships": [ { "Type": "CHILD", "Ids": [ "9e28834d-798e-4a62-8862-a837dfd895a6" ] } ], "Page": 1 }, { "BlockType": "WORD", "Confidence": 53.301639556884766, "Text": "ellooworio", "Geometry": { "BoundingBox": { "Width": 1.0, "Height": 0.5365243554115295, "Left": 0.0, "Top": 0.46347561478614807 }, "Polygon": [ { "X": 0.0, "Y": 0.46347561478614807 }, { "X": 1.0, "Y": 0.46347561478614807 }, { "X": 1.0, "Y": 1.0 }, { "X": 0.0, "Y": 1.0 } ] }, "Id": "170c3eb9-5155-4bec-8c44-173bba537e70", "Page": 1 }, { "BlockType": "WORD", "Confidence": 88.46246337890625, "Text": "He", "Geometry": { "BoundingBox": { "Width": 0.15350718796253204, "Height": 0.29955607652664185, "Left": 0.13885067403316498, "Top": 0.21856294572353363 }, "Polygon": [ { "X": 0.13885067403316498, "Y": 0.21856294572353363 }, { "X": 0.292357861995697, "Y": 0.21856294572353363 }, { "X": 0.292357861995697, "Y": 0.5181190371513367 }, { "X": 0.13885067403316498, "Y": 0.5181190371513367 } ] }, "Id": "516ae823-3bab-4f9a-9d74-ad7150d128ab", "Page": 1 }, { "BlockType": "WORD", "Confidence": 89.8501968383789, "Text": "llo,", "Geometry": { "BoundingBox": { "Width": 0.17724157869815826, "Height": 0.49159327149391174, "Left": 0.2980354428291321, "Top": 0.17169663310050964 }, "Polygon": [ { "X": 0.2980354428291321, "Y": 0.17169663310050964 }, { "X": 0.47527703642845154, "Y": 0.17169663310050964 }, { "X": 0.47527703642845154, "Y": 0.6632899045944214 }, { "X": 0.2980354428291321, "Y": 0.6632899045944214 } ] }, "Id": "6bcf4ea8-bbe8-4686-91be-b98dd63bc6a6", "Page": 1 }, { "BlockType": "WORD", "Confidence": 82.44834899902344, "Text": "worlo", "Geometry": { "BoundingBox": { "Width": 0.33182239532470703, "Height": 0.3766750991344452, "Left": 0.5091826915740967, "Top": 0.23131252825260162 }, "Polygon": [ { "X": 0.5091826915740967, "Y": 0.23131252825260162 }, { "X": 0.8410050868988037, "Y": 0.23131252825260162 }, { "X": 0.8410050868988037, "Y": 0.607987642288208 }, { "X": 0.5091826915740967, "Y": 0.607987642288208 } ] }, "Id": "ed135c3b-35dd-4085-8f00-26aedab0125f", "Page": 1 }, { "BlockType": "WORD", "Confidence": 88.50325775146484, "Text": "world", "Geometry": { "BoundingBox": { "Width": 0.35004907846450806, "Height": 0.19635874032974243, "Left": 0.527581512928009, "Top": 0.30100569128990173 }, "Polygon": [ { "X": 0.527581512928009, "Y": 0.30100569128990173 }, { "X": 0.8776305913925171, "Y": 0.30100569128990173 }, { "X": 0.8776305913925171, "Y": 0.49736443161964417 }, { "X": 0.527581512928009, "Y": 0.49736443161964417 } ] }, "Id": "9e28834d-798e-4a62-8862-a837dfd895a6", "Page": 1 } ] }