Principes de base de l'API Natural Language

Ce document est un guide présentant les principes de base de l'utilisation de l'API Cloud Natural Language. Dans ce guide conceptuel, vous découvrirez les types de requêtes que vous pouvez envoyer à l'API Natural Language. Vous apprendrez également à construire de telles requêtes et à gérer leurs réponses. Nous recommandons à tous les utilisateurs de l'API Natural Language de lire à la fois ce guide et l'un des tutoriels associés avant de se plonger dans l'API elle-même.

Fonctionnalités de l'API Natural Language

L'API Natural Language a recours à plusieurs méthodes d'analyse et d'annotation des textes. Chaque niveau d'analyse livre des informations précieuses permettant de comprendre le langage. Ces méthodes sont décrites ci-dessous :

• L'analyse des sentiments examine le texte donné et identifie l'opinion émotionnelle dominante qui s'en dégage, en particulier pour déterminer si l'attitude de l'auteur est positive, négative ou neutre. L'analyse des sentiments est effectuée avec la méthode analyzeSentiment.

• L'analyse des entités inspecte le texte donné pour y rechercher des entités connues (des noms propres, c'est-à-dire des personnages publics ou des points de repère, par exemple, et des noms communs tels que restaurant, stade, etc.), puis renvoie des informations sur ces entités. L'analyse d'entités est effectuée avec la méthode analyzeEntities.

• L'analyse des sentiments d'entités examine le texte donné pour y rechercher des entités connues (noms propres et noms communs), renvoie des informations sur ces entités, et identifie l'opinion émotionnelle dominante dans le texte, en particulier pour déterminer si l'attitude de l'auteur est positive, négative ou neutre. L'analyse d'entités est effectuée avec la méthode analyzeEntitySentiment.

• L'analyse syntaxique extrait les informations linguistiques en divisant le texte donné en une série de phrases et de jetons (qui correspondent généralement aux mots) et en procédant à une analyse approfondie de ces jetons. L'analyse syntaxique est effectuée avec la méthode analyzeSyntax.

• La classification de contenus analyse le contenu d'un texte et renvoie une catégorie de contenu lui correspondant. La classification de contenus est effectuée avec la méthode classifyText.

Chaque appel d'API détecte et renvoie également la langue, si celle-ci n'a pas été spécifiée par l'appelant dans la requête initiale.

De plus, si vous souhaitez effectuer plusieurs opérations liées au langage naturel sur un texte donné à l'aide d'un seul appel d'API, la requête annotateText peut également servir à effectuer une analyse des sentiments et une analyse des entités.

Requêtes Natural Language de base

L'API Natural Language est une API REST, et elle comprend des requêtes et réponses JSON. Une requête JSON simple d'analyse des entités Natural Language est donnée en exemple ci-dessous :

{
  "document":{
    "type":"PLAIN_TEXT",
    "language_code": "EN",
    "content":"'Lawrence of Arabia' is a highly rated film biography about
                British Lieutenant T. E. Lawrence. Peter O'Toole plays
                Lawrence in the film."
  },
  "encodingType":"UTF8"
}

Expliquons chacun de ces champs :

• document contient les données de cette requête et comprend les sous-champs suivants :
  • type : type de document (HTML ou PLAIN_TEXT).
  • language : (facultatif) la langue du texte inclus dans la requête. Si ce champ n'est pas renseigné, la langue sera automatiquement détectée. Pour plus d'informations sur les langues acceptées par l'API Natural Language, consultez la page Langues acceptées. Les langues non acceptées renverront une erreur dans la réponse JSON.
    
  • content ou gcsContentUri : le texte à évaluer. Si vous transmettez content, ce texte est inclus directement dans la requête JSON (comme indiqué plus haut). Si vous transmettez gcsContentUri, ce champ doit inclure un URI pointant vers des contenus textuels situés dans Google Cloud Storage.
• encodingType : (obligatoire) le schéma de codage dans lequel les décalages de caractères renvoyés dans le texte doivent être calculés, qui doit correspondre au codage du texte transmis. Si ce paramètre n'est pas défini, la requête ne générera pas d'erreur, mais tous les décalages de ce type seront définis sur -1.

Spécifier les contenus textuels

Lorsque vous transmettez une requête d'API Natural Language, vous spécifiez le texte à traiter de l'une des deux manières suivantes :

• En transmettant le texte directement dans un champ content.
• En transmettant un URI Google Cloud Storage dans un champ gcsContentUri.

Dans les deux cas, vous devez vous assurer de ne pas dépasser les limites de contenus. Notez que ces limites de contenus s'appliquent par octet et non par caractère ; la longueur des caractères dépend donc de l'encodage de votre texte.

La requête ci-dessous fait référence à un fichier Google Cloud Storage contenant le discours de Gettysburg :

{
  "document":{
    "type":"PLAIN_TEXT",
    "language": "EN",
    "gcsContentUri":"gs://cloud-samples-tests/natural-language/gettysburg.txt"
  },
}

Analyse des sentiments

L'analyse des sentiments tente de déterminer l'attitude globale (positive ou négative) exprimée dans le texte. Le sentiment est représenté par des valeurs numériques : score et magnitude.

Champs d'une réponse d'analyse des sentiments

Un exemple de réponse analyzeSentiment au discours de Gettysburg est présenté ci-dessous :

{
  "documentSentiment": {
    "score": 0.2,
    "magnitude": 3.6
  },
  "language_code": "en",