View a markdown version of this page

Llamar a Amazon Textract Asynchronous Operations - Amazon Textract

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.

Llamar a Amazon Textract Asynchronous Operations

Amazon Textract proporciona una API asincrónica que puede usar para procesar documentos de varias páginas en formato PDF o TIFF. También puede utilizar operaciones asincrónicas para procesar documentos de una sola página en formato JPEG, PNG, TIFF o PDF.

La información de este tema utiliza operaciones de detección de texto para mostrar cómo utilizar las operaciones asincrónicas de Amazon Textract. Puede utilizar el mismo enfoque con las operaciones de análisis de texto de y. StartDocumentAnalysis GetDocumentAnalysis También funciona de la misma manera con StartExpenseAnalysis y GetExpenseAnalysis.

Para ver un ejemplo, consulta Detectar o analizar texto en un documento de varias páginas.

Si está analizando documentos de préstamo, puede utilizar la StartLendingAnalysis operación para clasificar las páginas de los documentos y enviar las páginas clasificadas a una operación de análisis de Amazon Textract. Las páginas se envían a las operaciones de análisis en función de la clase asignada.

Puede recuperar los resultados de páginas individuales mediante la GetLendingAnalysis operación o recuperar un resumen del análisis con. GetLendingAnalysisSummary

Amazon Textract procesa de forma asíncrona un documento almacenado en un bucket de Amazon S3. Para empezar a procesar, llame a una Start operación, como. StartDocumentTextDetection El estado de finalización de la solicitud se publica en un tema de Amazon Simple Notification Service (Amazon SNS). Para obtener el estado de finalización del tema de Amazon SNS, puede utilizar una cola o una función de Amazon Simple Queue Service (Amazon SQS). AWS Lambda Una vez que disponga del estado de realización, llame a una operación Get, como GetDocumentTextDetection, para obtener los resultados de la solicitud.

Los resultados de las llamadas asincrónicas se cifran y almacenan durante 7 días en un bucket propiedad de Amazon Textract de forma predeterminada, a menos que especifique un bucket de Amazon S3 mediante el argumento de una operación. OutputConfig Para obtener información sobre cómo permitir que Amazon Textract envíe documentos cifrados a su bucket de Amazon S3, consulte. Permisos para la configuración de salida

La siguiente tabla muestra las operaciones Start y Get correspondientes a los diferentes tipos de procesamiento asincrónico admitidos por Amazon Textract:

Start/Get Operaciones de API para operaciones asincrónicas de Amazon Textract
Tipo de procesamiento API de inicio Obtenga la API
Detección de texto StartDocumentTextDetection GetDocumentTextDetection
Análisis de texto StartDocumentAnalysis GetDocumentAnalysis
Análisis de gastos StartExpenseAnalysis GetExpenseAnalysis
Análisis de préstamos StartLendingAnalysis GetLendingAnalysis, GetLendingAnalysisSummary

Para ver un ejemplo en el que se utilizan AWS Lambda funciones, consulte Procesamiento de documentos a gran escala con Amazon Textract.

El siguiente diagrama muestra el proceso para detectar el texto de un documento en una imagen de documento almacenada en un bucket de Amazon S3. En el diagrama, una cola de Amazon SQS obtiene el estado de realización a partir del tema de Amazon SNS.

Diagrama que muestra un flujo de trabajo de Amazon Textract con los pasos clave: iniciar y devolver el ID del trabajo, procesar el documento en un bucket de S3, publicar el estado de finalización en un tema de SNS, supervisar la cola de SQS para ver el estado de finalización y llamar GetDocumentTextDetection para obtener los resultados del análisis.

El proceso que se muestra en el diagrama anterior es el mismo para analizar texto y. invoices/receipts Empiezas a analizar el texto llamando StartDocumentAnalysis y empiezas a analizar invoices/receipts llamando. StartExpenseAnalysis Obtienes los resultados llamando GetDocumentAnalysis o GetExpenseAnalysis respectivamente.

Inicio de la detección de texto

Para iniciar una solicitud de detección de texto de Amazon Textract, llame StartDocumentTextDetection. El siguiente es un ejemplo de una solicitud JSON que ha transferido 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" }

El parámetro de entrada DocumentLocation proporciona el nombre del archivo del documento y el bucket de Amazon S3 desde el que recuperarlo. NotificationChannelcontiene el nombre de recurso de Amazon (ARN) del tema de Amazon SNS que Amazon Textract notifica cuando finaliza la solicitud de detección de texto. El tema de Amazon SNS debe estar en la misma región de AWS que el punto de enlace de Amazon Textract al que está llamando. NotificationChanneltambién contiene el ARN de un rol que permite a Amazon Textract publicar en el tema de Amazon SNS. Para conceder permisos de publicación a Amazon Textract para sus temas de Amazon SNS, debe crear un rol de servicio de IAM. Para obtener más información, consulte Configuración de Amazon Textract para operaciones asincrónicas.

También puede especificar un parámetro de entrada opcional que le permita identificar el trabajo, o los grupos de trabajos, en estado de finalización publicado en el tema de Amazon SNS. JobTag Por ejemplo, puede usarlo JobTag para identificar el tipo de documento que se está procesando, como un formulario de impuestos o un recibo.

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 paraClientRequestToken, la Start operación devuelve lo mismo JobId para varias llamadas idénticas a la Start operación, comoStartDocumentTextDetection. 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 y Amazon Textract no envía el estado de finalización al tema registrado de Amazon SNS.

  • 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).

  • Si reutiliza el token con otra operación Start distinta, la operación se realiza correctamente.

Otro parámetro opcional disponible es OutputConfig el que le permite ajustar el lugar en el que se colocará la salida. De forma predeterminada, Amazon Textract almacenará los resultados internamente y solo se podrá acceder a ellos mediante las operaciones de Get API. Si OutputConfig está habilitada, puede establecer el nombre del depósito al que se enviará la salida y el prefijo de archivo de los resultados, donde podrá descargarlos. Además, puedes configurar el KMSKeyID parámetro en una clave gestionada por el cliente para cifrar los resultados. Sin este conjunto de parámetros, Amazon Textract cifrará los datos del lado del servidor utilizando el para Amazon S3 Clave administrada de AWS

nota

Antes de usar este parámetro, asegúrese de tener el PutObject permiso para usar el bucket de salida. Además, asegúrese de que dispone de los DescribeKey permisos de descifrado y descifrado para la AWS KMS clave si decide utilizarla. ReEncrypt GenerateDataKey

La respuesta a la operación StartDocumentTextDetection es un identificador de trabajo (JobId). JobIdUtilícela para realizar un seguimiento de las solicitudes y obtener los resultados del análisis una vez que Amazon Textract haya publicado el estado de finalización en el tema de Amazon SNS. A continuación, se muestra un ejemplo:

{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}

Si inicia demasiados trabajos al mismo tiempo, haga una llamada para StartDocumentTextDetection generar una LimitExceededException excepción (código de estado HTTP: 400) hasta que el número de trabajos en ejecución simultánea esté por debajo del límite del servicio de Amazon Textract.

Si descubre que se generan LimitExceededException excepciones con ráfagas de actividad, considere la posibilidad de utilizar una cola de Amazon SQS para gestionar las solicitudes entrantes. Ponte en contacto con el equipo de AWS soporte si descubres que una cola de Amazon SQS no puede gestionar tu número medio de solicitudes simultáneas y sigues recibiendo excepciones. LimitExceededException

Obtener el estado de finalización de una solicitud de análisis de Amazon Textract

Amazon Textract envía una notificación de finalización del análisis al tema registrado en Amazon SNS. 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 detección de texto satisfactoria tiene un SUCCEEDED estado. Por ejemplo, el siguiente resultado muestra el procesamiento correcto de un trabajo de detección de texto.

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

Para obtener más información, consulte Notificación de resultados de Amazon Textract.

Para obtener la información de estado publicada por Amazon Textract 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. La función se activa cuando Amazon Textract notifica al tema de Amazon SNS que la solicitud se ha completado. Utilice una función Lambda si desea que el código del lado del servidor procese los resultados de una solicitud de detección de texto. Por ejemplo, es posible que desee usar código del lado del servidor para anotar la imagen o crear un informe sobre el texto detectado antes de devolver la información a una aplicación cliente.

  • Amazon SQS: puede suscribir una cola de Amazon SQS a un tema de Amazon SNS. A continuación, sondea la cola de Amazon SQS para recuperar el estado de finalización publicado por Amazon Textract cuando se completa una solicitud de detección de texto. Para obtener más información, consulte Detectar o analizar texto en un documento de varias páginas. Utilice una cola de Amazon SQS si quiere llamar a las operaciones de Amazon Textract únicamente desde una aplicación cliente.

importante

No recomendamos obtener el estado de finalización de la solicitud llamando repetidamente a la operación de Amazon Textract. Get Esto se debe a que Amazon Textract limita la Get operación si se realizan demasiadas solicitudes. Si procesa varios documentos al mismo tiempo, es más sencillo y eficaz supervisar una cola de SQS para recibir la notificación de finalización que sondear Amazon Textract para ver el estado de cada trabajo de forma individual.

Si ha configurado su cuenta para recibir una notificación de resultados de un tema de Amazon Simple Notification Service (Amazon SNS) o a través de una cola de Amazon SQS, debe asegurarse de que su cuenta es segura limitando el alcance del acceso de Amazon Textract solo a los recursos que está utilizando. Para ello, puede adjuntar una política de confianza a su rol de servicio de IAM. Para obtener información sobre cómo hacerlo, consulte Cross-service Prevención de la confusión entre agentes.

Obtención de los resultados de detección de texto de Amazon Textract

Para obtener los resultados de una solicitud de detección de mensajes de texto, asegúrese primero de que el estado de finalización obtenido del tema de Amazon SNS es. SUCCEEDED A continuación, llame a GetDocumentTextDetection, que transfiere el valor JobId que se devuelve desde StartDocumentTextDetection. El JSON de la solicitud es similar al siguiente ejemplo:

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

JobIdes el identificador de la operación de detección de texto. Dado que la detección de texto puede generar grandes cantidades de datos, MaxResults utilícelo para especificar el número máximo de resultados que se devolverán en una sola Get operación. El valor predeterminado de MaxResults es 1000. Si especifica un valor superior a 1000, solo se devolverán 1000 resultados. Si la operación no devuelve todos los resultados, se devuelve un token de paginación para la página siguiente. Para obtener la siguiente página de resultados, especifica el token en el NextToken parámetro.

nota

Los resultados solo se pueden recuperar hasta 7 días después del tiempo de inicialización del trabajo.

El JSON de respuesta de la GetDocumentTextDetection operación es similar al siguiente. El número total de páginas detectadas se devuelve enDocumentMetadata. El texto detectado se devuelve en la Blocks matriz. Para obtener información sobre Block los objetos, consulteObjetos de respuesta para la detección de texto y el análisis de documentos.

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

Uso de un adaptador

Con Amazon Textract, puede usar un adaptador al llamar a la StartDocumentAnalysis operación. Para usar un adaptador, primero debe crear y entrenar un adaptador mediante la consola de Amazon Textract. Para aplicar el adaptador, proporcione su ID al llamar a la operación de la StartDocumentAnalysis API. Al llamar a la StartDocumentAnalysis operación, puedes usar hasta un adaptador por página.

"AdaptersConfig": { "Adapters": [ { "AdapterId": "2e9bf1c4aa31", "Version": "1", "Pages": [ "1" ] } ] }