本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Amazon Comprehend 洞察的非同步分析
下列各節使用 Amazon Comprehend API 執行非同步操作，以分析 Amazon Comprehend 洞察。
**Topics**
+ [先決條件](#detect-topics-role-auth)
+ [啟動分析任務](#how-start-job)
+ [監控分析任務](#how-monitor-progress)
+ [取得分析結果](#how-get-results)
## 先決條件
文件必須使用 UTF-8-formatted的文字檔案。您可以提交兩種格式的文件。您使用的格式取決於您要分析的文件類型，如下表所述。
| Description | 格式 |
| --- | --- |
| 每個檔案都包含一個輸入文件。這最適合用於大型文件的集合。 | 每個檔案一份文件 |
| 輸入是一或多個檔案。檔案中的每一行都被視為文件。這最適合短文件，例如社交媒體貼文。
每行必須以換行 (LF、\\n)、歸位 (CR、\\r) 或兩者 (CRLF、\\r\\n) 結尾。您無法使用 UTF-8 行分隔符號 (u\+2028) 來結束行。 | 每行一個文件 |
當您啟動分析任務時，您可以指定輸入資料的 S3 位置。URI 必須與您呼叫的 API 端點位於相同的 AWS 區域。URI 可以指向單一檔案，也可以是資料檔案集合的字首。如需詳細資訊，請參閱 [InputDataConfig](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html) 資料類型。
您必須授予 Amazon Comprehend 存取包含文件集合和輸出檔案的 Amazon S3 儲存貯體。如需詳細資訊，請參閱[非同步操作所需的角色型許可](security_iam_id-based-policy-examples.md#auth-role-permissions)。
## 啟動分析任務
若要提交分析任務，請使用 Amazon Comprehend 主控台或適當的`Start*`操作：
+ [StartDominantLanguageDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDominantLanguageDetectionJob.html) — 開始任務以偵測集合中每個文件中的主要語言。如需文件中主要語言的詳細資訊，請參閱 [主要語言](how-languages.md)。
+ [StartEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartEntitiesDetectionJob.html) — 啟動任務以偵測集合中每個文件中的實體。如需實體的詳細資訊，請參閱[實體](how-entities.md)。
+ [StartKeyPhrasesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartKeyPhrasesDetectionJob.html) — 啟動任務以偵測集合中每個文件中的金鑰片語。如需金鑰片語的詳細資訊，請參閱 [金鑰片語](how-key-phrases.md)。
+ [StartPiiEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartPiiEntitiesDetectionJob.html) — 開始任務以偵測集合中每個文件中的個人身分識別資訊 (PII)。如需 PII 的詳細資訊，請參閱 [偵測 PII 實體](how-key-phrases.md)。
+ [StartSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartSentimentDetectionJob.html) — 啟動任務以偵測集合中每個文件中的情緒。如需情緒的詳細資訊，請參閱 [情緒](how-sentiment.md)。
## 監控分析任務
`Start*` 操作會傳回您可用來監控任務進度的 ID。
若要使用 API 監控進度，您可以使用兩個操作之一，取決於您要監控個別任務或多個任務的進度。
若要監控個別分析任務的進度，請使用 `Describe*`操作。您提供 `Start*`操作傳回的任務 ID。來自 `Describe*`操作的回應包含具有任務狀態`JobStatus`的欄位。
若要監控多個分析任務的進度，請使用 `List*`操作。 `List*`操作會傳回您提交至 Amazon Comprehend 的任務清單。回應包含每個任務`JobStatus`的欄位，告知您任務的狀態。
如果狀態欄位設定為 `COMPLETED`或 `FAILED`，則任務處理已完成。
若要取得個別任務的狀態，請將 `Describe*`操作用於您正在執行的分析。
+ [DescribeDominantLanguageDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeDominantLanguageDetectionJob.html)
+ [DescribeEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeEntitiesDetectionJob.html)
+ [DescribeKeyPhrasesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeKeyPhrasesDetectionJob.html)
+ [DescribePiiEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribePiiEntitiesDetectionJob.html)
+ [DescribeSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeSentimentDetectionJob.html)
若要取得多個任務的狀態，請將 `List*`操作用於您正在執行的分析。
+ [ListDominantLanguageDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListDominantLanguageDetectionJobs.html)
+ [ListEntitiesDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListEntitiesDetectionJobs.html)
+ [ListKeyPhrasesDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListKeyPhrasesDetectionJobs.html)
+ [ListPiiEntitiesDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListPiiEntitiesDetectionJobs.html)
+ [ListSentimentDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListSentimentDetectionJobs.html)
若要將結果限制為符合特定條件的任務，請使用 `List*`操作的 `Filter` 參數。您可以篩選任務名稱、任務狀態，以及提交任務的日期和時間。如需詳細資訊，請參閱 Amazon Comprehend API 參考中每個`List*`操作的 `Filter` 參數。
## 取得分析結果
分析任務完成後，請使用 `Describe*`操作來取得結果的位置。如果任務狀態為 `COMPLETED`，回應會包含 `OutputDataConfig` 欄位，其中包含具有輸出檔案 Amazon S3 位置的欄位。檔案 `output.tar.gz`是包含分析結果的壓縮封存。
如果任務的狀態為 `FAILED`，回應會包含一個`Message`欄位，描述分析任務未成功完成的原因。
若要取得個別任務的狀態，請使用適當的`Describe*`操作：
+ [DescribeDominantLanguageDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeDominantLanguageDetectionJob.html)
+ [DescribeEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeEntitiesDetectionJob.html)
+ [DescribeKeyPhrasesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeKeyPhrasesDetectionJob.html)
+ [DescribeSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeSentimentDetectionJob.html)
結果會以單一檔案傳回，每個文件都有一個 JSON 結構。每個回應檔案也包含狀態欄位設定為 之任何任務的錯誤訊息`FAILED`。
下列各節顯示兩種輸入格式的輸出範例。
### 取得主要語言偵測結果
以下是 分析中偵測到慣用語言的輸出檔案範例。輸入的格式是每行一個文件。如需詳細資訊，請參閱 [DetectDominantLanguage](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectDominantLanguage.html) 操作。
```
{"File": "0_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9514502286911011}, {"LanguageCode": "de", "Score": 0.02374090999364853}, {"LanguageCode": "nl", "Score": 0.003208699868991971}, "Line": 0}
{"File": "1_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9822712540626526}, {"LanguageCode": "de", "Score": 0.002621392020955682}, {"LanguageCode": "es", "Score": 0.002386554144322872}], "Line": 1}
```
以下是 分析的輸出範例，其中輸入格式為每個檔案一個文件：
```
{"File": "small_doc", "Languages": [{"LanguageCode": "en", "Score": 0.9728053212165833}, {"LanguageCode": "de", "Score": 0.007670710328966379}, {"LanguageCode": "es", "Score": 0.0028472368139773607}]}
{"File": "huge_doc", "Languages": [{"LanguageCode": "en", "Score": 0.984955906867981}, {"LanguageCode": "de", "Score": 0.0026436643674969673}, {"LanguageCode": "fr", "Score": 0.0014206881169229746}]}
```
### 取得實體偵測結果
以下是 分析中偵測到文件中實體的輸出檔案範例。輸入的格式是每行一個文件。如需詳細資訊，請參閱 [DetectEntities](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectEntities.html) 操作。輸出包含兩個錯誤訊息，一個用於太長的文件，另一個用於非 UTF-8 格式的文件。
```
{"File": "50_docs", "Line": 0, "Entities": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.9763959646224976, "Text": "Cluj-NapocaCluj-Napoca", "Type": "LOCATION"}"]}
{"File": "50_docs", "Line": 1, "Entities": [{"BeginOffset": 11, "EndOffset": 15, "Score": 0.9615424871444702, "Text": "Maat", "Type": "PERSON"}}]}
{"File": "50_docs", "Line": 2, "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size exceeds maximum size limit 102400 bytes."}
{"File": "50_docs", "Line": 3, "ErrorCode": "UNSUPPORTED_ENCODING", "ErrorMessage": "Document is not in UTF-8 format and all subsequent lines are ignored."}
```
以下是 分析的輸出範例，其中輸入格式是每個檔案一個文件。輸出包含兩個錯誤訊息，一個用於太長的文件，另一個用於非 UTF-8 格式的文件。
```
{"File": "non_utf8.txt", "ErrorCode": "UNSUPPORTED_ENCODING", "ErrorMessage": "Document is not in UTF-8 format and all subsequent line are ignored."}
{"File": "small_doc", "Entities": [{"BeginOffset": 0, "EndOffset": 4, "Score": 0.645766019821167, "Text": "Maat", "Type": "PERSON"}]}
{"File": "huge_doc", "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size exceeds size limit 102400 bytes."}
```
### 取得金鑰片語偵測結果
以下是分析中偵測到文件中金鑰片語的輸出檔案範例。輸入的格式是每行一個文件。如需詳細資訊，請參閱 [DetectKeyPhrases](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectKeyPhrases.html) 操作。
```
{"File": "50_docs", "KeyPhrases": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.8948641419410706, "Text": "Cluj-NapocaCluj-Napoca"}, {"BeginOffset": 45, "EndOffset": 49, "Score": 0.9989854693412781, "Text": "Cluj"}], "Line": 0}
```
以下是 分析輸出的範例，其中輸入格式是每個檔案一個文件。
```
{"File": "1_doc", "KeyPhrases": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.8948641419410706, "Text": "Cluj-NapocaCluj-Napoca"}, {"BeginOffset": 45, "EndOffset": 49, "Score": 0.9989854693412781, "Text": "Cluj"}]}
```
### 取得個人身分識別資訊 (PII) 偵測結果
以下是分析任務的輸出檔案範例，可偵測文件中的 PII 實體。輸入的格式是每行一個文件。
```
{"Entities":[{"Type":"NAME","BeginOffset":40,"EndOffset":69,"Score":0.999995},{"Type":"ADDRESS","BeginOffset":247,"EndOffset":253,"Score":0.998828},{"Type":"BANK_ACCOUNT_NUMBER","BeginOffset":406,"EndOffset":411,"Score":0.693283}],"File":"doc.txt","Line":0}
{"Entities":[{"Type":"SSN","BeginOffset":1114,"EndOffset":1124,"Score":0.999999},{"Type":"EMAIL","BeginOffset":3742,"EndOffset":3775,"Score":0.999993},{"Type":"PIN","BeginOffset":4098,"EndOffset":4102,"Score":0.999995}],"File":"doc.txt","Line":1}
```
以下是 分析的輸出範例，其中輸入格式是每個檔案一個文件。
```
{"Entities":[{"Type":"NAME","BeginOffset":40,"EndOffset":69,"Score":0.999995},{"Type":"ADDRESS","BeginOffset":247,"EndOffset":253,"Score":0.998828},{"Type":"BANK_ROUTING","BeginOffset":279,"EndOffset":289,"Score":0.999999}],"File":"doc.txt"}
```
### 取得情緒偵測結果
以下是 分析的輸出檔案範例，可偵測文件中表達的情緒。它包含錯誤訊息，因為一個文件太長。輸入的格式是每行一個文件。如需詳細資訊，請參閱 [DetectSentiment](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectSentiment.html) 操作。
```
{"File": "50_docs", "Line": 0, "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.002734508365392685, "Negative": 0.008935936726629734, "Neutral": 0.9841893315315247, "Positive": 0.004140198230743408}}
{"File": "50_docs", "Line": 1, "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size is exceeded maximum size limit 5120 bytes."}
{"File": "50_docs", "Line": 2, "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.0023119584657251835, "Negative": 0.0029857370536774397, "Neutral": 0.9866572022438049, "Positive": 0.008045154623687267}}
```
以下是 分析輸出的範例，其中輸入格式是每個檔案一個文件。
```
{"File": "small_doc", "Sentiment": "NEUTRAL", "SentimentScore": {"Mixed": 0.0023450672160834074, "Negative": 0.0009663937962614, "Neutral": 0.9795311689376831, "Positive": 0.017157377675175667}}
{"File": "huge_doc", "ErrorCode": "DOCUMENT_SIZE_EXCEEDED", "ErrorMessage": "Document size is exceeds the limit of 5120 bytes."}
```