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.

Faites l'essai

Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de Natural Language en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

<ph type="x-smartling-placeholder"></ph> Essayez Natural Language gratuitement

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",
   "sentences": [
    {
      "text": {
        "content": "Four score and seven years ago our fathers brought forth
        on this continent a new nation, conceived in liberty and dedicated to
        the proposition that all men are created equal.",
        "beginOffset": 0
      },
      "sentiment": {
        "magnitude": 0.8,
        "score": 0.8
      }
    },
   ...
}

Les valeurs de ces champs sont décrites ci-dessous :

  • documentSentiment contient le sentiment général du document et comprend les sous-champs suivants :
    • Le score du sentiment est compris entre -1.0 (négatif) et 1.0 (positif). Il correspond à la tendance émotionnelle générale du texte.
    • La magnitude indique l'intensité générale de l'émotion (positive ou négative) exprimée dans le texte en question. Elle est comprise entre 0.0 et +inf. Contrairement à score, magnitude n'est pas normalisé pour documentSentiment ; chaque expression d'une émotion dans le texte (positive ou négative) contribue à la magnitude du texte (donc les blocs de texte plus longs peuvent avoir des grandeurs supérieures).
  • Le champ language_code contient la langue du document, laquelle est soit transmise dans la requête initiale, soit détectée automatiquement en cas de champ non renseigné.
  • language_supported contient une valeur booléenne permettant de déterminer si la langue est officiellement compatible.
  • Le champ sentences contient une liste des phrases extraites du document original. Il inclut l'élément suivant :
    • sentiment contient les valeurs de sentiment au niveau de la phrase associées à chaque phrase, qui contient score entre -1.0 (négatif) et 1.0 (positive) comme des valeurs magnitude comprises entre 0.0 et 1.0. Notez que magnitude pour sentences est normalisé.

Une valeur de sentiment 0.2 pour le discours de Gettysburg indique une légère positivité au niveau de l'émotion, tandis que la valeur de magnitude 3.6 indique un document relativement émotionnel étant donné sa petite taille (environ un paragraphe). Notez que la première phrase du discours de Gettysburg présente un score positif très élevé de 0.8.

Interpréter les valeurs d'analyse des sentiments

Le score du sentiment d'un document indique l'émotion globale de ce document. La magnitude du sentiment d'un document indique la quantité de contenu émotionnel présente dans le document. Cette valeur est souvent proportionnelle à la longueur du document.

Il est important de noter que l'API Natural Language indique les différences entre les émotions positives et négatives dans un document, mais qu'elle n'identifie pas d'émotions positives et négatives spécifiques. Par exemple, "en colère" et "triste" sont toutes deux considérées comme des émotions négatives. Toutefois, lorsque l'API Natural Language analyse un texte considéré comme étant "en colère" ou un texte considéré comme étant "triste", la réponse indique seulement que le sentiment dans le texte est négatif, et non pas qu'il s'agit de tristesse ou de colère.

Un score neutre (environ 0.0) peut indiquer qu'il s'agit d'un document à faible émotion, ou peut indiquer des émotions mélangées, avec des valeurs positives et négatives élevées qui s'annulent entre elles. De manière générale, vous pouvez utiliser les valeurs de magnitude pour lever les ambiguïtés. En effet, les documents qui sont réellement neutres ont une valeur de magnitude faible, tandis que les documents mixtes ont des valeurs de magnitude plus élevées.

Lorsque vous comparez des documents entre eux (particulièrement des documents de longueurs différentes), assurez-vous de calibrer vos scores avec les valeurs de magnitude, car elles vous aideront à évaluer la quantité pertinente de contenu émotionnel.

Le graphique ci-dessous illustre quelques exemples de valeurs et la manière dont elles doivent être interprétées :

Sentiment Exemples de valeurs
Clairement positif* "score" : 0.8, "magnitude" : 3.0
Clairement négatif* "score" : -0.6, "magnitude" : 4.0
Neutre "score" : 0.1, "magnitude" : 0.0
Mixte "score" : 0.0, "magnitude" : 4.0

* Les sentiments "clairement positif" et "clairement négatif" varient selon les cas d'utilisation et les clients. Vous pourriez parvenir à des résultats différents dans le contexte spécifique que vous utiliserez. Nous vous recommandons de définir un seuil qui convient à vos besoins, puis de l'ajuster après avoir testé et vérifié les résultats. Par exemple, vous pouvez définir tout résultat supérieur à 0.25 comme étant clairement positif, puis modifier le seuil de score à 0.15 après avoir examiné vos données et vos résultats, et en avoir conclu que les résultats compris entre 0.15 et 0.25 doivent également être considérés comme des sentiments positifs.

Analyse des entités

L'analyse des entités fournit des informations sur les entités présentes dans le texte, lesquelles font généralement référence à des "choses" nommées, telles que des personnages célèbres, des points de repère, des objets courants, etc.

Les entités appartiennent généralement à l'une de ces deux catégories : aux noms propres, qui correspondent à des entités uniques (personnes spécifiques, lieux spécifiques, etc.) ou aux noms communs (également appelés "nominaux" dans le traitement du langage naturel). Partez généralement du principe que si quelque chose est un nom, il est considéré comme une "entité". Les entités sont renvoyées sous forme de décalages indexés dans le texte d'origine.

Une requête d'analyse des entités doit transmettre un argument encodingType, afin que les décalages renvoyés puissent être interprétés correctement.

Champs d'une réponse d'analyse des entités

L'analyse des entités renvoie un ensemble d'entités détectées ainsi que les paramètres qui leur sont associés, tels que le type d'entité, la pertinence de l'entité par rapport au texte global et les emplacements dans le texte qui font référence à la même entité.

Une réponse analyzeEntities à la requête d'entité est présentée ci-dessous :

{
  "entities": [
    {
      "name": "British",
      "type": "LOCATION",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "British",
            "beginOffset": 58
          },
          "type": "PROPER",
          "probability": 0.941
        }
      ]
    },
    {
      "name": "Lawrence",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Lawrence",
            "beginOffset": 113
          },
          "type": "PROPER",
          "probability": 0.914
        }
      ]
    },
    {
      "name": "Lawrence of Arabia",
      "type": "WORK_OF_ART",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Lawrence of Arabia",
            "beginOffset": 0
          },
          "type": "PROPER",
          "probability": 0.761
        }
      ]
    },
    {
      "name": "Lieutenant",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Lieutenant",
            "beginOffset": 66
          },
          "type": "COMMON",
          "probability": 0.927
        }
      ]
    },
    {
      "name": "Peter O Toole",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Peter O Toole",
            "beginOffset": 93
          },
          "type": "PROPER",
          "probability": 0.907
        }
      ]
    },
    {
      "name": "T. E. Lawrence",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "T. E. Lawrence",
            "beginOffset": 77
          },
          "type": "PROPER",
          "probability": 0.853
        }
      ]
    },
    {
      "name": "film",
      "type": "WORK_OF_ART",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "film",
            "beginOffset": 129
          },
          "type": "COMMON",
          "probability": 0.805
        }
      ]
    },
    {
      "name": "film biography",
      "type": "WORK_OF_ART",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "film biography",
            "beginOffset": 37
          },
          "type": "COMMON",
          "probability": 0.876
        }
      ]
    }
  ],
  "languageCode": "en",
  "languageSupported": true
}

Notez que l'API Natural Language renvoie des entités pour "Lawrence d'Arabie" (le film) et "T.E. Lawrence" (l'homme). L'analyse des entités est utile pour lever l'ambiguïté sur les entités similaires, telles que "Lawrence" dans ce cas particulier.

Les champs utilisés pour stocker les paramètres de l'entité sont énumérés ci-dessous :

  • type indique le type de l'entité (par exemple, si l'entité est une personne, un lieu, un bien de consommation, etc.). Ces informations aident à distinguer et/ou à lever les ambiguïtés sur certaines entités, et peuvent être utilisées pour créer des modèles ou extraire des informations. Par exemple, une valeur type peut aider à distinguer des entités portant un nom similaire, telles que "Lawrence d'Arabie", étiquetée en tant que WORK_OF_ART (film) et "T.E. Lawrence", étiquetée en tant que PERSON. (Voir les types d'entités pour plus d'informations.)

  • metadata contient des informations sources sur le référentiel de connaissances de l'entité. D'autres référentiels pourront éventuellement être exposés à l'avenir.

  • mentions indique les positions de décalage dans le texte où une entité est mentionnée. Cette information peut être utile si vous voulez trouver toutes les mentions de la personne "Lawrence" dans le texte, mais pas les mentions évoquant le titre du film. Vous pouvez également utiliser les mentions pour recueillir une liste des alias d'entités, tels que "Lawrence", qui font référence à la même entité "T.E Lawrence". Une mention d'entité peut être de deux types : PROPER ou COMMON. Une entité sous forme de nom propre pour "Lawrence d'Arabie", par exemple, pourrait être directement mentionnée en tant que titre du film, ou en tant que nom commun ("film biographique" sur T.E. Lawrence).

Analyse des sentiments d'entités

L'analyse des sentiments d'entités combine l'analyse des entités et l'analyse des sentiments pour tenter de déterminer le sentiment (positif ou négatif) exprimé à propos des entités dans le texte. Le sentiment de l'entité est représenté par des valeurs numériques de score et de magnitude, et il est déterminé pour chaque mention d'une entité. Ces scores sont ensuite agrégés pour former un score et une magnitude de sentiment globaux pour une entité.

Requêtes d'analyse des sentiments d'entités

Les requêtes d'analyse des sentiments d'entités sont envoyées à l'API Natural Language via la méthode analyzeEntitySentiment sous la forme suivante :

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"I love R&B music. Marvin Gaye is the best.
               'What's Going On' is one of my favorite songs.
               It was so sad when Marvin Gaye died."
  },
  "encodingType":"UTF8"
}

Dans votre requête, vous pouvez spécifier un paramètre language facultatif qui identifie le code de langue du texte dans le paramètre content. Si vous ne spécifiez pas de paramètre language, l'API Natural Language détecte automatiquement la langue du contenu de la requête. Pour plus d'informations sur les langues acceptées par l'API Natural Language, consultez la page Langues acceptées.

Réponses d'analyse des sentiments d'entités

L'API Natural Language traite le texte donné pour en extraire les entités et en déterminer le sentiment. Une requête d'analyse des sentiments d'entités renvoie une réponse contenant les entités (entities) trouvées dans le contenu du document, une entrée mentions pour chaque mention de l'entité, et les valeurs numériques de score et de magnitude pour chaque mention, comme décrit à la section Interpréter les valeurs d'analyse des sentiments. Les valeurs globales de score et de magnitude d'une entité sont un agrégat des valeurs de score et de magnitude spécifiques à chaque mention de l'entité. Les valeurs de score et de magnitude d'une entité peuvent être égales à 0. Si le texte contient peu de sentiment, cela donne une magnitude de 0. Si le sentiment est mixte, cela donne un score de 0.

{
  "entities": [
    {
      "name": "R&B music",
      "type": "WORK_OF_ART",
      "metadata": {},
      "salience": 0.5306305,
      "mentions": [
        {
          "text": {
            "content": "R&B music",
            "beginOffset": 7
          },
          "type": "COMMON",
          "sentiment": {
            "magnitude": 0.9,
            "score": 0.9
          }
        }
      ],
      "sentiment": {
        "magnitude": 0.9,
        "score": 0.9
      }
    },
    {
      "name": "Marvin Gaye",
      "type": "PERSON",
      "metadata": {
        "mid": "/m/012z8_",
        "wikipedia_url": "http://en.wikipedia.org/wiki/Marvin_Gaye"
      },
      "salience": 0.21584158,
      "mentions": [
        {
          "text": {
            "content": "Marvin Gaye",
            "beginOffset": 18
          },
          "type": "PROPER",
          "sentiment": {
            "magnitude": 0.4,
            "score": 0.4
          }
        },
        {
          "text": {
            "content": "Marvin Gaye",
            "beginOffset": 138
          },
          "type": "PROPER",
          "sentiment": {
            "magnitude": 0.2,
            "score": -0.2
          }
        }
      ],
      "sentiment": {
        "magnitude": 0.6,
        "score": 0.1
      }
    },
    ...
  ],
  "language": "en"
}

Vous trouverez un exemple à la page Analyser les sentiments d'entités.

Analyse syntaxique

L'API Natural Language fournit de nombreux outils puissants permettant d'analyser des textes grâce à l'analyse syntaxique. Pour effectuer une analyse syntaxique, utilisez la méthode analyzeSyntax.

L'analyse syntaxique comprend les opérations suivantes :

  • L'extraction de phrases divise le flux de texte en une série de phrases.
  • La tokenisation divise le flux de texte en une série de jetons, chaque jeton correspondant généralement à un seul mot.
  • L'API Natural Language procède ensuite au traitement des jetons et y ajoute des informations syntaxiques, en se basant sur leur position au sein des phrases.

Une documentation complète sur l'ensemble des jetons syntaxiques peut être consultée dans le guide Arbres de morphologie et de dépendance.

Requêtes d'analyse syntaxique

Les requêtes d'analyse syntaxique sont envoyées à l'API Natural Language via la méthode analyzeSyntax sous la forme suivante :

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Ask not what your country can do for you,
               ask what you can do for your country."
  },
  "encodingType":"UTF8"
}

Réponses d'analyse syntaxique

L'API Natural Language traite le texte donné pour en extraire les phrases et les jetons. Une requête d'analyse syntaxique renvoie une réponse contenant ces phrases (sentences) et jetons (tokens) sous la forme suivante :

{
  "sentences": [
    ... Array of sentences with sentence information
  ],
  "tokens": [
    ... Array of tokens with token information
  ]
}

Extraction de phrase

Lors de l'analyse syntaxique, l'API Natural Language renvoie un tableau de phrases extraites du texte fourni, chaque phrase contenant les champs suivants au sein d'un élément parent text :

  • beginOffset, indiquant le décalage de caractère (basé sur zéro) dans le texte donné, à partir duquel commence la phrase. Ce décalage est calculé en utilisant la valeur de champ encodingType qui a été transmise.
  • content, contenant le texte intégral de la phrase extraite.

Par exemple, l'élément sentences suivant est reçu pour une requête d'analyse syntaxique du discours de Gettysburg :

{
  "sentences": [
    {
      "text": {
        "content": "Four score and seven years ago our fathers brought forth on
                    this continent a new nation, conceived in liberty and
                    dedicated to the proposition that all men are created
                    equal.",
        "beginOffset": 0
      }
    },
    {
      "text": {
        "content": "Now we are engaged in a great civil war, testing whether
                    that nation or any nation so conceived and so dedicated can
                    long endure.",
        "beginOffset": 175
      }
    },
...
...
    {
      "text": {
        "content": "It is rather for us to be here dedicated to the great task
                    remaining before us--that from these honored dead we take
                    increased devotion to that cause for which they gave the
                    last full measure of devotion--that we here highly resolve
                    that these dead shall not have died in vain, that this
                    nation under God shall have a new birth of freedom, and that
                    government of the people, by the people, for the people
                    shall not perish from the earth.",
        "beginOffset": 1002
      }
    }
  ],
  "language": "en"
}

Une requête d'analyse syntaxique adressée à l'API Natural Language inclut également un ensemble de jetons. Vous pouvez utiliser les informations associées à chaque jeton pour effectuer une analyse plus poussée des phrases renvoyées. Pour plus d’informations sur ces jetons, consultez le guide Arbres de morphologie et de dépendance.

Tokenisation

La méthode analyzeSyntax transforme également le texte en une série de jetons qui correspondent aux différents éléments textuels (c'est-à-dire les mots) du contenu transmis. Le processus par lequel l'API Natural Language crée cet ensemble de jetons est appelé la tokenisation.

Une fois ces jetons extraits, l'API Natural Language les traite pour déterminer les classes de mots (y compris les informations morphologiques) et les lemmes qui leur sont associés. Les jetons sont par ailleurs évalués et placés dans un arbre de dépendance, ce qui vous permet de déterminer la signification syntaxique des jetons et d'illustrer la relation entre les jetons et les phrases dont ils sont issus. Les informations syntaxiques et morphologiques associées à ces jetons sont utiles pour comprendre la structure syntaxique des phrases dans l'API Natural Language.

L'ensemble des champs de jetons renvoyés dans une réponse JSON d'analyse syntaxique est spécifié ci-dessous :

  • text contient les données textuelles associées à ce jeton, avec les champs enfants suivants :

    • beginOffset contient le décalage de caractère (basé sur zéro) dans le texte fourni. Sachez que bien que les dépendances (décrites ci-dessous) n'existent que dans les phrases, le positionnement des décalages de jetons se fait dans l'ensemble du texte. Ce décalage est calculé en utilisant la valeur de champ encodingType qui a été transmise.
    • content contient le contenu textuel réel du texte d'origine.

  • partOfSpeech fournit des informations grammaticales sur le jeton, y compris des informations morphologiques, telles que son temps, sa personne, son nombre, son genre, etc. (Pour des informations plus complètes sur ces champs, consultez le guide Arborescences de morphologies et de dépendances.)

  • lemma contient le mot "racine" sur lequel ce mot est basé, ce qui vous permet de définir l'utilisation canonique du mot dans le texte. Par exemple, les mots "écrire" et "écrit" sont basés sur le même lemme ("écrire"). De même, les formes du pluriel et du singulier sont basées sur les lemmes : "maison" et "maisons" désignent toutes deux une même forme. (Voir Lemme (linguistique).)

  • Les champs dependencyEdge identifient la relation entre les mots d'une phrase contenant un jeton, au moyen d'arêtes dans une arborescence orientée. Ces informations peuvent être utiles pour la traduction, l'extraction d'informations et la synthèse. (Le guide Arbres de morphologie et de dépendance contient des informations plus détaillées sur l'analyse des dépendances.) Chaque champ dependencyEdge contient les champs enfants suivants :

    • headTokenIndex fournit la valeur d'index (basée sur zéro) du "jeton parent" de ce jeton, dans la phrase d'encapsulation du jeton. Un jeton sans parent s'indexe lui-même.
    • label fournit le type de dépendance de ce jeton par rapport à son jeton principal.

La citation suivante issue du discours inaugural de Franklin D. Roosevelt produira les jetons suivants :

REMARQUE : Toutes les balises partOfSpeech contenant les valeurs *_UNKNOWN ont été supprimées par souci de clarté.

 "tokens": [
    {
      "text": {
        "content": "The",
        "beginOffset": 4
      },
      "partOfSpeech": {
        "tag": "DET",
      },
      "dependencyEdge": {
        "headTokenIndex": 2,
        "label": "DET"
      },
      "lemma": "The"
    },
    {
      "text": {
        "content": "only",
        "beginOffset": 8
      },
      "partOfSpeech": {
        "tag": "ADJ",
      },
      "dependencyEdge": {
        "headTokenIndex": 2,
        "label": "AMOD"
      },
      "lemma": "only"
    },
    {
      "text": {
        "content": "thing",
        "beginOffset": 13
      },
      "partOfSpeech": {
        "tag": "NOUN",
        "number": "SINGULAR",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "NSUBJ"
      },
      "lemma": "thing"
    },
    {
      "text": {
        "content": "we",
        "beginOffset": 19
      },
      "partOfSpeech": {
        "tag": "PRON",
        "case": "NOMINATIVE",
        "number": "PLURAL",
        "person": "FIRST",
      },
      "dependencyEdge": {
        "headTokenIndex": 4,
        "label": "NSUBJ"
      },
      "lemma": "we"
    },
    {
      "text": {
        "content": "have",
        "beginOffset": 22
      },
      "partOfSpeech": {
        "tag": "VERB",
        "mood": "INDICATIVE",
        "tense": "PRESENT",
      },
      "dependencyEdge": {
        "headTokenIndex": 2,
        "label": "RCMOD"
      },
      "lemma": "have"
    },
    {
      "text": {
        "content": "to",
        "beginOffset": 27
      },
      "partOfSpeech": {
        "tag": "PRT",
      },
      "dependencyEdge": {
        "headTokenIndex": 6,
        "label": "AUX"
      },
      "lemma": "to"
    },
    {
      "text": {
        "content": "fear",
        "beginOffset": 30
      },
      "partOfSpeech": {
        "tag": "VERB",
      },
      "dependencyEdge": {
        "headTokenIndex": 4,
        "label": "XCOMP"
      },
      "lemma": "fear"
    },
    {
      "text": {
        "content": "is",
        "beginOffset": 35
      },
      "partOfSpeech": {
        "tag": "VERB",
        "mood": "INDICATIVE",
        "number": "SINGULAR",
        "person": "THIRD",
        "tense": "PRESENT",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "ROOT"
      },
      "lemma": "be"
    },
    {
      "text": {
        "content": "fear",
        "beginOffset": 38
      },
      "partOfSpeech": {
        "tag": "NOUN",
        "number": "SINGULAR",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "ATTR"
      },
      "lemma": "fear"
    },
    {
      "text": {
        "content": "itself",
        "beginOffset": 43
      },
      "partOfSpeech": {
        "tag": "PRON",
        "case": "ACCUSATIVE",
        "gender": "NEUTER",
        "number": "SINGULAR",
        "person": "THIRD",
      },
      "dependencyEdge": {
        "headTokenIndex": 8,
        "label": "NN"
      },
      "lemma": "itself"
    },
    {
      "text": {
        "content": ".",
        "beginOffset": 49
      },
      "partOfSpeech": {
        "tag": "PRON",
        "case": "ACCUSATIVE",
        "gender": "NEUTER",
        "number": "SINGULAR",
        "person": "THIRD",
      },
      "dependencyEdge": {
        "headTokenIndex": 8,
        "label": "NN"
      },
      "lemma": "itself"
    },
    {
      "text": {
        "content": ".",
        "beginOffset": 49
      },
      "partOfSpeech": {
        "tag": "PUNCT",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "P"
      },
      "lemma": "."
    }
  ],

Classification de contenu

Vous pouvez demander à l'API Natural Language d'analyser un document et de renvoyer une liste des catégories de contenu qui s'appliquent au texte du document. Pour classifier le contenu d'un document, appelez la méthode classifyText.

La liste complète des catégories de contenu renvoyées pour la méthode classifyText figure ici.

L'API Natural Language filtre les catégories renvoyées par la méthode classifyText pour n'inclure que les catégories les plus pertinentes pour une requête. Par exemple, si /Science et /Science/Astronomy s'appliquent toutes deux à un document, seule la catégorie /Science/Astronomy est renvoyée, car il s'agit du résultat le plus spécifique.

Pour obtenir un exemple de classification de contenu avec l'API Natural Language, consultez la page Classifier des contenus.

Effectuer plusieurs opérations dans une même requête

Si vous souhaitez effectuer un ensemble d'opérations Natural Language en un seul appel de méthode, utilisez annotateText comme requête de l'API Natural Language à usage général. Une requête JSON d'annotation textuelle est semblable à une requête d'analyse des entités standard, à ceci près qu'elle requiert en plus qu'un ensemble de fonctionnalités soient transmises pour indiquer les opérations à effectuer sur le texte. Ces fonctionnalités sont énumérées ci-dessous :

  • extractDocumentSentiment effectue une analyse des sentiments, comme décrit dans la section Analyse des sentiments.
  • extractEntities effectue une analyse des entités, comme décrit dans la section Analyse des entités.
  • extractSyntax indique que le texte donné doit être traité pour pouvoir effectuer une analyse syntaxique, comme décrit dans la section Analyse syntaxique.

La requête suivante appelle l'API pour annoter les fonctionnalités (features) dans une phrase courte.

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"The windy, cold weather was unbearable this winter."
  },
  "features":{
    "extractSyntax":true,
    "extractEntities":true,
    "extractDocumentSentiment":true
  },
  "encodingType":"UTF8"
}