Conceptos básicos de la API de Natural Language

Este documento es una guía de los conceptos básicos del uso de la API de Cloud Natural Language. En esta guía conceptual, se abordan los tipos de solicitudes que puedes realizar a la API de Natural Language, cómo crear esas solicitudes y cómo manejar sus respuestas. Recomendamos que todos los usuarios de la API de Natural Language lean esta guía y uno de los instructivos asociados antes de comenzar a usar la API.

Características de Natural Language

La API de Natural Language tiene varios métodos para realizar análisis y anotaciones en tu texto. Cada nivel de análisis proporciona información valiosa para la comprensión del lenguaje. Estos métodos se mencionan a continuación:

• El Análisis de opiniones inspecciona el texto dado e identifica la opinión emocional predominante dentro del texto, en especial para determinar la actitud de un escritor como positiva, negativa o neutra. El análisis de opiniones se ejecuta mediante el método analyzeSentiment.

• El Análisis de entidades inspecciona el texto dado en busca de entidades conocidas (nombres propios como figuras públicas, puntos de referencia, etc., y sustantivos comunes como restaurantes, estadios, etc.), y muestra información sobre esas entidades. El análisis de entidades se ejecuta con el método analyzeEntities.

• El Análisis de opiniones de entidades busca entidades conocidas en el texto dado (nombres propios y sustantivos comunes), muestra información sobre esas entidades e identifica la emoción predominante de la entidad en el texto, en especial para determinar si la actitud del escritor hacia la entidad es positiva, negativa o neutra. El análisis de entidades se ejecuta con el método analyzeEntitySentiment.

• El Análisis sintáctico extrae información lingüística mediante la división del texto dado en una serie de oraciones y tokens (por lo general, límites de palabras), para proporcionar un análisis más detallado sobre esos tokens. El análisis sintáctico se realiza con el método analyzeSyntax.

• La Clasificación de contenido analiza el contenido del texto y muestra una categoría para el mismo. La clasificación de contenido se realiza mediante el método classifyText.

Cada llamada a la API también detecta y muestra el idioma si el emisor no especificó un idioma en la solicitud inicial.

Además, si deseas realizar varias operaciones de lenguaje natural en un texto determinado con una sola llamada a la API, también se puede usar la solicitud annotateText para realizar análisis de opiniones y de entidades.

Solicitudes básicas de Natural Language

La API de Natural Language es una API de REST que consiste en una solicitud JSON y una respuesta. A continuación, aparece una solicitud de Análisis de entidades JSON de Natural Language:

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

Estos campos se explican a continuación:

• document contiene los datos de esta solicitud, que constan de los siguientes subcampos:
  • type: tipo de documento (HTML o PLAIN_TEXT)
  • language: (opcional) el idioma del texto de la solicitud. Si no se especifica, el idioma se detectará automáticamente. Para obtener información sobre los idiomas compatibles con la API de Natural Language, consulta Idiomas compatibles. Los idiomas no compatibles mostrarán un error en la respuesta JSON.
    
  • content o gcsContentUri, que contienen el texto que se va a evaluar. Si pasas content, este texto se incluye directamente en la solicitud JSON (como se mostró antes). Si pasas gcsContentUri, el campo debe contener un URI que dirija al contenido de texto dentro de Google Cloud Storage.
• encodingType - (obligatorio) el esquema de codificación en el cual se deben calcular los desplazamientos de caracteres mostrados en el texto, y que deben coincidir con la codificación del texto pasado. Si no se configura este parámetro, la solicitud no arrojará un error, pero todos los desplazamientos de ese tipo se configurarán en -1.

Especificar el contenido del texto

Cuando pasas una solicitud de la API de Natural Language, especificas el texto que se debe procesar de una de dos maneras:

• Pasar el texto directamente en un campo content.
• Pasar un URI de Google Cloud Storage dentro de un campo gcsContentUri.

En cualquier caso, debes asegurarte de no sobrepasar los Límites de contenido permitido. Ten en cuenta que estos límites de contenido son por byte, no por caracter; por lo tanto, la longitud de los caracteres depende de la codificación de tu texto.

La solicitud siguiente se refiere a un archivo de Google Cloud Storage que contiene la Dirección de Gettysburg:

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

Análisis de opiniones

El análisis de opiniones intenta determinar la actitud general (positiva o negativa) expresada en el texto. La opinión se representa mediante valores numéricos score y magnitude.

Campos de respuesta al Análisis de opiniones

A continuación, se muestra una respuesta analyzeSentiment de muestra a la Dirección de Gettysburg:

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