本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 API 的非同步分析任務 下列範例使用 Amazon Comprehend 非同步 APIs 來建立和管理使用 的分析任務 AWS CLI。 **Topics** + [Amazon Comprehend 洞察的非同步分析](api-async-insights.md) + [目標情緒的非同步分析](using-api-targeted-sentiment.md) + [事件偵測的非同步分析](get-started-api-events.md) + [主題建模的非同步分析](get-started-topics.md) # 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、\$1n)、歸位 (CR、\$1r) 或兩者 (CRLF、\$1r\$1n) 結尾。您無法使用 UTF-8 行分隔符號 (u\$12028) 來結束行。 | 每行一個文件 | 當您啟動分析任務時，您可以指定輸入資料的 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."} ``` # 目標情緒的非同步分析 如需目標情緒的即時分析資訊，請參閱 [目標情緒的即時分析](using-api-sync.md#get-started-api-targeted-sentiment)。 Amazon Comprehend 提供下列 API 操作，以啟動和管理非同步目標情緒分析： + [StartTargetedSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartTargetedSentimentDetectionJob.html) – 啟動文件集合的非同步目標情緒偵測任務。 + [ListTargetedSentimentDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListTargetedSentimentDetectionJobs.html) – 傳回您已提交的目標情緒偵測任務清單。 + [DescribeTargetedSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeTargetedSentimentDetectionJob.html) – 取得與指定目標情緒偵測任務相關聯的屬性 （包括狀態）。 + [StopTargetedSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StopTargetedSentimentDetectionJob.html) – 停止指定的進行中目標情緒任務。 **Topics** + [開始之前](#api-targeted-sentiment-before) + [使用 分析目標情緒 AWS CLI](#api-targeted-sentiment-cli) ## 開始之前 開始之前，請確定您已： + **輸入和輸出儲存貯**體 - 識別您要用於輸入和輸出的 Amazon S3 儲存貯體。儲存貯體必須與您呼叫的 API 位於相同的區域。 + **IAM 服務角色** - 您必須擁有具有存取輸入和輸出儲存貯體許可的 IAM 服務角色。如需詳細資訊，請參閱[非同步操作所需的角色型許可](security_iam_id-based-policy-examples.md#auth-role-permissions)。 ## 使用 分析目標情緒 AWS CLI 下列範例示範搭配 使用 `StartTargetedSentimentDetectionJob`操作 AWS CLI。此範例指定輸入文字的語言。 此範例格式適用於 Unix、Linux 和 macOS。用於 Windows 時，請以插入號 (^) 取代每一行結尾處的 Unix 接續字元斜線 (\$1)。 ``` aws comprehend start-targeted-sentiment-detection-job \ --job-name "job name" \ --language-code "en" \ --cli-input-json file://path to JSON input file ``` 對於 `cli-input-json` 參數，您提供包含請求資料的 JSON 檔案路徑，如下列範例所示。 ``` { "InputDataConfig": { "S3Uri": "s3://input bucket/input path", "InputFormat": "ONE_DOC_PER_FILE" }, "OutputDataConfig": { "S3Uri": "s3://output bucket/output path" }, "DataAccessRoleArn": "arn:aws:iam::account ID:role/data access role" } ``` 如果啟動任務的請求成功，您將會收到下列回應： ``` { "JobStatus": "SUBMITTED", "JobArn": "job ARN" "JobId": "job ID" } ``` # 事件偵測的非同步分析 **Topics** + [開始之前](#events-before) + [使用 偵測事件 AWS CLI](#events-cli) + [使用 列出事件 AWS CLI](#list-events) + [使用 描述事件 AWS CLI](#describe-events) + [取得事件偵測結果](#async-events) 若要偵測文件集中的事件，請使用 [StartEventsDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartEventsDetectionJob.html) 啟動非同步任務。 ## 開始之前 開始之前，請確定您已： + **輸入和輸出儲存貯**體 - 識別您要用於輸入和輸出的 Amazon S3 儲存貯體。儲存貯體必須與您呼叫的 API 位於相同的區域。 + **IAM 服務角色** - 您必須擁有具有存取輸入和輸出儲存貯體許可的 IAM 服務角色。如需詳細資訊，請參閱[非同步操作所需的角色型許可](security_iam_id-based-policy-examples.md#auth-role-permissions)。 ## 使用 偵測事件 AWS CLI 下列範例示範搭配 使用 [StartEventsDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartEventsDetectionJob.html) 操作 AWS CLI 此範例格式適用於 Unix、Linux 和 macOS。用於 Windows 時，請以插入號 (^) 取代每一行結尾處的 Unix 接續字元斜線 (\$1)。 ``` aws comprehend start-events-detection-job \ --region region \ --job-name job name \ --cli-input-json file://path to JSON input file ``` 對於 `cli-input-json` 參數，您提供包含請求資料的 JSON 檔案路徑，如下列範例所示。 ``` { "InputDataConfig": { "S3Uri": "s3://input bucket/input path", "InputFormat": "ONE_DOC_PER_LINE" }, "OutputDataConfig": { "S3Uri": "s3://output bucket/output path" }, "DataAccessRoleArn": "arn:aws:iam::account ID:role/data access role" "LanguageCode": "en", "TargetEventTypes": [ "BANKRUPTCY", "EMPLOYMENT", "CORPORATE_ACQUISITION", "INVESTMENT_GENERAL", "CORPORATE_MERGER", "IPO", "RIGHTS_ISSUE", "SECONDARY_OFFERING", "SHELF_OFFERING", "TENDER_OFFERING", "STOCK_SPLIT" ] } ``` 如果啟動事件偵測任務的請求成功，您將會收到下列回應： ``` { "JobStatus": "SUBMITTED", "JobId": "job ID" } ``` ## 使用 列出事件 AWS CLI 使用 [ListEventsDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListEventsDetectionJobs.html) 操作來查看您已提交的事件偵測任務清單。此清單包含您使用的輸入和輸出位置，以及每個偵測任務狀態的相關資訊。此範例格式適用於 Unix、Linux 和 macOS。用於 Windows 時，請以插入號 (^) 取代每一行結尾處的 Unix 接續字元斜線 (\$1)。 ``` aws comprehend list-events-detection-jobs --region region ``` 您會得到類似以下內容的 JSON 來回應： ``` { "EventsDetectionJobPropertiesList": [ { "DataAccessRoleArn": "arn:aws:iam::account ID:role/data access role", "EndTime": timestamp, "InputDataConfig": { "InputFormat": "ONE_DOC_PER_LINE", "S3Uri": "s3://input bucket/input path" }, "JobId": "job ID", "JobName": "job name", "JobStatus": "COMPLETED", "LanguageCode": "en", "Message": "message", "OutputDataConfig": { "S3Uri": "s3://output bucket/ouput path" }, "SubmitTime": timestamp, "TargetEventTypes": [ "BANKRUPTCY", "EMPLOYMENT", "CORPORATE_ACQUISITION", "INVESTMENT_GENERAL", "CORPORATE_MERGER", "IPO", "RIGHTS_ISSUE", "SECONDARY_OFFERING", "SHELF_OFFERING", "TENDER_OFFERING", "STOCK_SPLIT" ] } ], "NextToken": "next token" } ``` ## 使用 描述事件 AWS CLI 您可以使用 [DescribeEventsDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeEventsDetectionJob.html) 操作來取得現有任務的狀態。此範例格式適用於 Unix、Linux 和 macOS。用於 Windows 時，請以插入號 (^) 取代每一行結尾處的 Unix 接續字元斜線 (\$1)。 ``` aws comprehend describe-events-detection-job \ --region region \ --job-id job ID ``` 您將會收到下列 JSON 來回應： ``` { "EventsDetectionJobProperties": { "DataAccessRoleArn": "arn:aws:iam::account ID:role/data access role", "EndTime": timestamp, "InputDataConfig": { "InputFormat": "ONE_DOC_PER_LINE", "S3Uri": "S3Uri": "s3://input bucket/input path" }, "JobId": "job ID", "JobName": "job name", "JobStatus": "job status", "LanguageCode": "en", "Message": "message", "OutputDataConfig": { "S3Uri": "s3://output bucket/output path" }, "SubmitTime": timestamp, "TargetEventTypes": [ "BANKRUPTCY", "EMPLOYMENT", "CORPORATE_ACQUISITION", "INVESTMENT_GENERAL", "CORPORATE_MERGER", "IPO", "RIGHTS_ISSUE", "SECONDARY_OFFERING", "SHELF_OFFERING", "TENDER_OFFERING", "STOCK_SPLIT" ] } } ``` ## 取得事件偵測結果 以下是分析任務中偵測到文件中事件的輸出檔案範例。輸入的格式是每行一個文件。 ``` {"Entities": [{"Mentions": [{"BeginOffset": 12, "EndOffset": 27, "GroupScore": 1.0, "Score": 0.916355, "Text": "over a year ago", "Type": "DATE"}]}, {"Mentions": [{"BeginOffset": 33, "EndOffset": 39, "GroupScore": 1.0, "Score": 0.996603, "Text": "Amazon", "Type": "ORGANIZATION"}]}, {"Mentions": [{"BeginOffset": 66, "EndOffset": 77, "GroupScore": 1.0, "Score": 0.999283, "Text": "Whole Foods", "Type": "ORGANIZATION"}]}], "Events": [{"Arguments": [{"EntityIndex": 2, "Role": "INVESTEE", "Score": 0.999283}, {"EntityIndex": 0, "Role": "DATE", "Score": 0.916355}, {"EntityIndex": 1, "Role": "INVESTOR", "Score": 0.996603}], "Triggers": [{"BeginOffset": 373, "EndOffset": 380, "GroupScore": 0.999984, "Score": 0.999955, "Text": "acquire", "Type": "CORPORATE_ACQUISITION"}], "Type": "CORPORATE_ACQUISITION"}, {"Arguments": [{"EntityIndex": 2, "Role": "PARTICIPANT", "Score": 0.999283}], "Triggers": [{"BeginOffset": 115, "EndOffset": 123, "GroupScore": 1.0, "Score": 0.999967, "Text": "combined", "Type": "CORPORATE_MERGER"}], "Type": "CORPORATE_MERGER"}], "File": "doc.txt", "Line": 0} ``` 如需事件輸出檔案結構和支援的事件類型的詳細資訊，請參閱 [事件](how-events.md)。 # 主題建模的非同步分析 若要判斷文件集中的主題，請使用 [StartTopicsDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartTopicsDetectionJob.html) 啟動非同步任務。您可以監控以英文或西班牙文撰寫之文件中的主題。 **Topics** + [開始之前](#topics-before) + [使用 AWS Command Line Interface](#topics-cli) + [使用適用於 Python 的 SDK 或 適用於 .NET 的 SDK](#topic-java) ## 開始之前 開始之前，請確定您已： + **輸入和輸出儲存貯**體 - 識別您要用於輸入和輸出的 Amazon S3 儲存貯體。儲存貯體必須與您呼叫的 API 位於相同的區域。 + **IAM 服務角色** - 您必須擁有具有存取輸入和輸出儲存貯體許可的 IAM 服務角色。如需詳細資訊，請參閱[非同步操作所需的角色型許可](security_iam_id-based-policy-examples.md#auth-role-permissions)。 ## 使用 AWS Command Line Interface 下列範例示範搭配 使用 `StartTopicsDetectionJob`操作 AWS CLI 此範例格式適用於 Unix、Linux 和 macOS。用於 Windows 時，請以插入號 (^) 取代每一行結尾處的 Unix 接續字元斜線 (\$1)。 ``` aws comprehend start-topics-detection-job \ --number-of-topics topics to return \ --job-name "job name" \ --region region \ --cli-input-json file://path to JSON input file ``` 對於 `cli-input-json` 參數，您提供包含請求資料的 JSON 檔案路徑，如下列範例所示。 ``` { "InputDataConfig": { "S3Uri": "s3://input bucket/input path", "InputFormat": "ONE_DOC_PER_FILE" }, "OutputDataConfig": { "S3Uri": "s3://output bucket/output path" }, "DataAccessRoleArn": "arn:aws:iam::account ID:role/data access role" } ``` 如果啟動主題偵測任務的請求成功，您將會收到下列回應： ``` { "JobStatus": "SUBMITTED", "JobId": "job ID" } ``` 使用 [ListTopicsDetectionJobs](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ListTopicsDetectionJobs.html) 操作來查看您已提交的主題偵測任務清單。此清單包含您使用的輸入和輸出位置，以及每個偵測任務狀態的相關資訊。此範例格式適用於 Unix、Linux 和 macOS。用於 Windows 時，請以插入號 (^) 取代每一行結尾處的 Unix 接續字元斜線 (\$1)。 ``` aws comprehend list-topics-detection-jobs \-- region ``` 您會得到類似以下內容的 JSON 來回應： ``` { "TopicsDetectionJobPropertiesList": [ { "InputDataConfig": { "S3Uri": "s3://input bucket/input path", "InputFormat": "ONE_DOC_PER_LINE" }, "NumberOfTopics": topics to return, "JobId": "job ID", "JobStatus": "COMPLETED", "JobName": "job name", "SubmitTime": timestamp, "OutputDataConfig": { "S3Uri": "s3://output bucket/output path" }, "EndTime": timestamp }, { "InputDataConfig": { "S3Uri": "s3://input bucket/input path", "InputFormat": "ONE_DOC_PER_LINE" }, "NumberOfTopics": topics to return, "JobId": "job ID", "JobStatus": "RUNNING", "JobName": "job name", "SubmitTime": timestamp, "OutputDataConfig": { "S3Uri": "s3://output bucket/output path" } } ] } ``` 您可以使用 [DescribeTopicsDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DescribeTopicsDetectionJob.html) 操作來取得現有任務的狀態。此範例格式適用於 Unix、Linux 和 macOS。用於 Windows 時，請以插入號 (^) 取代每一行結尾處的 Unix 接續字元斜線 (\$1)。 ``` aws comprehend describe-topics-detection-job --job-id job ID ``` 您將會收到下列 JSON 來回應： ``` { "TopicsDetectionJobProperties": { "InputDataConfig": { "S3Uri": "s3://input bucket/input path", "InputFormat": "ONE_DOC_PER_LINE" }, "NumberOfTopics": topics to return, "JobId": "job ID", "JobStatus": "COMPLETED", "JobName": "job name", "SubmitTime": timestamp, "OutputDataConfig": { "S3Uri": "s3://output bucket/ouput path" }, "EndTime": timestamp } } ``` ## 使用適用於 Python 的 SDK 或 適用於 .NET 的 SDK 如需如何啟動主題建模任務的 SDK 範例，請參閱 [`StartTopicsDetectionJob` 搭配 AWS SDK 或 CLI 使用](example_comprehend_StartTopicsDetectionJob_section.md)。