Prévisualiser des liens Google Livres avec les chips intelligents

Niveau de codage: intermédiaire
Durée: 30 minutes
Type de projet: module complémentaire Google Workspace

Objectifs

• Découvrez ce que fait le module complémentaire.
• Découvrez comment créer un module complémentaire à l'aide d'Apps Script et comprendre le rôle des services Apps Script.
• configurer votre environnement ;
• Configurez le script.
• Exécutez le script.

À propos de ce module complémentaire Google Workspace

Dans cet exemple, vous allez créer un module complémentaire Google Workspace qui prévisualise les liens de Google Livres dans un document Google Docs. Lorsque vous saisissez ou collez une URL Google Livres dans un document, le module complémentaire reconnaît le lien et déclenche un aperçu du lien. Pour prévisualiser le lien, vous pouvez le convertir en chip intelligent et maintenir le curseur dessus pour afficher une fiche contenant plus d'informations sur le livre.

Ce module complémentaire utilise le service UrlFetch d'Apps Script pour se connecter à l'API Google Livres et obtenir des informations sur Google Livres à afficher dans Google Docs.

Fonctionnement

Dans le fichier manifeste du module complémentaire Google Workspace, le script configure le module complémentaire pour qu'il étende Google Docs et déclenche des aperçus de liens pour les URL correspondant à certains modèles du site Web Google Livres (https://books.google.com).

Dans le fichier de code, le script se connecte à l'API Google Books et utilise l'URL pour obtenir des informations sur le livre (qui est une instance de la ressource Volume). Le script utilise ces informations pour générer un chip intelligent qui affiche le titre du livre et une fiche d'aperçu qui affiche un résumé, le nombre de pages, une image de la couverture du livre et le nombre d'avis.

Services Apps Script

Ce module complémentaire utilise les services suivants:

• Service URLFetch : se connecte à l'API Google Livres pour obtenir des informations sur les livres (qui sont des instances de la ressource Volume des API).
• Service de carte : crée l'interface utilisateur du module complémentaire.

Prérequis

Pour utiliser cet exemple, vous devez remplir les conditions préalables suivantes:

• Un compte Google (l'approbation de l'administrateur peut être nécessaire pour les comptes Google Workspace).

• Un navigateur Web avec accès à Internet

• Un projet Google Cloud avec un compte de facturation associé. Consultez la section Activer la facturation pour un projet.

Configurer votre environnement

Les sections suivantes configurent votre environnement pour créer le module complémentaire.

Ouvrez votre projet Cloud dans la console Google Cloud.

Si ce n'est pas déjà fait, ouvrez le projet Cloud que vous prévoyez d'utiliser pour cet exemple:

1. Dans la console Google Cloud, accédez à la page Sélectionner un projet.

   Sélectionner un projet Cloud

2. Sélectionnez le projet Google Cloud que vous souhaitez utiliser. Vous pouvez également cliquer sur Créer un projet et suivre les instructions à l'écran. Si vous créez un projet Google Cloud, vous devrez peut-être activer la facturation pour ce projet.

Activer l'API Google Books

Ce module complémentaire se connecte à l'API Google Livres. Avant d'utiliser les API Google, vous devez les activer dans un projet Google Cloud. Vous pouvez activer une ou plusieurs API dans un même projet Google Cloud.

• Dans votre projet Cloud, activez l'API Books.

  Activer l'API

Configurer l'écran d'autorisation OAuth

Ce module complémentaire nécessite un projet Cloud avec un écran d'autorisation configuré. La configuration de l'écran de consentement OAuth définit ce que Google affiche aux utilisateurs et enregistre votre application pour que vous puissiez la publier ultérieurement.

1. Dans la console Google Cloud, accédez à Menu  > API et services > Écran de consentement OAuth.

   Accéder à l'écran de consentement OAuth

2. Pour Type d'utilisateur, sélectionnez Interne, puis cliquez sur Créer.
3. Remplissez le formulaire d'enregistrement de l'application, puis cliquez sur Enregistrer et continuer.

4. Pour l'instant, vous pouvez ignorer l'ajout de champs d'application et cliquer sur Enregistrer et continuer. À l'avenir, lorsque vous créerez une application à utiliser en dehors de votre organisation Google Workspace, vous devrez remplacer le type d'utilisateur par Externe, puis ajouter les champs d'autorisation requis par votre application.

5. Consultez le résumé de l'enregistrement de votre application. Pour y apporter des modifications, cliquez sur Modifier. Si l'enregistrement de l'application semble correct, cliquez sur Revenir au tableau de bord.

Obtenir une clé API pour l'API Google Books

1. Accédez à Google Cloud Console. Assurez-vous que votre projet avec facturation activée est ouvert.

2. Dans la console Google Cloud, accédez à Menu  > API et services > Identifiants.

   Accéder à "Identifiants"

3. Cliquez sur Créer des identifiants > Clé API.

4. Notez votre clé API pour l'utiliser ultérieurement.

Configurer le script

Les sections suivantes configurent le script de compilation du module complémentaire.

Créer le projet Apps Script

1. Cliquez sur le bouton suivant pour ouvrir le projet Apps Script Aperçu des liens depuis Google Books.
   Ouvrir le projet
2. Cliquez sur  Vue d'ensemble.
3. Sur la page de présentation, cliquez sur  Créer une copie.
4. Dans votre copie du projet Apps Script, accédez au fichier Code.gs et remplacez YOUR_API_KEY par la clé API que vous avez générée dans la section précédente.

Copiez le numéro du projet Cloud

1. Dans la console Google Cloud, accédez à Menu  > IAM et administration > Paramètres.

   Accéder à la page Paramètres de la section IAM et administration

2. Dans le champ Numéro du projet, copiez la valeur.

Définir le projet Cloud du projet Apps Script

1. Dans votre projet Apps Script, cliquez sur Paramètres du projet.
2. Sous Projet Google Cloud Platform (GCP), cliquez sur Changer de projet.
3. Dans Numéro de projet GCP, collez le numéro du projet Google Cloud.
4. Cliquez sur Définir un projet.

Tester le module complémentaire

Les sections suivantes testent le module complémentaire que vous avez créé.

Installer un déploiement de test

1. Dans votre projet Apps Script, cliquez sur Éditeur.
2. Remplacez YOUR_API_KEY par la clé API de l'API Google Books, créée dans une section précédente.
3. Cliquez sur Déployer > Tester les déploiements.
4. Cliquez sur Installer > OK.

Prévisualiser un lien dans Google Docs

1. Créez un document Google Docs sur docs.new.
2. Collez l'URL suivante dans le document, puis appuyez sur la touche Tabulation pour la convertir en chip intelligent : https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
3. Pointez sur le chip intelligent et, lorsque vous y êtes invité, autorisez l'accès pour exécuter le module complémentaire. La fiche d'aperçu affiche des informations sur le livre.

L'image suivante montre l'aperçu du lien:

Examiner le code

Pour examiner le code Apps Script de ce module complémentaire, cliquez sur Afficher le code source pour développer la section:

Afficher le code source

appsscript.json

solutions/add-on/book-smartchip/appsscript.json

Afficher sur GitHub

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

Code.gs

solutions/add-on/book-smartchip/Code.js

Afficher sur GitHub

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();
  }
}

Articles associés

• Prévisualiser les liens avec les chips intelligents
• Documentation de référence de l'API Google Books