Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
Chiamata di Amazon Textract Asynchronous Operations
Amazon Textract fornisce un'API asincrona che puoi utilizzare per elaborare documenti multipagina in formato PDF o TIFF. È inoltre possibile utilizzare operazioni asincrone per elaborare documenti a pagina singola in formato JPEG, PNG, TIFF o PDF.
Le informazioni contenute in questo argomento utilizzano le operazioni di rilevamento del testo per mostrare come utilizzare le operazioni asincrone di Amazon Textract. Lo stesso approccio funziona con le operazioni di analisi testuale diStartDocumentAnalysiseGetDocumentAnalysis. Funziona allo stesso modo conStartExpenseAnalysiseGetExpenseAnalysis.
Per un esempio, consultare Rilevamento o analisi del testo in un documento multipagina.
Amazon Textract elabora in modo asincrono un documento archiviato in un bucket Amazon S3. Si avvia l'elaborazione chiamando unStartoperazione, comeStartDocumentTextDetection. Lo stato di completamento della richiesta viene pubblicato in un argomento Amazon Simple Notification Service (Amazon SNS). Per ottenere lo stato di completamento dall'argomento Amazon SNS, puoi utilizzare una coda Amazon Simple Queue Service (Amazon SQS) o unaAWS Lambdafunzione. Dopo aver acquisito lo stato di completamento, chiama un'operazione Get, come ad esempio GetDocumentTextDetection, per ottenere i risultati della richiesta.
I risultati delle chiamate asincrone vengono crittografati e archiviati per 7 giorni in un bucket di proprietà di Amazon Textract per impostazione predefinita, a meno che tu non specifichi un bucket Amazon S3 utilizzandoOutputConfigArgomento.
La tabella seguente mostra le operazioni Start e Get corrispondenti per i diversi tipi di elaborazione asincrona supportata da Amazon Textract:
| Tipo di elaborazione | Avvia API | Ottieni API |
|---|---|---|
| Rilevamento del testo | StartDocumentTextDetection | GetDocumentTextDetection |
| Analisi del testo | StartDocumentAnalysis | GetDocumentAnalysis |
| Analisi delle spese | Avviare l'analisi delle spese | Ottieni analisi delle spese |
Per un esempio che utilizzaAWS Lambdafunzioni, vedereElaborazione di documenti su larga scala con Amazon Textract
Il seguente diagramma mostra il processo di rilevamento del testo in un'immagine documento archiviata in un bucket Amazon S3. Nel diagramma, una coda Amazon SQS ottiene lo stato di completamento dall'argomento Amazon SNS.
Il processo visualizzato dal diagramma precedente è lo stesso per l'analisi del testo e delle fatture/ricevute. Si inizia ad analizzare il testo chiamandoStartDocumentAnalysise inizia ad analizzare fatture/ricevute chiamandoStartExpenseAnalysisSi ottengono i risultati chiamandoGetDocumentAnalysisoGetExpenseAnalysisrispettivamente.
Avvio del rilevamento del testo
Puoi avviare una richiesta di rilevamento del testo Amazon Textract chiamandoStartDocumentTextDetection. Di seguito è riportato un esempio di una richiesta JSON passata da 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" }
Parametri di inputDocumentLocationfornisce il nome del file del documento e il bucket Amazon S3 da cui recuperarlo.NotificationChannelcontiene l'Amazon Resource Name (ARN) dell'argomento Amazon SNS che viene notificato da Amazon Textract al termine della richiesta di rilevamento del testo. L'argomento Amazon SNS deve trovarsi nella stessa regione AWS dell'endpoint Amazon Textract che stai chiamando.NotificationChannelcontiene inoltre l'ARN relativo a un ruolo che consente ad Amazon Textract di pubblicare nell'argomento Amazon SNS. Puoi fornire autorizzazioni per la pubblicazione di Amazon Textract ai tuoi argomenti Amazon SNS creando un ruolo di servizio IAM. Per ulteriori informazioni, consultare Configurazione di Amazon Textract per operazioni asincrone.
È anche possibile specificare un parametro di input facoltativo,JobTag, che ti consente di identificare il processo o i gruppi di processi, nello stato di completamento pubblicato nell'argomento Amazon SNS. Ad esempio, è possibile utilizzareJobTagper identificare il tipo di documento elaborato, ad esempio un modulo fiscale o una ricevuta.
Per evitare la duplicazione accidentale dei processi di analisi, puoi facoltativamente fornire un token idempotente, ClientRequestToken. Se fornisci un valore perClientRequestToken, ilStartrestituisce lo stessoJobIdper più chiamate identiche alStartoperazione, comeStartDocumentTextDetection. Un token ClientRequestToken ha un ciclo di vita di 7 giorni. Dopo 7 giorni, puoi riutilizzarlo. Se riutilizzi il token durante il suo ciclo di vita, si verifica quanto segue:
-
Se riutilizzi il token con la stessa operazione
Starte gli stessi parametri di input, viene restituito lo stessoJobId. Il processo non viene rieseguito e Amazon Textract non invia uno stato di completamento all'argomento Amazon SNS registrato. -
Se riutilizzi il token con la stessa operazione
Starte un parametro di input secondario viene modificato, viene sollevata un'eccezioneidempotentparametermismatchexception(codice di stato HTTP: 400). -
Se riutilizzi il token con un'altra operazione
Start, l'operazione va a buon fine.
Un altro parametro opzionale disponibile èOutputConfig, che consente di regolare la posizione in cui verrà posizionato l'output. Per impostazione predefinita, Amazon Textract memorizzerà i risultati internamente e sarà accessibile solo dalle operazioni Ottieni API. conOutputConfigabilitato, è possibile impostare il nome del bucket a cui verrà inviato l'output e il prefisso del file dei risultati, dove è possibile scaricare i risultati. Inoltre, è possibile impostare ilKMSKeyIDparametro di una chiave gestita dal cliente per crittografare l'output. Senza questo set di parametri Amazon Textract crittograferà il lato server utilizzando ilChiave gestita da AWSper Amazon S3
Nota
Prima di utilizzare questo parametro, assicurarsi di disporre dell'autorizzazione PutObject per il bucket di output. Inoltre, assicurati di disporre delle autorizzazioni Decrypt, ReEncrypt, GenerateDataKey e DescribeKey per ilAWS KMSchiave se decidi di usarlo.
La risposta all'operazione StartDocumentTextDetection è un identificatore del processo (JobId). UtilizzaJobIdtenere traccia delle richieste e ottenere i risultati dell'analisi dopo che Amazon Textract ha pubblicato lo stato di completamento nell'argomento Amazon SNS. Di seguito è riportato un esempio:
{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}
Se inizi troppi lavori contemporaneamente, chiama aStartDocumentTextDetectionRAISE ALimitExceededExceptioneccezione (codice di stato HTTP: 400) finché il numero di processi simultanei in esecuzione è inferiore al service limit Amazon Textract.
Se riscontri che vengono sollevate eccezioni LimitExceededException con picchi di attività, potresti utilizzare una coda Amazon SQS per gestire le richieste in arrivo. ContattiAWSSupport se riscontri che il numero medio di richieste simultanee non può essere gestito da una coda Amazon SQS e ricevi ancoraLimitExceededExceptioneccezioni.
Ottenimento dello stato di completamento di una richiesta Amazon Textract Analysis
Amazon Textract invia una notifica di completamento dell'analisi all'argomento Amazon SNS registrato. La notifica include l'identificatore del processo e lo stato di completamento dell'operazione in una stringa JSON. Una richiesta di rilevamento testuale riuscita ha unSUCCEEDEDstato. Ad esempio, il risultato seguente mostra l'elaborazione corretta di un processo di rilevamento del testo.
{ "JobId": "642492aea78a86a40665555dc375ee97bc963f342b29cd05030f19bd8fd1bc5f", "Status": "SUCCEEDED", "API": "StartDocumentTextDetection", "JobTag": "Receipt", "Timestamp": 1543599965969, "DocumentLocation": { "S3ObjectName": "document", "S3Bucket": "bucket" } }
Per ulteriori informazioni, consultare Notifica dei risultati Amazon Textract.
Per ottenere le informazioni sullo stato pubblicate nell'argomento Amazon SNS da Amazon Textract, utilizza una delle seguenti opzioni:
-
AWS Lambda— Puoi sottoscrivere unAWS Lambdafunzione scritta in un argomento Amazon SNS. La funzione viene chiamata quando Amazon Textract notifica all'argomento Amazon SNS che la richiesta è stata completata. Utilizza una funzione Lambda se desideri che il codice lato server elabori i risultati di una richiesta di rilevamento del testo. Ad esempio, potresti voler utilizzare il codice lato server per annotare l'immagine o creare un report sul testo rilevato prima di restituire le informazioni a un'applicazione client.
-
Amazon SQS— Puoi sottoscrivere una coda Amazon SQS a un argomento Amazon SNS. Puoi quindi eseguire il polling della coda Amazon SQS per recuperare lo stato di completamento pubblicato da Amazon Textract al completamento di una richiesta di rilevamento testuale. Per ulteriori informazioni, consultare Rilevamento o analisi del testo in un documento multipagina. Utilizza una coda Amazon SQS se desideri chiamare le operazioni Amazon Textract solo da un'applicazione client.
Importante
Non è consigliabile ottenere lo stato di completamento della richiesta chiamando ripetutamente Amazon TextractGetoperazione. Questo perché Amazon Textract strozza ilGetSe vengono effettuate troppe richieste. Se si elaborano più documenti contemporaneamente, è più semplice ed efficiente monitorare una coda SQS per la notifica di completamento anziché eseguire il polling di Amazon Textract per lo stato di ciascun processo singolarmente.
Ottenere i risultati del rilevamento del testo Amazon Textract
Per ottenere i risultati di una richiesta di rilevamento testuale, accertati prima che lo stato di completamento recuperato dall'argomento Amazon SNS siaSUCCEEDED. Quindi chiama GetDocumentTextDetection che trasferisce il valore JobId restituito da StartDocumentTextDetection. La struttura JSON della richiesta è simile all'esempio riportato di seguito:
{ "JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3", "MaxResults": 10, "SortBy": "TIMESTAMP" }
JobIdè l'identificatore per l'operazione di rilevamento del testo. Poiché il rilevamento di testo può generare grandi quantità di dati, utilizzaMaxResultsper specificare il numero massimo di risultati da restituire in un singoloGetoperazione. Il valore predefinito perMaxResultsè 1.000. Se si specifica un valore maggiore di 1.000, vengono restituiti solo 1.000 risultati. Se l'operazione non restituisce tutti i risultati, viene restituito un token di paginazione per la pagina successiva. Per visualizzare la pagina di risultati successiva, specificare il token nellaNextTokenParametro .
Nota
Amazon Textract conserva i risultati delle operazioni asincrone per 7 giorni. Non è possibile recuperare i risultati dopo questo periodo.
LaGetDocumentTextDetectionLa struttura JSON della risposta dell'operazione è simile a quello riportato di seguito. Il numero totale di pagine rilevate viene restituito inDocumentMetadata. Il testo rilevato viene restituito nellaBlocksarray. Per informazioni suBlockoggetti, vediOggetti di risposta di rilevamento del testo e analisi dei documenti.
{ "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 } ] }
