Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Memanggil Operasi Asinkron Amazon Texact
Amazon Textract menyediakan API asinkron yang dapat Anda gunakan untuk memproses dokumen multipage dalam format PDF atau TIFF. Anda juga dapat menggunakan operasi asinkron untuk memproses dokumen satu halaman yang ada dalam format JPEG, PNG, TIFF, atau PDF.
Informasi dalam topik ini menggunakan operasi pendeteksian teks untuk menunjukkan cara menggunakan operasi asinkron Amazon Texact. Pendekatan yang sama bekerja dengan operasi analisis teks[StartDocumentAnalysis](API_StartDocumentAnalysis.md)dan[GetDocumentAnalysis](API_GetDocumentAnalysis.md). Ini juga bekerja sama dengan[StartExpenseAnalysis](API_StartExpenseAnalysis.md)dan[GetExpenseAnalysis](API_GetExpenseAnalysis.md).
Sebagai contoh, lihat [Mendeteksi atau Menganalisis Teks dalam Dokumen Multipage](async-analyzing-with-sqs.md).
Amazon Textract Texact secara tidak sinkron memproses dokumen yang tersimpan di bucket Amazon S3. Anda mulai memproses dengan memanggil`Start`operasi, seperti[StartDocumentTextDetection](API_StartDocumentTextDetection.md). Status penyelesaian untuk permintaan diterbitkan ke topik Amazon Simple Notification Service (Amazon SNS). Untuk mendapatkan status penyelesaian dari topik Amazon SNS, Anda dapat menggunakan antrean Amazon Simple Queue Service (Amazon SQS) atau fungsi AWS Lambda. Setelah Anda memiliki status penyelesaian, Anda perlu memanggil operasi `Get`, seperti [GetDocumentTextDetection](API_GetDocumentTextDetection.md), untuk mendapatkan hasil permintaan.
Hasil panggilan asinkron dienkripsi dan disimpan selama 7 hari dalam bucket milik Amazon Textract Texact secara default, kecuali jika Anda menetapkan bucket Amazon S3 menggunakan operasi`OutputConfig`argumen.
Tabel berikut menunjukkan operasi Start and Get yang sesuai untuk berbagai jenis pemrosesan asinkron yang didukung oleh Amazon Textract:
**Mulai/Dapatkan Operasi API untuk Operasi Asinkron Amazon Texact**
| Jenis Pengolahan | Mulai API | Dapatkan API |
| --- | --- | --- |
| Pendeteksi teks | StartDocumentTextDetection | GetDocumentTextDetection |
| Analisis Teks | StartDocumentAnalysis | GetDocumentAnalysis |
| Analisis Beban | StartExpenseAnalysis | GetExpenseAnalysis |
Untuk contoh yang menggunakanAWS Lambdafungsi, lihat[Pemrosesan dokumen berskala besar dengan Amazon Textract](https://github.com/aws-samples/amazon-textract-serverless-large-scale-document-processing).
Diagram berikut menunjukkan proses untuk mendeteksi teks dokumen dalam citra dokumen yang tersimpan di bucket Amazon S3. Dalam diagram, antrean Amazon SQS mendapatkan status penyelesaian dari topik Amazon SNS.
![\[alt text not found\]](http://docs.aws.amazon.com/id_id/textract/latest/dg/images/asynchronous.png)
Proses yang ditampilkan oleh diagram sebelumnya adalah sama untuk menganalisis teks dan faktur/tanda terima. Anda mulai menganalisis teks dengan menelepon[StartDocumentAnalysis](API_StartDocumentAnalysis.md)dan mulai menganalisis faktur/tanda terima dengan menelepon[StartExpenseAnalysis](API_StartExpenseAnalysis.md)Anda mendapatkan hasilnya dengan menelepon[GetDocumentAnalysis](API_GetDocumentAnalysis.md)atau[GetExpenseAnalysis](API_GetExpenseAnalysis.md)masing-masing.
## Pendeteksi teks
Anda memulai permintaan pendeteksi teks Amazon Texact dengan menelepon[StartDocumentTextDetection](API_StartDocumentTextDetection.md). Berikut ini adalah contoh permintaan JSON yang diberikan oleh `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"
}
```
Parameter input`DocumentLocation`menyediakan nama file dokumen dan bucket Amazon S3 untuk mengambilnya.`NotificationChannel`berisi Amazon Resource Name (ARN) dari topik Amazon SNS yang memberi tahu Amazon Textract saat permintaan pendeteksi teks selesai. Topik Amazon SNS harus berada di Wilayah AWS yang sama dengan titik akhir Amazon Textract Texact yang Anda hubungi.`NotificationChannel`juga berisi ARN untuk peran yang memungkinkan Amazon Textract untuk mempublikasikan ke topik Amazon SNS. Anda memberikan izin penerbitan Amazon Textract Texact untuk topik Amazon SNS Anda dengan menciptakan peran layanan IAM. Untuk informasi selengkapnya, lihat [Mengkonfigurasi Amazon Textract untuk Operasi Asynchronous](api-async-roles.md).
Anda juga dapat menentukan parameter input opsional,`JobTag`, yang mengizinkan Anda untuk mengidentifikasi tugas, atau kelompok tugas, dalam status penyelesaian yang diterbitkan untuk topik Amazon SNS. Misalnya, Anda dapat menggunakan`JobTag`untuk mengidentifikasi jenis dokumen yang sedang diproses, seperti formulir pajak atau tanda terima.
Untuk mencegah duplikasi pekerjaan analisis yang tidak disengaja, Anda dapat memberikan token idempotensi , `ClientRequestToken`. Jika Anda memberikan nilai untuk`ClientRequestToken`, yang`Start`operasi mengembalikan yang sama`JobId`untuk beberapa panggilan identik ke`Start`operasi, seperti`StartDocumentTextDetection`. Token `ClientRequestToken` memiliki masa pakai 7 hari. Setelah 7 hari, Anda bisa menggunakannya kembali. Jika Anda menggunakan kembali token selama masa token aktif, hal berikut akan terjadi:
+ Jika Anda menggunakan kembali token dengan sama`Start`operasi dan parameter input yang sama, sama`JobId`dikembalikan. Tugas tidak akan dilakukan lagi dan Amazon Textract Texact tidak mengirimkan status penyelesaian ke topik Amazon SNS yang terdaftar.
+ Jika Anda menggunakan kembali token dengan operasi `Start` dan perubahan pada input parameter kecil, Anda mendapatkan pengecualian yang ditimbulkan `idempotentparametermismatchexception` (Kode status HTTP: 400).
+ Jika Anda menggunakan kembali token dengan yang berbeda`Start`operasi, operasi berhasil.
Parameter opsional lain yang tersedia adalah`OutputConfig`, yang memungkinkan Anda menyesuaikan di mana output Anda akan ditempatkan. Secara default, Amazon Textract akan menyimpan hasil secara internal, dan hanya dapat diakses oleh operasi Get API. Dengan`OutputConfig`diaktifkan, Anda dapat mengatur nama bucket output akan dikirim ke, dan awalan file hasil, di mana Anda dapat men-download hasil Anda. Selain itu, Anda dapat mengatur`KMSKeyID`parameter ke kunci yang dikelola pelanggan untuk mengenkripsi output Anda. Tanpa parameter ini, Amazon Textract akan mengenkripsi sisi server menggunakanKunci yang dikelola AWSuntuk Amazon S3
**catatan**
Sebelum menggunakan parameter ini, pastikan Anda memiliki izin PutObject untuk bucket output. Selain itu, pastikan Anda memiliki izin Decrypt, ReEncrypt, GenerateDataKey, dan DescribeKey untukAWS KMSkunci jika Anda memutuskan untuk menggunakannya.
Respons terhadap operasi `StartDocumentTextDetection` adalah pengidentifikasi tugas (`JobId`). Gunakan`JobId`untuk melacak permintaan dan mendapatkan hasil analisis setelah Amazon Textract Texact menerbitkan status penyelesaian ke topik Amazon SNS. Berikut ini adalah contoh:
```
{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}
```
Jika Anda memulai terlalu banyak pekerjaan secara bersamaan, panggilan ke`StartDocumentTextDetection`menaikkan`LimitExceededException`exception (Kode status HTTP: 400) hingga jumlah tugas yang berjalan bersamaan di bawah batas layanan Amazon Textract Texact.
Jika Anda menemukan bahwa pengecualian LimitExceededException dimunculkan dengan rongsokan aktivitas, mohon pertimbangkan untuk menggunakan antrean Amazon SQS untuk mengelola permintaan yang masuk. KontakAWSSupport jika Anda menemukan bahwa jumlah rata-rata permintaan bersamaan tidak dapat dikelola oleh antrean Amazon SQS dan Anda masih menerima`LimitExceededException`pengecualian.
## Mendapatkan Status Penyelesaian Permintaan Analisis Amazon Textract
Amazon Textract Texact mengirimkan notifikasi penyelesaian analisis ke topik Amazon SNS yang terdaftar. Pemberitahuan tersebut mencakup pengindentifikasi tugas dan status penyelesaian operasi dalam string JSON. Permintaan deteksi teks yang sukses memiliki`SUCCEEDED`status. Misalnya, hasil berikut menunjukkan berhasilnya pengolahan tugas pendeteksi teks.
```
{
"JobId": "642492aea78a86a40665555dc375ee97bc963f342b29cd05030f19bd8fd1bc5f",
"Status": "SUCCEEDED",
"API": "StartDocumentTextDetection",
"JobTag": "Receipt",
"Timestamp": 1543599965969,
"DocumentLocation": {
"S3ObjectName": "document",
"S3Bucket": "bucket"
}
}
```
Untuk informasi selengkapnya, lihat [Pemberitahuan Amazon Textract](async-notification-payload.md).
Untuk mendapatkan status informasi yang dipublikasikan ke topik Amazon SNS, gunakan salah satu opsi berikut:
+ **AWS Lambda** — Anda dapat berlangganan fungsi AWS Lambda yang Anda tulis untuk topik Amazon SNS. Fungsi ini dipanggil saat Amazon Textract memberi tahu topik Amazon SNS bahwa permintaannya telah selesai. Gunakan fungsi Lambda jika Anda menginginkan kode sisi server untuk memproses hasil permintaan deteksi teks. Misalnya, Anda mungkin ingin menggunakan kode sisi server untuk menganotasi gambar atau membuat laporan tentang teks yang terdeteksi sebelum mengembalikan informasi ke aplikasi klien.
+ **Amazon SQS**— Anda dapat berlangganan antrean Amazon SQS ke topik Amazon SNS. Anda kemudian dapat melakukan polling antrean Amazon SQS untuk mengambil status penyelesaian yang diterbitkan oleh Amazon Textract saat permintaan pendeteksi teks selesai. Untuk informasi selengkapnya, lihat [Mendeteksi atau Menganalisis Teks dalam Dokumen Multipage](async-analyzing-with-sqs.md). Gunakan antrean Amazon SQS jika Anda ingin memanggil operasi Amazon Textract Texact hanya dari aplikasi klien.
**penting**
Kami tidak merekomendasikan untuk mendapatkan status penyelesaian permintaan dengan berulang kali memanggil Amazon Textract`Get`operasi. Hal ini karena Amazon Textract Texact throttles`Get`operasi jika terlalu banyak permintaan yang dibuat. Jika Anda memproses beberapa dokumen secara bersamaan, akan lebih mudah dan lebih efisien untuk memantau satu antrean SQS untuk notifikasi penyelesaian daripada membuat polling Amazon Textract untuk status setiap pekerjaan secara individual.
## Mendapatkan Hasil Deteksi Amazon Textract Texact
Untuk mendapatkan hasil permintaan pendeteksi teks, pertama pastikan bahwa status penyelesaian yang diambil dari topik Amazon SNS adalah`SUCCEEDED`. Kemudian panggil `GetDocumentTextDetection`, yang memberikan nilai `JobId` yang dikembalikan dari `StartDocumentTextDetection`. Permintaan JSON serupa dengan contoh berikut:
```
{
"JobId": "270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3",
"MaxResults": 10,
"SortBy": "TIMESTAMP"
}
```
`JobId`adalah pengidentifikasi untuk operasi deteksi teks. Karena deteksi teks dapat menghasilkan data dalam jumlah besar, gunakan`MaxResults`untuk menentukan jumlah hasil maksimum yang akan dikembalikan dalam satu`Get`operasi. Nilai default untuk`MaxResults`adalah 1.000. Jika Anda menentukan nilai yang lebih besar dari 1.000, hanya 1.000 hasil yang dikembalikan. Jika operasi tidak mengembalikan semua hasil, token pagination untuk halaman berikutnya dikembalikan. Untuk mendapatkan halaman hasil berikutnya, tentukan token di`NextToken`parameter.
**catatan**
Amazon Textract Texact mempertahankan hasil operasi asinkron selama 7 hari. Anda tidak dapat mengambil hasilnya setelah waktu ini.
Parameter`GetDocumentTextDetection`respon operasi JSON serupa dengan yang berikut ini. Jumlah total halaman yang terdeteksi dikembalikan`DocumentMetadata`. Teks yang terdeteksi dikembalikan dalam`Blocks`array. Untuk informasi tentang`Block`benda, lihat[Deteksi Teks dan Dokumen Analisis Respon Objek](how-it-works-document-layout.md).
```
{
"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
}
]
}
```