Appel d'opérations asynchrones Amazon Textract

Amazon Textract fournit une API asynchrone que vous pouvez utiliser pour traiter des documents multipages 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. La même approche fonctionne avec les opérations d'analyse de texte deStartDocumentAnalysisetGetDocumentAnalysis. Il fonctionne également de la même manière avecStartExpenseAnalysisetGetExpenseAnalysis.

Pour voir un exemple, consultez Détection ou analyse de texte dans un document multipage.

Amazon Textract traite de manière asynchrone un document stocké dans un compartiment Amazon S3. Vous commencez le traitement en appelant unStartopération, telle queStartDocumentTextDetection. Le statut d'achèvement de la demande est publié dans une rubrique Amazon Simple Notification Service (Amazon SNS). Pour obtenir le statut d'achèvement dans la rubrique Amazon SNS, vous pouvez utiliser une file d'attente Amazon Simple Queue Service (Amazon SQS) ou uneAWS Lambda. 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 d'une opérationOutputConfigargument.

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

Opérations d'API Start/Get pour Amazon Textract Asynchronous Operations
Type de traitement	API de démarrage	Obtenez l'API
Détection de texte	StartDocumentTextDetection	GetDocumentTextDetection
Analyse de texte	StartDocumentAnalysis	GetDocumentAnalysis
Analyse des dépenses	Commencer l'analyse des dépenses	Obtenez une analyse des dépenses

Pour un exemple qui utiliseAWS Lambdafonctions, consultezTraitement de documents à grande échelle avec Amazon Textract.

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

Le processus affiché par le diagramme précédent est le même pour l'analyse du texte et des factures/reçus. Vous commencez à analyser du texte en appelantStartDocumentAnalysiset commencez à analyser les factures/reçus en appelantStartExpenseAnalysisVous obtenez les résultats en appelantGetDocumentAnalysisouGetExpenseAnalysisrespectivement.

Détection de texte

Vous lancez une demande de détection de texte Amazon Textract en appelantStartDocumentTextDetection. 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éeDocumentLocationfournit le nom du fichier de document et le compartiment Amazon S3 dont ce fichier peut être extrait.NotificationChannelcontient l'Amazon Resource Name (ARN) de la rubrique Amazon SNS que Amazon Textract informe 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 pour un rôle qui permet à Amazon Textract de publier dans la rubrique Amazon SNS. Vous attribuez des autorisations de publication Amazon Textract à vos rubriques 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 en option,JobTag, qui vous permet d'identifier la tâche ou les groupes de tâches dans le statut d'achèvement publié dans la rubrique Amazon SNS. Par exemple, vous pouvez utiliserJobTagpour identifier le type de document traité, 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, leStartrenvoie la même opérationJobIdpour plusieurs appels identiques à laStartopération, telle 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 de statut 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 est :OutputConfig, qui vous permet de régler l'endroit où votre sortie sera placée. Par défaut, Amazon Textract stocke les résultats en interne et n'est accessible que par les opérations Obtenir l'API. avecOutputConfigactivé, vous pouvez définir le nom du compartiment vers lequel la sortie sera envoyée et le préfixe de fichier des résultats, dans lequel vous pouvez télécharger vos résultats. De plus, vous pouvez définir leKMSKeyIDd'une clé gérée par le client pour chiffrer votre sortie. Sans ce jeu de paramètres, Amazon Textract chiffrera côté serveur à l'aide de la commandeClé gérée par AWSpour Amazon S3

Note

Avant d'utiliser ce paramètre, assurez-vous que vous disposez de l'autorisation PutObject pour le compartiment de sortie. En outre, assurez-vous que vous disposez des autorisations Decrypt, ReEncrypt, GenerateDataKey et DescribeKey pour leAWS KMSsi vous décidez de l'utiliser.

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

{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}

Si vous commencez trop de tâches simultanément, appelez àStartDocumentTextDetectionRAISE UNELimitExceededExceptionexception (code de statut HTTP : 400) jusqu'à ce que le nombre de tâches exécutées simultanément soit inférieur à la limite de service Amazon Textract.

Si vous constatez que les exceptions LimitExceededException sont générées lors des périodes d'activité, vous devez envisager d'utiliser une file d'attente Amazon SQS afin de gérer les demandes entrantes. ContacterAWSSupport si vous constatez que le nombre moyen de demandes simultanées ne peut pas être géré par une file d'attente Amazon SQS et que vous continuez à recevoirLimitExceededExceptionexceptions.

Obtention du statut d'achèvement d'une demande d'analyse Amazon Textract

Amazon Textract envoie une notification d'achèvement 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 comporte unSUCCEEDEDÉtat. Par exemple, le résultat suivant illustre la réussite du traitement 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 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 unAWS Lambdaque vous écrivez dans une rubrique Amazon SNS. La fonction est appelée quand Amazon Textract informe 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 pouvez 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 vers une application cliente.

• Amazon SQS— Vous pouvez abonner une file d'attente Amazon SQS à une rubrique Amazon SNS. Vous pouvez ensuite interroger la file d'attente Amazon SQS pour extraire le statut d'achèvement publié par Amazon Textract lorsqu'une demande de détection de texte se termine. Pour plus d'informations, consultez Détection ou analyse de texte dans un document multipage. Utilisez une file d'attente Amazon SQS si vous souhaitez appeler des opérations Amazon Textract uniquement à partir d'une application cliente.

Important

Nous vous déconseillons d'obtenir le statut d'achèvement de la demande en appelant de manière répétée le Amazon TextractGet. Cela est dû au fait qu'Amazon Textract limite leGetsi de trop nombreuses demandes sont lancées. Si vous traitez plusieurs documents simultanément, il est plus simple et plus efficace de surveiller la création d'une notification d'achèvement dans une file d'attente SQS que d'interroger Amazon Textract pour obtenir le statut de chaque tâche individuellement.

Obtention des résultats de détection de texte Amazon Textract

Pour obtenir les résultats d'une demande de détection de texte, assurez-vous tout d'abord que le statut d'achèvement extrait de la rubrique Amazon SNS est.SUCCEEDED. 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'identificateur de l'opération de détection de texte. Étant donné que la détection de texte peut générer de grandes quantités de données, utilisezMaxResultspour spécifier le nombre maximal de résultats à renvoyer en une seule foisGet. La valeur par défaut deMaxResultsest de 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 la page de résultatsNextToken  Paramètre .

Note

Amazon Textract conserve les résultats d'opérations asynchrone pendant 7 jours. Passé ce délai, vous ne pouvez pas récupérer les résultats.

LeGetDocumentTextDetectionJSON d'une réponse d'opération est similaire à ce qui suit. Le nombre total de pages détectées est renvoyé dansDocumentMetadata. Le texte détecté est renvoyé dans leBlockstableau. Pour obtenir des informations surBlockobjets, voirObjets de réponse Détection de texte et 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
        }
    ]
}