Analyse asynchrone pour Amazon Comprehend Insights

Les sections suivantes utilisent l'API Amazon Comprehend pour exécuter des opérations asynchrones afin d'analyser les informations d'Amazon Comprehend.

Prérequis

Les documents doivent être dans des fichiers texte au format UTF-8. Vous pouvez soumettre vos documents dans deux formats. Le format que vous utilisez dépend du type de document que vous souhaitez analyser, comme décrit dans le tableau suivant.

Description	Format
Chaque fichier contient un document d'entrée. C'est la meilleure solution pour les collections de documents volumineux.	Un document par fichier
L'entrée est un ou plusieurs fichiers. Chaque ligne d'un fichier est considérée comme un document. C'est la meilleure solution pour les documents courts, tels que les publications sur les réseaux sociaux. Chaque ligne doit se terminer par une ligne d'alimentation (LF,\n), un retour en chariot (CR, \ r), ou les deux (CRLF, \ r\n). Vous ne pouvez pas utiliser le séparateur de ligne UTF-8 (u+2028) pour terminer une ligne.	Un document par ligne

Lorsque vous démarrez une tâche d'analyse, vous spécifiez l'emplacement S3 de vos données d'entrée. L'URI doit se trouver dans la même AWS région que le point de terminaison de l'API que vous appelez. L'URI peut pointer vers un seul fichier ou être le préfixe d'un ensemble de fichiers de données. Pour plus d'informations, consultez le type de données InputDataConfig.

Vous devez accorder à Amazon Comprehend l'accès au compartiment Amazon S3 qui contient votre collection de documents et vos fichiers de sortie. Pour plus d’informations, consultez Autorisations basées sur les rôles requises pour les opérations asynchrones.

Démarrage d'une tâche d'analyse

Pour soumettre une tâche d'analyse, utilisez la console Amazon Comprehend ou l'opération appropriée Start* :

• StartDominantLanguageDetectionJob— Lancez une tâche pour détecter la langue dominante dans chaque document de la collection. Pour plus d'informations sur la langue dominante d'un document, consultezLangue dominante.

• StartEntitiesDetectionJob— Lancez une tâche pour détecter les entités dans chaque document de la collection. Pour plus d'informations sur les entités, consultez Entités.

• StartKeyPhrasesDetectionJob— Lancez une tâche pour détecter les phrases clés dans chaque document de la collection. Pour plus d'informations sur les phrases clés, voirPhrases clés.

• StartPiiEntitiesDetectionJob— Commencez une tâche pour détecter les informations personnelles identifiables (PII) dans chaque document de la collection. Pour plus d'informations sur les informations personnelles, consultezDétecter PII des entités.

• StartSentimentDetectionJob— Lancez une tâche pour détecter le sentiment qui se dégage de chaque document de la collection. Pour plus d'informations sur les sentiments, voirSentiment.

Tâches d'analyse de surveillance

L'Start*opération renvoie un identifiant que vous pouvez utiliser pour suivre la progression de la tâche.

Pour suivre la progression à l'aide de l'API, vous pouvez effectuer l'une des deux opérations suivantes, selon que vous souhaitez suivre la progression d'une tâche individuelle ou de plusieurs tâches.

Pour suivre la progression d'une tâche d'analyse individuelle, utilisez les Describe* opérations. Vous fournissez l'ID de tâche renvoyé par l'Start*opération. La réponse de l'Describe*opération contient le JobStatus champ indiquant le statut de la tâche.

Pour suivre la progression de plusieurs tâches d'analyse, utilisez les List* opérations. List*les opérations renvoient une liste des tâches que vous avez soumises à Amazon Comprehend. La réponse inclut un JobStatus champ pour chaque tâche qui indique le statut de la tâche.

Si le champ d'état est défini sur COMPLETED ouFAILED, le traitement de la tâche est terminé.

Pour obtenir le statut de tâches individuelles, utilisez l'Describe*opération correspondant à l'analyse que vous effectuez.

• DescribeDominantLanguageDetectionJob

• DescribeEntitiesDetectionJob

• DescribeKeyPhrasesDetectionJob

• DescribePiiEntitiesDetectionJob

• DescribeSentimentDetectionJob

Pour obtenir le statut de plusieurs tâches, utilisez l'List*opération correspondant à l'analyse que vous effectuez.

• ListDominantLanguageDetectionJobs

• ListEntitiesDetectionJobs

• ListKeyPhrasesDetectionJobs

• ListPiiEntitiesDetectionJobs

• ListSentimentDetectionJobs

Pour limiter les résultats aux tâches qui répondent à certains critères, utilisez le Filter paramètre List* des opérations. Vous pouvez filtrer en fonction du nom de la tâche, de son statut, ainsi que de la date et de l'heure de soumission de la tâche. Pour plus d'informations, consultez le Filter paramètre de chacune des List* opérations dans la référence de l'API Amazon Comprehend.

Obtenir des résultats d'analyse

Une fois le travail d'analyse terminé, utilisez une Describe* opération pour obtenir l'emplacement des résultats. Si le statut de la tâche est le suivantCOMPLETED, la réponse inclut un OutputDataConfig champ contenant l'emplacement du fichier de sortie sur Amazon S3. Le fichier est une archive compressée qui contient les résultats de l'analyse. output.tar.gz

Si le statut d'une tâche estFAILED, la réponse contient un Message champ qui décrit la raison pour laquelle la tâche d'analyse ne s'est pas terminée correctement.

Pour obtenir le statut de chaque tâche, utilisez l'Describe*opération appropriée :

• DescribeDominantLanguageDetectionJob

• DescribeEntitiesDetectionJob

• DescribeKeyPhrasesDetectionJob

• DescribeSentimentDetectionJob

Les résultats sont renvoyés dans un seul fichier, avec une structure JSON pour chaque document. Chaque fichier de réponse inclut également des messages d'erreur pour toute tâche dont le champ d'état est défini surFAILED.

Chacune des sections suivantes présente des exemples de sortie pour les deux formats d'entrée.

Obtenir des résultats de détection de la langue dominante

Voici un exemple de fichier de sortie issu d'une analyse qui a détecté la langue dominante. Le format de l'entrée est d'un document par ligne. Pour plus d'informations, consultez l'DetectDominantLanguageopération.

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

Voici un exemple de sortie d'une analyse où le format de l'entrée est d'un document par fichier :

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

Obtenir les résultats de détection des entités

Voici un exemple de fichier de sortie issu d'une analyse qui a détecté des entités dans des documents. Le format de l'entrée est d'un document par ligne. Pour plus d'informations, consultez l'DetectEntitiesopération. La sortie contient deux messages d'erreur, l'un pour un document trop long et l'autre pour un document qui n'est pas au format 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."} 

Voici un exemple de sortie d'une analyse où le format de l'entrée est d'un document par fichier. La sortie contient deux messages d'erreur, l'un pour un document trop long et l'autre pour un document qui n'est pas au format 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."}

Obtenir les résultats de détection des phrases clés

Voici un exemple de fichier de sortie issu d'une analyse qui a détecté des phrases clés dans un document. Le format de l'entrée est d'un document par ligne. Pour plus d'informations, consultez l'DetectKeyPhrasesopération.

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

Voici un exemple de sortie d'une analyse où le format de l'entrée est d'un document par fichier.

{"File": "1_doc", "KeyPhrases": [{"BeginOffset": 0, "EndOffset": 22, "Score": 0.8948641419410706, "Text": "Cluj-NapocaCluj-Napoca"}, {"BeginOffset": 45, "EndOffset": 49, "Score": 0.9989854693412781, "Text": "Cluj"}]}            

Obtenir les résultats de détection des informations personnelles identifiables (PII)

Voici un exemple de fichier de sortie issu d'une tâche d'analyse qui a détecté des entités PII dans des documents. Le format de l'entrée est d'un document par ligne.

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

Voici un exemple de sortie d'une analyse où le format de l'entrée est d'un document par fichier.

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

Obtenir des résultats de détection des sentiments

Voici un exemple de fichier de sortie issu d'une analyse qui a détecté le sentiment exprimé dans un document. Il inclut un message d'erreur car un document est trop long. Le format de l'entrée est d'un document par ligne. Pour plus d'informations, consultez l'DetectSentimentopération.

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

Voici un exemple de sortie d'une analyse où le format de l'entrée est d'un document par fichier.

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