As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Análise assíncrona para insights do Amazon Comprehend
As seções a seguir usam a API do Amazon Comprehend para executar operações assíncronas que analisam os insights do Amazon Comprehend.
**Topics**
+ [Pré-requisitos](#detect-topics-role-auth)
+ [Iniciar uma tarefa de análise](#how-start-job)
+ [Monitorar tarefas de análise](#how-monitor-progress)
+ [Obter os resultados da análise](#how-get-results)
## Pré-requisitos
Os documentos devem arquivos de texto no formato UTF-8. Você pode enviar seus documentos em dois formatos. O formato usado depende do tipo de documento que deseja analisar, conforme descrito na tabela a seguir.
| Description | Formato |
| --- | --- |
| Cada arquivo contém um documento de entrada. Essa opção é melhor para coleções de documentos grandes. | Um documento por arquivo |
| A entrada é um ou mais arquivos. Cada linha em um arquivo é considerada um documento. Essa opção é melhor para documentos curtos, como publicações em mídias sociais. Cada linha deve terminar com uma alimentação de linha (LF, \$1n), um retorno de carro (CR, \$1r) ou ambos (CRLF, \$1r\$1n). Você não pode usar o separador de linha UTF-8 (u\$12028) para finalizar uma linha. | Um documento por linha |
Ao iniciar uma tarefa de análise, especifique a localização do S3 para seus dados de entrada. O URI deve estar na mesma AWS região do endpoint da API que você está chamando. O URI pode apontar para um único arquivo ou pode ser o prefixo de uma coleção de arquivos de dados. Para obter mais informações, consulte o tipo de dados [InputDataConfig](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html).
É preciso conceder ao Amazon Comprehend acesso ao bucket do Amazon S3 contendo sua coleção de documentos e arquivos de saída. Para obter mais informações, consulte [Permissões baseadas em perfis necessárias para operações assíncronas](security_iam_id-based-policy-examples.md#auth-role-permissions).
## Iniciar uma tarefa de análise
Para enviar uma tarefa de análise, use o console do Amazon Comprehend ou a operação de `Start*` apropriada:
+ [StartDominantLanguageDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDominantLanguageDetectionJob.html)— Comece um trabalho para detectar o idioma dominante em cada documento da coleção. Para mais informações sobre o idioma dominante em um documento, consulte [Idioma dominante](how-languages.md).
+ [StartEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartEntitiesDetectionJob.html)— Inicie um trabalho para detectar entidades em cada documento da coleção. Para obter mais informações sobre entidades, consulte [Entidades](how-entities.md).
+ [StartKeyPhrasesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartKeyPhrasesDetectionJob.html)— Inicie um trabalho para detectar frases-chave em cada documento da coleção. Para mais informações sobre nomes de chave, consulte [Frases chave](how-key-phrases.md).
+ [StartPiiEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartPiiEntitiesDetectionJob.html)— Inicie um trabalho para detectar informações de identificação pessoal (PII) em cada documento da coleção. Para mais informações sobre PII, consulte [Detectar entidades de PII](how-key-phrases.md).
+ [StartSentimentDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartSentimentDetectionJob.html)— Inicie um trabalho para detectar o sentimento em cada documento da coleção. Para mais informações sobre sentimentos, consulte [Sentimento](how-sentiment.md).
## Monitorar tarefas de análise
A operação de `Start*` retorna um ID que pode ser usado para monitorar o progresso da tarefa.
Para monitorar o progresso usando a API, use uma das duas operações, dependendo se deseja monitorar o progresso de uma tarefa individual ou de várias tarefas.
Para monitorar o progresso de uma tarefa de análise individual, use as operações de `Describe*`. Você fornece o ID da tarefa retornada pela operação de `Start*`. A resposta da operação de `Describe*` contém o campo de `JobStatus` com o status da tarefa.
Para monitorar o progresso de várias tarefas de análise, use a as operações de `List*`. Operações de `List*` retornam uma lista de tarefas que você enviou para o Amazon Comprehend. A resposta inclui um campo de `JobStatus` para cada tarefa que informa o seu status.
Se o campo de status estiver definido como `COMPLETED` ou `FAILED`, o processamento da tarefa foi concluído.
Para obter o status de tarefas individuais, use a operação `Describe*` para a análise que está executando.
+ [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)
Para obter o status de tarefas múltiplas, use a operação `List*` para a análise que está executando.
+ [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)
Para restringir resultados a tarefas que correspondam a determinados critérios, use o parâmetro `Filter` das operações de `List*`. É possível filtrar os resultados por nome, status da tarefa ou data e hora em que ela foi enviada. Para obter mais informações, consulte o parâmetro `Filter` para cada uma das operações de `List*` na referência de API do Amazon Comprehend.
## Obter os resultados da análise
Depois que uma tarefa de análise for concluída, use uma operação `Describe*` para obter a localização dos resultados. Se o status da tarefa for `COMPLETED`, a resposta incluirá um campo `OutputDataConfig` contendo um outro campo com a localização do arquivo de saída no Amazon S3. O arquivo de saída, `output.tar.gz`, é um arquivo compactado contendo os resultados da análise.
Se o status de uma tarefa for `FAILED`, a resposta conterá um campo de `Message` descrevendo o motivo pelo qual a tarefa de análise não foi concluída com êxito.
Para obter o status de tarefas individuais, use a operação `Describe*` apropriada:
+ [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)
Os resultados são retornados em um único arquivo, com uma estrutura JSON para cada documento. Cada arquivo de resposta também inclui mensagens de erro para qualquer tarefa com o campo de status definido como `FAILED`.
Cada uma das seções a seguir mostra exemplos de saída para os dois formatos de entrada.
### Obter resultados de detecção de linguagem dominante
Veja a seguir um exemplo de um arquivo de saída de uma análise que detectou o idioma dominante. O formato da entrada é um documento por linha. Para obter mais informações, consulte a operação [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}
```
Veja a seguir um exemplo de saída de uma análise em que o formato da entrada é um documento por arquivo:
```
{"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}]}
```
### Obter resultados de detecção de entidades
Veja a seguir um exemplo de um arquivo de saída de uma análise que detectou entidades em documentos. O formato da entrada é um documento por linha. Para obter mais informações, consulte a operação [DetectEntities](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectEntities.html). A saída contém duas mensagens de erro, uma para um documento muito longo e outra para um documento que não está no formato 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."}
```
Veja a seguir um exemplo de saída de uma análise em que o formato da entrada é um documento por arquivo. A saída contém duas mensagens de erro, uma para um documento muito longo e outra para um documento que não está no formato 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."}
```
### Obter resultados de detecção de frases-chave
Veja a seguir um exemplo de um arquivo de saída de uma análise que detectou frases-chave em um documento. O formato da entrada é um documento por linha. Para obter mais informações, consulte a operação [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}
```
Veja a seguir um exemplo da saída de uma análise em que o formato da entrada é um documento por arquivo.
```
{"File": "1_doc", "KeyPhrases": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.8948641419410706, "Text": "Cluj-NapocaCluj-Napoca"}, {"BeginOffset": 45, "EndOffset": 49, "Score": 0.9989854693412781, "Text": "Cluj"}]}
```
### Obter resultados de detecção de informações de identificação pessoal (PII)
Veja a seguir um exemplo de arquivo de saída de uma tarefa de análise que detectou entidades de PII em documentos. O formato da entrada é um documento por linha.
```
{"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}
```
Veja a seguir um exemplo de saída de uma análise em que o formato da entrada é um documento por arquivo.
```
{"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"}
```
### Obter resultados de detecção de sentimento
Veja a seguir um exemplo de um arquivo de saída de uma análise que detectou o sentimento expresso em um documento. Inclui uma mensagem de erro porque um documento é muito longo. O formato da entrada é um documento por linha. Para obter mais informações, consulte a operação [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}}
```
Veja a seguir um exemplo da saída de uma análise em que o formato da entrada é um documento por arquivo.
```
{"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."}
```