Uso de la API de lenguaje natural de Google Docs

Published in

GDG IPN

9 min readFeb 7, 2020

Introducción

La API de lenguaje natural es un modelo de aprendizaje automático previamente capacitado que puede analizar la sintaxis, extraer entidades y evaluar el sentimiento del texto. Se puede llamar desde Google Docs para realizar todas estas funciones.

Este codelab lo guiará a través de la llamada a la API de lenguaje natural para reconocer el sentimiento del texto seleccionado en un documento de Google y resaltarlo en función de ese sentimiento.

¿Qué vamos a construir?

Una vez que este codelab esté completo, podrá seleccionar texto en un documento y marcar su sentimiento, utilizando una opción de menú, como se muestra a continuación.

El texto se resaltará en rojo para el sentimiento negativo, verde para el sentimiento positivo y amarillo para el sentimiento neutral.

Lo que aprenderás

Cómo llamar a la API de lenguaje natural desde Google Docs
Cómo agregar menús a Google Docs
Cómo reconocer y trabajar con texto seleccionado en Google Docs

Lo que necesitarás

Una cuenta de Google
Acceso a un proyecto de Google Cloud Platform

Este codelab se centra en llamar a la API de lenguaje natural desde Google Docs. Los conceptos y los bloques de código no relevantes se pasan por alto y se proporcionan para que simplemente los copie y pegue.

Configuración y requisitos

Configuración del entorno a su propio ritmo

Si aún no tiene una cuenta de Google (Gmail o Google Apps), debe crear una .
Inicie sesión en la consola de Google Cloud Platform ( console.cloud.google.com ) y cree un nuevo proyecto:

A continuación, deberá habilitar la facturación en la Consola de desarrolladores para utilizar los recursos de Google Cloud, como la API de lenguaje natural. No debería haber ningún cargo por usar Google Cloud Platform durante este codelab ya que las primeras 5,000 llamadas de la API de lenguaje natural cada mes son gratuitas.

Los nuevos usuarios de Google Cloud Platform son elegibles para una prueba gratuita de $ 300 .

Inicialice su entorno de proyecto de Google Cloud Platform

Inicie sesión en Google Cloud Console desde una pestaña / ventana del navegador, en https://console.cloud.google.com .

Esto es lo que debería ver una vez que haya iniciado sesión:

Habilitar la API de lenguaje natural

Importante : visite la página del Administrador de API para iniciar una configuración inicial detrás de escena, como habilitar la API de lenguaje natural y crear una clave de usuario

Habilite la API de lenguaje natural seleccionando Habilitar API en la parte superior del tablero y seleccionando la API de lenguaje natural.

Obtener clave API

Tendremos que generar una clave API para pasar nuestra URL de solicitud.

Para crear una clave API, vaya a la sección Administrador de API del panel de su proyecto:

A continuación, navegue a la pestaña Credenciales y haga clic en Crear credenciales:

En el menú desplegable, seleccione la clave API:

Copie la clave API que se le da a un archivo de texto o un documento de Google para usar en un paso posterior. Una vez que tenga la clave API, estará listo para pasar a Google Docs.

Configura tu documento de Google

Antes de poder llamar a la API de lenguaje natural, necesitará tener un programa Apps Script para crear el menú, vincularlo a una función para marcar el texto y extraer el texto de la selección del usuario.

Crea un nuevo Google Doc .
Desde su nuevo documento, seleccione el elemento de menú Herramientas> Editor de secuencias de comandos . Si se le presenta una pantalla de bienvenida, haga clic en Proyecto en blanco .
Elimine cualquier código en el editor de scripts y pegue el código a continuación. Este código creará un elemento de menú, extraerá el texto del texto seleccionado actual y resaltará el texto en función de su opinión. Todavía no llama a la API de lenguaje natural.

/**
* @OnlyCurrentDoc
*
* The above comment directs Apps Script to limit the scope of file
* access for this add-on. It specifies that this add-on will only
* attempt to read or modify the files in which the add-on is used,
* and not all of the user's files. The authorization request message
* presented to users will reflect this limited scope.
*/
/**
* Creates a menu entry in the Google Docs UI when the document is
* opened.
* 
*/
function onOpen() {
  var ui = DocumentApp.getUi();
  
  ui.createMenu('Natural Language Tools')
    .addItem('Mark Sentiment', 'markSentiment')
    .addToUi();
}
/**
* Gets the user-selected text and highlights it based on sentiment 
* with green for positive sentiment, red for negative, and yellow 
* for neutral.
* 
*/
function markSentiment() {
  var POSITIVE_COLOR = '#00ff00';  //  Colors for sentiments
  var NEGATIVE_COLOR = '#ff0000';
  var NEUTRAL_COLOR = '#ffff00';
  var NEGATIVE_CUTOFF = -0.2;   //  Thresholds for sentiments
  var POSITIVE_CUTOFF = 0.2;
  
  var selection = DocumentApp.getActiveDocument().getSelection();
  if (selection) {
    var string = getSelectedText();
    
    var sentiment = retrieveSentiment(string);
  
    //  Select the appropriate color   
    var color = NEUTRAL_COLOR;
    if (sentiment <= NEGATIVE_CUTOFF) {
      color = NEGATIVE_COLOR;
    }
    if (sentiment >= POSITIVE_CUTOFF) {
      color = POSITIVE_COLOR;
    }
    
    //  Highlight the text 
    var elements = selection.getSelectedElements();
    for (var i = 0; i < elements.length; i++) {
      if (elements[i].isPartial()) {
        var element = elements[i].getElement().editAsText();
        var startIndex = elements[i].getStartOffset();
        var endIndex = elements[i].getEndOffsetInclusive();
        element.setBackgroundColor(startIndex, endIndex, color);
  
      } else {
        var element = elements[i].getElement().editAsText();
        foundText = elements[i].getElement().editAsText();
        foundText.setBackgroundColor(color);
      } 
    }
  }
}
/**
 * Returns a string with the contents of the selected text.
 * If no text is selected, returns an empty string.
 */
function getSelectedText() {
  var selection = DocumentApp.getActiveDocument().getSelection();
  var string = "";
  if (selection) {
    var elements = selection.getSelectedElements();
    
    for (var i = 0; i < elements.length; i++) {
      if (elements[i].isPartial()) {
        var element = elements[i].getElement().asText();
        var startIndex = elements[i].getStartOffset();
        var endIndex = elements[i].getEndOffsetInclusive() + 1;
        var text = element.getText().substring(startIndex, endIndex);
        string = string + text;
        
      } else {
        var element = elements[i].getElement();
        // Only translate elements that can be edited as text; skip
        // images and other non-text elements.
        if (element.editAsText) {
          string = string + element.asText().getText();
        }
      }
    }
  }
  return string;
}/** Given a string, will call the Natural Language API and retrieve 
  * the sentiment of the string.  The sentiment will be a real 
  * number in the range -1 to 1, where -1 is highly negative 
  * sentiment and 1 is highly positive.
*/
function retrieveSentiment (line) {
//  TODO:  Call the Natural Language API with the line given
//         and return the sentiment value. 
  return 0.0;
}

Más detalles sobre Apps Script están disponibles en el sitio App Script .

Seleccione el elemento de menú Archivo> Guardar todo. Nombre su nuevo script “Herramientas de lenguaje natural” y haga clic en Aceptar. (El nombre del script se muestra a los usuarios finales en varios lugares, incluido el cuadro de diálogo de autorización).
Regrese a su documento. Agregue texto a su documento. (Esta muestra proviene de Alicia en el país de las maravillas en el Proyecto Gutenberg , pero no dude en usar el texto que desee).
Vuelva a cargar el documento para ver el nuevo menú, “Herramientas de lenguaje natural”, que creó, que aparece en la barra de herramientas de Google Docs
Seleccione texto y luego la opción Marcar sentimiento del menú Herramientas de lenguaje natural. La primera vez que seleccione esta opción, se le solicitará que autorice la ejecución del script. Haga clic en Autorizar e inicie sesión con sus credenciales.
Permita que Natural Language Tools vea y administre documentos en los que se ha instalado esta aplicación.
Una vez que se autoriza la secuencia de comandos, el texto seleccionado se resaltará en amarillo, ya que el código auxiliar para el análisis de sentimientos siempre devuelve 0.0, que es neutral.

Llame a la API de lenguaje natural

Una vez que su programa pueda extraer texto de la selección y resaltarlo, es hora de llamar a la API de lenguaje natural. Todo esto se hará en el cuerpo de la retrieveSentimentfunción.

Puede encontrar todos los detalles de la API de lenguaje natural aquí .

Regrese a Herramientas -> Editor de secuencias de comandos en Google Docs.

En la retrieveSentimentfunción:

Eliminar las líneas actuales.
Agregue una variable para contener su clave API, que guardó en un paso anterior.

var apiKey = "your key here";

Cree una variable que contendrá la URL de la API de lenguaje natural con su clave API adjunta.

var apiEndpoint = 
'https://language.googleapis.com/v1/documents:analyzeSentiment?key=' 
+ apiKey;

Construya una estructura a partir de la línea pasada a la función que contiene el texto de la línea, junto con su tipo e idioma. Puede encontrar más información sobre los idiomas admitidos en la documentación del producto .

var docDetails = {
    language: 'en-us',
    type: 'PLAIN_TEXT',
    content: line
  };

Cree la carga útil de datos completa a partir de los detalles del documento agregando el tipo de codificación.

var nlData = {
    document: docDetails,
    encodingType: 'UTF8'
  };

Cree una estructura que contenga la carga útil y la información de encabezado necesaria.

var nlOptions = {
    method : 'post',
    contentType: 'application/json',
    payload : JSON.stringify(nlData)
  };

Haga la llamada, guardando la respuesta.

var response = UrlFetchApp.fetch(apiEndpoint, nlOptions);

La respuesta se devolverá en formato JSON, así que analícela y extraiga el campo de puntuación, si existe. Devuelve ese campo o 0.0.

var data = JSON.parse(response);
  
  var sentiment = 0.0;
  //  Ensure all pieces were in the returned value
  if (data && data.documentSentiment 
          && data.documentSentiment.score){
     sentiment = data.documentSentiment.score;
  }
  
  return sentiment;

El código completo para recuperar el sentimiento está debajo.

function retrieveSentiment (line) {
  var apiKey = "your key here";
  var apiEndpoint = 
'https://language.googleapis.com/v1/documents:analyzeSentiment?key=' 
+ apiKey;  //  Create a structure with the text, its language, its type,
  //  and its encoding
  var docDetails = {
    language: 'en-us',
    type: 'PLAIN_TEXT',
    content: line
  };
  
  var nlData = {
    document: docDetails,
    encodingType: 'UTF8'
  };
  
  //  Package all of the options and the data together for the call
  var nlOptions = {
    method : 'post',
    contentType: 'application/json',
    payload : JSON.stringify(nlData)
  };
  
  //  And make the call
  var response = UrlFetchApp.fetch(apiEndpoint, nlOptions);
  
  var data = JSON.parse(response);
  
  var sentiment = 0.0;
  //  Ensure all pieces were in the returned value
  if (data && data.documentSentiment 
          && data.documentSentiment.score){
     sentiment = data.documentSentiment.score;
  }
  
  return sentiment;
}

Guarde su script, vuelva a cargar el documento y pruebe el programa completo. Es posible que deba volver a autorizar con sus credenciales para habilitar la nueva funcionalidad. Seleccione diferentes secciones de su documento para ver cómo puede diferir el sentimiento sobre sus partes.

¡Felicidades!

Creó un documento de Google y llamó a la API de lenguaje natural para analizar el sentimiento de partes seleccionadas del documento.

Si ha terminado con este ejemplo, regrese a la sección Credenciales de Google Cloud Console y elimine la clave API para asegurarse de que no se use en otro lugar.