View a markdown version of this page

Appeler Amazon Textract asynchronous Operations - Amazon Textract

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Appeler Amazon Textract asynchronous Operations

Amazon Textract fournit une API asynchrone que vous pouvez utiliser pour traiter des documents de plusieurs pages au format PDF ou TIFF. Vous pouvez également utiliser des opérations asynchrones pour traiter des documents d'une seule page au format JPEG, PNG, TIFF ou PDF.

Les informations de cette rubrique utilisent des opérations de détection de texte pour montrer comment utiliser les opérations asynchrones Amazon Textract. Vous pouvez utiliser la même approche pour les opérations d'analyse de texte de StartDocumentAnalysis et GetDocumentAnalysis. Cela fonctionne également de la même manière avec StartExpenseAnalysis et GetExpenseAnalysis.

Pour obtenir un exemple, consultez Détection ou analyse de texte dans un document de plusieurs pages.

Si vous analysez des documents de prêt, vous pouvez utiliser cette StartLendingAnalysis opération pour classer les pages des documents et envoyer les pages classées à une opération d'analyse Amazon Textract. Les pages sont acheminées vers les opérations d'analyse en fonction de la classe qui leur est attribuée.

Vous pouvez récupérer les résultats de pages individuelles à l'aide de l'GetLendingAnalysisopération, ou récupérer un résumé de l'analyse avec. GetLendingAnalysisSummary

Amazon Textract traite de manière asynchrone un document stocké dans un compartiment Amazon S3. Vous commencez le traitement en appelant une Start opération, telle que StartDocumentTextDetection. L’état d’achèvement de la demande est publié dans une rubrique Amazon Simple Notification Service (Amazon SNS). Pour obtenir l'état d'achèvement à partir de la rubrique Amazon SNS, vous pouvez utiliser une file d'attente Amazon Simple Queue Service (Amazon SQS) ou une AWS Lambda fonction. Après avoir obtenu le statut d'achèvement, vous appelez une opération Get telle que GetDocumentTextDetection pour obtenir le résultat de la demande.

Les résultats des appels asynchrones sont chiffrés et stockés pendant 7 jours dans un compartiment appartenant à Amazon Textract par défaut, sauf si vous spécifiez un compartiment Amazon S3 à l'aide de l'argument d'une opération. OutputConfig Pour savoir comment autoriser Amazon Textract à envoyer des documents chiffrés vers votre compartiment Amazon S3, consultezAutorisations pour la configuration des sorties.

Le tableau suivant présente les opérations Start et Get correspondantes pour les différents types de traitement asynchrone pris en charge par Amazon Textract :

Start/Get Opérations d'API pour les opérations asynchrones Amazon Textract
Type de traitement API de démarrage Obtenir l'API
Détection de texte StartDocumentTextDetection GetDocumentTextDetection
Analyse de texte StartDocumentAnalysis GetDocumentAnalysis
Analyse des dépenses StartExpenseAnalysis GetExpenseAnalysis
Analyse des prêts StartLendingAnalysis GetLendingAnalysis, GetLendingAnalysisSummary

Pour un exemple utilisant des AWS Lambda fonctions, consultez la section Traitement de documents à grande échelle avec Amazon Textract.

Le schéma suivant montre le processus de détection du texte d'un document dans une image de document stockée dans un compartiment Amazon S3. Dans ce schéma, une file d’attente Amazon SNS obtient le statut d’achèvement à partir de la rubrique SNS.

Schéma illustrant un flux de travail Amazon Textract avec les étapes clés : démarrer et renvoyer l'identifiant de la tâche, traiter le document dans un compartiment S3, publier l'état d'achèvement dans la rubrique SNS, surveiller la file d'attente SQS pour connaître l'état d'achèvement, appeler GetDocumentTextDetection pour obtenir les résultats de l'analyse.

Le processus affiché par le schéma précédent est le même pour l'analyse de texte et invoices/receipts. Vous commencez à analyser du texte en appelant StartDocumentAnalysis et commencez à analyser invoices/receipts en appelant StartExpenseAnalysis Vous obtenez les résultats en appelant GetDocumentAnalysis ou GetExpenseAnalysis respectivement.

Démarrage de la détection de texte

Vous lancez une demande de détection de texte Amazon Textract en appelant StartDocumentTextDetection. L’exemple suivant est une demande JSON transmise par 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" }

Le paramètre d'entrée DocumentLocation fournit le nom du fichier du document et le compartiment Amazon S3 depuis lequel le récupérer. NotificationChannelcontient le nom de ressource Amazon (ARN) de la rubrique Amazon SNS qu'Amazon Textract notifie lorsque la demande de détection de texte est terminée. La rubrique Amazon SNS doit se trouver dans la même région AWS que le point de terminaison Amazon Textract que vous appelez. NotificationChannelcontient également l'ARN d'un rôle qui permet à Amazon Textract de publier sur la rubrique Amazon SNS. Vous autorisez Amazon Textract à publier vos sujets Amazon SNS en créant un rôle de service IAM. Pour plus d’informations, consultez Configuration d'Amazon Textract pour les opérations asynchrones.

Vous pouvez également spécifier un paramètre d'entrée facultatif qui vous permet d'identifier la tâche, ou les groupes de tâches, dans l'état d'achèvement publié dans la rubrique Amazon SNS. JobTag Par exemple, vous pouvez l'utiliser JobTag pour identifier le type de document en cours de traitement, tel qu'un formulaire fiscal ou un reçu.

Afin d’éviter toute duplication accidentelle des tâches d’analyse, vous pouvez, si vous le souhaitez, fournir un jeton idempotent, ClientRequestToken. Si vous fournissez une valeur pourClientRequestToken, l'Startopération renvoie la même valeur JobId pour plusieurs appels identiques à l'Startopération, tels queStartDocumentTextDetection. 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 Textract n'envoie pas d'état d'achèvement à la rubrique Amazon SNS enregistrée.

  • Si vous réutilisez le jeton avec la même opération Start et une modification mineure du paramètre d’entrée, vous obtenez une exception idempotentparametermismatchexception (code de statut HTTP : 400).

  • Si vous réutilisez le jeton avec une autre opération Start, l'opération aboutit.

Un autre paramètre optionnel disponible OutputConfig vous permet de régler l'emplacement de votre sortie. Par défaut, Amazon Textract stocke les résultats en interne et n'est accessible que par les opérations de l'API Get. OutputConfigLorsque cette option est activée, vous pouvez définir le nom du compartiment auquel la sortie sera envoyée, ainsi que le préfixe du fichier des résultats, dans lequel vous pouvez télécharger vos résultats. En outre, vous pouvez définir le KMSKeyID paramètre sur une clé gérée par le client pour chiffrer votre sortie. Si ce paramètre n'est pas défini, Amazon Textract chiffrera côté serveur à l'aide de la fonction pour Amazon S3 Clé gérée par AWS

Note

Avant d'utiliser ce paramètre, assurez-vous de disposer de l' PutObject autorisation pour le bucket de sortie. En outre, assurez-vous de disposer des DescribeKey autorisations de déchiffrement ReEncrypt GenerateDataKey,, et de la AWS KMS clé si vous décidez de l'utiliser.

La réponse à l’opération StartDocumentTextDetection est un identifiant de tâche (JobId). Utilisez-le JobId pour suivre les demandes et obtenir les résultats de l'analyse une fois qu'Amazon Textract a publié l'état d'achèvement dans la rubrique Amazon SNS. Voici un exemple :

{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}

Si vous démarrez trop de tâches simultanément, des appels sont lancés pour StartDocumentTextDetection déclencher une LimitExceededException exception (code d'état HTTP : 400) jusqu'à ce que le nombre de tâches exécutées simultanément soit inférieur à la limite du service Amazon Textract.

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

Obtenir le statut d'achèvement d'une demande d'analyse Amazon Textract

Amazon Textract envoie une notification de fin d'analyse à la rubrique Amazon SNS enregistrée. La notification comprend l’identifiant de la tâche et le statut d’achèvement de l’opération dans une chaîne JSON. Une demande de détection de texte réussie possède un SUCCEEDED statut. Par exemple, le résultat suivant montre le traitement réussi d'une tâche de détection de texte.

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

Pour plus d’informations, consultez Notification des résultats d'Amazon Textract.

Pour obtenir les informations de statut publiées dans la rubrique Amazon SNS par Amazon Textract, utilisez l'une des options suivantes :

  • AWS Lambda : vous pouvez abonner une fonction AWS Lambda que vous écrivez à une rubrique Amazon SNS. La fonction est appelée lorsqu'Amazon Textract indique à la rubrique Amazon SNS que 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 de détection de texte. Par exemple, vous souhaiterez peut-être utiliser du code côté serveur pour annoter l'image ou créer un rapport sur le texte détecté avant de renvoyer les informations à une application cliente.

  • Amazon SQS  : vous pouvez abonner une file d'attente Amazon SQS à une rubrique Amazon SNS. Vous interrogez ensuite la file d'attente Amazon SQS pour récupérer l'état d'achèvement publié par Amazon Textract lorsqu'une demande de détection de texte est terminée. Pour plus d’informations, consultez Détection ou analyse de texte dans un document de plusieurs pages. Utilisez une file d'attente Amazon SQS si vous souhaitez appeler les opérations Amazon Textract uniquement depuis une application cliente.

Important

Nous ne recommandons pas d'obtenir le statut d'achèvement de la demande en appelant à plusieurs reprises l'Getopération Amazon Textract. Cela est dû au fait qu'Amazon Textract limite l'Getopération si un trop grand nombre de demandes sont effectuées. Si vous traitez plusieurs documents en même temps, il est plus simple et plus efficace de surveiller une file d'attente SQS pour la notification d'achèvement que de demander à Amazon Textract le statut de chaque tâche individuellement.

Si vous avez configuré votre compte pour recevoir une notification de résultats provenant d'une rubrique Amazon Simple Notification Service (Amazon SNS) ou via une file d'attente Amazon SQS, vous devez vous assurer que votre compte est sécurisé en limitant l'étendue de l'accès d'Amazon Textract aux seules ressources que vous utilisez. Pour ce faire, attachez une politique de confiance à votre fonction du service IAM. Pour plus d'informations sur la procédure à suivre, voir Prévention des adjoints Cross-service confus.

Obtenir les résultats de détection de texte d'Amazon Textract

Pour obtenir les résultats d'une demande de détection de texte, assurez-vous d'abord que l'état d'achèvement extrait de la rubrique Amazon SNS est SUCCEEDED le même. Ensuite, appelez GetDocumentTextDetection, qui transmet la valeur JobId renvoyée par StartDocumentTextDetection. Le format JSON de la demande est similaire à l’exemple suivant :

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

JobIdest l'identifiant de l'opération de détection de texte. La détection de texte pouvant générer de grandes quantités de données, utilisez MaxResults cette option pour spécifier le nombre maximum de résultats à renvoyer en une seule Get opération. La valeur par défaut pour MaxResults est 1 000. Si vous spécifiez une valeur supérieure à 1 000, seuls 1 000 résultats sont renvoyés. Si l'opération ne renvoie pas tous les résultats, un jeton de pagination pour la page suivante est renvoyé. Pour obtenir la page de résultats suivante, spécifiez le jeton dans le NextToken paramètre.

Note

Les résultats ne peuvent être récupérés que dans les 7 jours suivant l'initialisation de la tâche.

La réponse de GetDocumentTextDetection l'opération JSON est similaire à la suivante. Le nombre total de pages détectées est renvoyé dansDocumentMetadata. Le texte détecté est renvoyé dans le Blocks tableau. Pour plus d'informations sur Block les objets, consultezObjets de réponse à la détection de texte et à l'analyse de documents.

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

À l'aide d'un adaptateur

Avec Amazon Textract, vous pouvez utiliser un adaptateur lorsque vous appelez l'StartDocumentAnalysisopération. Pour utiliser un adaptateur, vous devez d'abord créer et entraîner un adaptateur à l'aide de la console Amazon Textract. Pour appliquer votre adaptateur, indiquez son identifiant lors de l'appel de l'opération StartDocumentAnalysis API. Lorsque vous appelez l'StartDocumentAnalysisopération, vous pouvez utiliser jusqu'à un adaptateur par page.

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