Obtén una vista previa de los vínculos de Google Libros con chips inteligentes

Nivel de programación: Intermedio
Duración: 30 minutos
Tipo de proyecto: Complemento de Google Workspace

Objetivos

• Comprende qué hace el complemento.
• Comprende cómo compilar un complemento con Apps Script y qué hacen los servicios de Apps Script.
• Configura el entorno.
• Configura la secuencia de comandos.
• Ejecuta la secuencia de comandos.

Acerca de este complemento de Google Workspace

En este ejemplo, crearás un complemento de Google Workspace que muestre vistas previas de vínculos de Google Books en un documento de Google Docs. Cuando escribes o pegas una URL de Google Libros en un documento, el complemento reconoce el vínculo y activa una vista previa. Para obtener una vista previa del vínculo, puedes convertirlo en un chip inteligente y mantener el puntero sobre él para ver una tarjeta que muestre más información sobre el libro.

Este complemento usa el servicio UrlFetch de Apps Script para conectarse a la API de Google Books y obtener información sobre Google Books para mostrarla en Documentos de Google.

Cómo funciona

En el archivo de manifiesto del complemento de Google Workspace, la secuencia de comandos configura el complemento para que extienda Documentos de Google y active las vistas previas de vínculos para las URLs que coinciden con ciertos patrones del sitio web de Google Books (https://books.google.com).

En el archivo de código, la secuencia de comandos se conecta a la API de Google Books y usa la URL para obtener información sobre el libro (que es una instancia del recurso Volume). La secuencia de comandos usa esta información para generar un chip inteligente que muestra el título del libro y una tarjeta de vista previa que muestra un resumen, el recuento de páginas, una imagen de la portada del libro y la cantidad de calificaciones.

Servicios de Apps Script

Este complemento usa los siguientes servicios:

• Servicio de UrlFetch: Se conecta a la API de Google Books para obtener información sobre los libros (que son instancias del recurso Volume de la API).
• Card Service: Crea la interfaz de usuario del complemento.

Requisitos previos

Para usar esta muestra, necesitas cumplir con los siguientes requisitos previos:

• Una Cuenta de Google (es posible que las cuentas de Google Workspace requieran la aprobación del administrador)

• Un navegador web con acceso a Internet

• Un proyecto de Google Cloud con una cuenta de facturación asociada Consulta Habilita la facturación para un proyecto.

Configura tu entorno

En las siguientes secciones, se configura tu entorno para compilar el complemento.

Abre tu proyecto de Cloud en la consola de Google Cloud.

Si aún no está abierto, abre el proyecto de Cloud que deseas usar para esta muestra:

1. En la consola de Google Cloud, ve a la página Seleccionar un proyecto.

   Selecciona un proyecto de Cloud

2. Selecciona el proyecto de Google Cloud que deseas usar. O bien, haz clic en Crear proyecto y sigue las instrucciones en pantalla. Si creas un proyecto de Google Cloud, es posible que debas activar la facturación para el proyecto.

Activa la API de Google Books

Este complemento se conecta a la API de Google Books. Antes de usar las APIs de Google, debes activarlas en un proyecto de Google Cloud. Puedes activar una o más APIs en un solo proyecto de Google Cloud.

• En tu proyecto de Cloud, activa la API de Books.

  Activa la API

Cómo configurar la pantalla de consentimiento de OAuth

Este complemento requiere un proyecto de Cloud con una pantalla de consentimiento configurada. Configurar la pantalla de consentimiento de OAuth define lo que Google muestra a los usuarios y registra tu app para que puedas publicarla más adelante.

1. En la consola de Google Cloud, ve a Menú menu > Google Auth platform > Branding.

   Ir a Desarrollo de la marca

2. Si ya configuraste el Google Auth platform, puedes configurar los siguientes parámetros de configuración de la pantalla de consentimiento de OAuth en Branding, Audience y Data Access. Si ves un mensaje que dice Google Auth platform aún no se configuró, haz clic en Comenzar:
1. En Información de la app, en Nombre de la app, ingresa un nombre para la app.
2. En Correo electrónico de asistencia del usuario, elige una dirección de correo electrónico de asistencia a la que los usuarios puedan comunicarse contigo si tienen preguntas sobre su consentimiento.
3. Haz clic en Siguiente.
4. En Público, selecciona Interno.
5. Haz clic en Siguiente.
6. En Información de contacto, ingresa una dirección de correo electrónico en la que puedas recibir notificaciones sobre cualquier cambio en tu proyecto.
7. Haz clic en Siguiente.
8. En Finalizar, revisa la Política de Datos del Usuario de los Servicios de las APIs de Google y, si la aceptas, selecciona Acepto la Política de Datos del Usuario de los Servicios de las APIs de Google.
9. Haz clic en Continuar.
10. Haz clic en Crear.
3. Por el momento, puedes omitir la adición de permisos. En el futuro, cuando crees una app para usarla fuera de tu organización de Google Workspace, deberás cambiar el Tipo de usuario a Externo. Luego, agrega los permisos de autorización que requiere tu app. Para obtener más información, consulta la guía completa Configura el consentimiento de OAuth.

Obtén una clave de API para la API de Google Books

1. Ve a la consola de Google Cloud. Asegúrate de que tu proyecto habilitado para la facturación esté abierto.

2. En la consola de Google Cloud, ve a Menú menu > APIs y servicios > Credenciales.

   Ir a Credenciales

3. Haz clic en Crear credenciales > Clave de API.

4. Toma nota de tu clave de API para usarla en un paso posterior.

Configura la secuencia de comandos

En las siguientes secciones, se configura la secuencia de comandos para compilar el complemento.

Crea el proyecto de Apps Script

1. Haz clic en el siguiente botón para abrir el proyecto de Apps Script Preview links from Google Books.
   Abre el proyecto
2. Haz clic en info_outline Descripción general.
3. En la página de descripción general, haz clic en Crear una copia.
4. En tu copia del proyecto de Apps Script, ve al archivo Code.gs y reemplaza YOUR_API_KEY por la clave de API que generaste en la sección anterior.

Copia el número del proyecto de Cloud.

1. En la consola de Google Cloud, ve a Menú menu > IAM y administración > Configuración.

   Ir a Configuración de IAM y administración

2. En el campo Número del proyecto, copia el valor.

Configura el proyecto de Cloud del proyecto de Apps Script

1. En tu proyecto de Apps Script, haz clic en Configuración del proyecto.
2. En Proyecto de Google Cloud, haz clic en Cambiar proyecto.
3. En Número de proyecto de GCP, pega el número de proyecto de Google Cloud.
4. Haz clic en Establecer el proyecto.

Prueba el complemento

En las siguientes secciones, se probará el complemento que creaste.

Instala una implementación de prueba

1. En tu proyecto de Apps Script, haz clic en code Editor.
2. Reemplaza YOUR_API_KEY por la clave de API de la API de Google Books que creaste en una sección anterior.
3. Haz clic en Implementar > Probar implementaciones.
4. Haz clic en Instalar > Listo.

Cómo obtener una vista previa de un vínculo en Documentos de Google

1. Crea un documento de Documentos de Google en docs.new.
2. Pega la siguiente URL en el documento y presiona la tecla de tabulación para convertirla en un chip inteligente: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
3. Mantén el puntero sobre el chip inteligente y, cuando se te solicite, autoriza el acceso para ejecutar el complemento. La tarjeta de vista previa muestra información sobre el libro.

En la siguiente imagen, se muestra la vista previa del vínculo:

Revisa el código

Para revisar el código de Apps Script de este complemento, haz clic en Ver código fuente para expandir la sección:

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/workspace.linkpreview",
    "https://www.googleapis.com/auth/script.external_request"
  ],
  "urlFetchWhitelist": [
    "https://www.googleapis.com/books/v1/volumes/"
  ],
  "addOns": {
    "common": {
      "name": "Preview Books Add-on",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/library-icon.png",
      "layoutProperties": {
        "primaryColor": "#dd4b39"
      }
    },
    "docs": {
      "linkPreviewTriggers": [
        {
          "runFunction": "bookLinkPreview",
          "patterns": [
            {
              "hostPattern": "*.google.*",
              "pathPrefix": "books"
            },
            {
              "hostPattern": "*.google.*",
              "pathPrefix": "books/edition"
            }
          ],
          "labelText": "Book",
          "logoUrl": "https://developers.google.com/workspace/add-ons/images/book-icon.png",
          "localizedLabelText": {
            "es": "Libros"
          }
        }
      ]
    }
  }
}

function getBook(id) {
  const apiKey = 'YOUR_API_KEY'; // Replace with your API key
  const apiEndpoint = `https://www.googleapis.com/books/v1/volumes/${id}?key=${apiKey}&country=US`;
  const response = UrlFetchApp.fetch(apiEndpoint);
  return JSON.parse(response);
}

function bookLinkPreview(event) {
 if (event.docs.matchedUrl.url) {
    const segments = event.docs.matchedUrl.url.split('/');
    const volumeID = segments[segments.length - 1];

    const bookData = getBook(volumeID);
    const bookTitle = bookData.volumeInfo.title;
    const bookDescription = bookData.volumeInfo.description;
    const bookImage = bookData.volumeInfo.imageLinks.small;
    const bookAuthors = bookData.volumeInfo.authors;
    const bookPageCount = bookData.volumeInfo.pageCount;

    const previewHeader = CardService.newCardHeader()
      .setSubtitle('By ' + bookAuthors)
      .setTitle(bookTitle);

    const previewPages = CardService.newDecoratedText()
      .setTopLabel('Page count')
      .setText(bookPageCount);

    const previewDescription = CardService.newDecoratedText()
      .setTopLabel('About this book')
      .setText(bookDescription).setWrapText(true);

    const previewImage = CardService.newImage()
      .setAltText('Image of book cover')
      .setImageUrl(bookImage);

    const buttonBook = CardService.newTextButton()
      .setText('View book')
      .setOpenLink(CardService.newOpenLink()
        .setUrl(event.docs.matchedUrl.url));

    const cardSectionBook = CardService.newCardSection()
      .addWidget(previewImage)
      .addWidget(previewPages)
      .addWidget(CardService.newDivider())
      .addWidget(previewDescription)
      .addWidget(buttonBook);

    return CardService.newCardBuilder()
    .setHeader(previewHeader)
    .addSection(cardSectionBook)
    .build();
  }
}

Temas relacionados

• Vínculos de vista previa con chips inteligentes
• Documentación de referencia de la API de Google Books