本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 調用 Amazon Textract 異步操作
<a name="api-async"></a>

Amazon Textract 提供了一個異步 API，您可以使用它來處理 PDF 或 TIFF 格式的多頁文檔。您還可以使用異步操作來處理 JPEG、PNG、TIFF 或 PDF 格式的單頁文檔。

本主題中的信息使用文本檢測操作來展示如何使用 Amazon Textract 異步操作。同樣的方法適用於[StartDocumentAnalysis](API_StartDocumentAnalysis.md)和[GetDocumentAnalysis](API_GetDocumentAnalysis.md)。它也適用於[StartExpenseAnalysis](API_StartExpenseAnalysis.md)和[GetExpenseAnalysis](API_GetExpenseAnalysis.md)。

如需範例，請參閱 [檢測或分析多頁文檔中的文本](async-analyzing-with-sqs.md)。

Amazon Textract 以非同步方式處理存放在 Amazon S3 儲存貯體中的檔案。您可以通過調用`Start`操作，例如[StartDocumentTextDetection](API_StartDocumentTextDetection.md)。請求的完成狀態將發佈至 Amazon SNS Simple Notification Service (Amazon SNS) 主題。若要自 Amazon SNS 主題取得完成狀態，您可以使用 Amazon Simple Queue Service (Amazon SQS) 排列或AWS Lambda函數。在獲得完成狀態後，可呼叫如 [GetDocumentTextDetection](API_GetDocumentTextDetection.md) 的 `Get` 操作來取得請求結果。

默認情況下，異步調用的結果 Amazon S3 被加密並存儲在 Amazon Textract 擁有的存儲桶中 7 天，除非您使用操作的`OutputConfig`引數。

下表顯示了 Amazon Textract 支持的不同異步處理類型的相應「開始」和「獲取」操作：


**啟動/取得亞馬遜文件異步操作的API 操作**  

| 處理類型 | 啟動 API | 取得 API | 
| --- | --- | --- | 
| 文字偵測 | StartDocumentTextDetection | GetDocumentTextDetection | 
| 文字分析 | StartDocumentAnalysis | GetDocumentAnalysis | 
| 費用分析 | 起始筆分析 | 地理軟件分析 | 

對於使用AWS Lambda函數，請參[使用 Amazon Textract 進行大規模文檔處理](https://github.com/aws-samples/amazon-textract-serverless-large-scale-document-processing)。

下圖顯示在 Amazon S3 儲存貯體中的檔案映像中偵測檔案的程序。在圖表內，Amazon SQS 佇列將自 Amazon SNS 主題取得完成狀態。

![\[alt text not found\]](http://docs.aws.amazon.com/zh_tw/textract/latest/dg/images/asynchronous.png)


前面圖所顯示的流程與分析文本和發票/收據的流程相同。您可以通過調用[StartDocumentAnalysis](API_StartDocumentAnalysis.md)並開始分析發票/收據，方法是調用[StartExpenseAnalysis](API_StartExpenseAnalysis.md)您可以通過調用[GetDocumentAnalysis](API_GetDocumentAnalysis.md)或者[GetExpenseAnalysis](API_GetExpenseAnalysis.md)分別。

## 啟動文字偵測
<a name="api-async-start"></a>

透過呼叫[StartDocumentTextDetection](API_StartDocumentTextDetection.md)。以下是由 `StartDocumentTextDetection` 傳遞的 JSON 請求範例。

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

輸入參數`DocumentLocation`提供檔案名稱以及從中取回檔案名稱的 Amazon S3 儲存貯體。`NotificationChannel`包含 Amazon SNS 主題的 Amazon Resource Name (ARN)，Amazon Amazon Textract N) 將在文本檢測請求完成時通知。Amazon SNS 主題必須與您呼叫的 Amazon Textract 端點位於同一個 AWS 區域。`NotificationChannel`也包含允許 Amazon Textract 發佈到 Amazon SNS 主題的角色 ARN。透過 IAM 服務角色，您將許可提供給 Amazon SNS 主題。如需詳細資訊，請參閱 [為異步操作配置 Amazon Textract](api-async-roles.md)。

您也可以指定可選輸入參數`JobTag`，可讓您找出顯示完成狀態且已發佈至 Amazon SNS 主題的任務或任務組。例如，您可以使用`JobTag`標識正在處理的單據類型，例如納税表或收據。

為避免分析任務發生意外的重複，您可以選擇性地提供等冪符記 `ClientRequestToken`。如果您提供`ClientRequestToken`，`Start`操作會傳回相同的`JobId`對於多個相同的調用`Start`操作，例如`StartDocumentTextDetection`。`ClientRequestToken` 符記有 7 天的存留期。在 7 天後，您可以再次使用它。如果您在符記的存留期內重新使用符記，會發生下列情況：
+ 如果您使用的 `Start` 操作與相同的輸入參數來重新使用符記，將傳回相同的 `JobId`。不會再次執行任務，而 Amazon Textract 也不會傳送完成狀態到已註冊的 Amazon SNS 主題。
+ 如果您以相同的 `Start` 操作搭配些微變更的參數來重新使用符記，您會得到一個 `idempotentparametermismatchexception` (HTTP 狀態碼：400) 例外狀況。
+ 如果您以不同的 `Start` 操作來重新使用符記，操作將可成功。

另一個可選參數是`OutputConfig`，它允許您調整輸出的放置位置。默認情況下，Amazon Textract 將在內部存儲結果，並且只能通過獲取 API 操作訪問。搭配`OutputConfig`，您可以設置將輸出發送到的存儲桶的名稱以及結果的文件前綴，您可以在其中下載結果。此外，您也可以設定`KMSKeyID`參數添加到客户託管密鑰來加密您的輸出。如果沒有此參數設置，Amazon Textract 將使用AWS 受管金鑰適用於 Amazon S3

**注意**  
在使用此參數之前，請確保您具有輸出存儲桶的 PutObject 權限。此外，請確保您具有解密、ReEncrypt、GenerateDataKey 和 DescribeKey 權限AWS KMS鍵，如果您決定使用它。

對於 `StartDocumentTextDetection` 操作的回應為任務識別碼 (`JobId`)。使用`JobId`追蹤請求並在 Amazon Textract 發佈完成狀態到 Amazon SNS 主題後取得分析結果。以下是範例：

```
{"JobId":"270c1cc5e1d0ea2fbc59d97cb69a72a5495da75851976b14a1784ca90fc180e3"}
```

如果同時啟動太多作業，請調用`StartDocumentTextDetection`RETURN`LimitExceededException`例外狀況 (HTTP 狀態碼：400)，直到數量同時執行任務的數量低於 Amazon Textract 服務限制。

如果您發現限制拒絕例外狀況發生且產生活動激增，請考慮使用 Amazon SQS 排列來管理傳入的請求。聯絡AWS如果您 Support 現同時進行的請求的平均數量無法由 Amazon SQS 排列控管，而您仍收到`LimitExceededException`例外狀況。

## 取得 Amazon Textract 分析請求的完成狀態
<a name="api-async-get-status"></a>

Amazon Textract 將傳送分析完成通知道已註冊的 Amazon SNS 主題。通知包含任務識別碼和並以 JSON 字串顯示操作的完成狀態。成功的文本檢測請求具有`SUCCEEDED`狀態。例如，以下結果顯示文字偵測任務的成功處理。

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

如需詳細資訊，請參閱 [Amazon Textract 結果通知](async-notification-payload.md)。

若要取得 Amazon Amazon Textract 發佈至 Amazon SNS 主題的狀態資訊，請使用以下其中一個選項：
+ **AWS Lambda**— 您可以訂AWS Lambda函數，以寫入 Amazon SNS 主題。當 Amazon Textract 通知 Amazon SNS 主題請求已完成時，將呼叫此功能。如果您需要伺服器端程式碼來處理文字偵測請求的結果，請使用 Lambda 函數。例如，您可能想要使用服務器端代碼來標註映像，或在傳回信息到客户端應用程式前針對檢測到的文本創建報告。
+ **Amazon SQS**— 您可以訂 Amazon SQS 佇列至 Amazon SNS 主題。接著請輪詢 Amazon SQS 排列以取得由 Amazon Textract 在文本檢測請求完成時發佈的完成狀態。如需詳細資訊，請參閱 [檢測或分析多頁文檔中的文本](async-analyzing-with-sqs.md)。如果您只想從客户端應用程式呼叫 Amazon Textract 操作，請使用 Amazon SQS 佇列。

**重要**  
我們不建議您透過重複呼叫 Amazon Textract 來取得請求完成狀態`Get`operation. 這是因為 Amazon Textract 會限制`Get`操作，如果執行太多請求。如果您同時處理多個檔案，監控一個 SQS 排列的完成通知將會比輪詢 Amazon Textract 以獲得個別任務的狀態更容易且有效率。

## 獲取 Amazon Textract 檢測結果
<a name="api-async-get"></a>

若要取得文本檢測請求結果，首先請確認自 Amazon SNS 主題檢索的完成狀態為`SUCCEEDED`。然後呼叫 `GetDocumentTextDetection`，將傳遞自 `StartDocumentTextDetection` 傳回的 `JobId` 值。請求 JSON 格式類似於以下範例：

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

`JobId`是文本檢測操作的標識符。由於文字偵測可以生成大量數據，請使用`MaxResults`來指定傳回結果的最大數量，以在單個`Get`operation. 的預設預設預設值`MaxResults`是 1,000 個。如果您指定的值大於 1,000，將只會傳回 1,000 個結果。如果操作未返回所有結果，將傳回下一頁的分頁令牌。若要取得下一頁的結果，請在`NextToken`參數。

**注意**  
Amazon Textract 會保留異步操作的結果 7 天。在此時間後您無法取得結果。

所以此`GetDocumentTextDetection`操作響應 JSON 格式類似如下。檢測到的頁面總數在`DocumentMetadata`。檢測到的文本將在`Blocks`陣列。關於的資訊`Block`對象，請參閲[文本檢測和文檔分析響應對象](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
        }
    ]
}
```