תצוגה מקדימה של קישורים מ-Google Books עם צ'יפים חכמים

רמת תכנות: בינונית
משך: 30 דקות
סוג הפרויקט: תוסף ל-Google Workspace

מטרות

  • להבין מה התוסף עושה.
  • להבין איך לפתח תוספים באמצעות Apps Script, ולהבין מה שירותי Apps Script.
  • הגדרת הסביבה.
  • מגדירים את הסקריפט.
  • מריצים את הסקריפט.

מידע על התוסף הזה ל-Google Workspace

בדוגמה הזו, יוצרים תוסף ל-Google Workspace שמציג תצוגה מקדימה של קישורים מ-Google Books במסמך ב-Google Docs. כשמקלידים או מדביקים כתובת URL של Google Books במסמך, התוסף מזהה את הקישור ומפעיל תצוגה מקדימה של הקישור. כדי לראות תצוגה מקדימה של הקישור, אפשר להמיר אותו לצ'יפ חכם ולהעביר את העכבר מעל הקישור כדי לראות כרטיס עם מידע נוסף על הספר.

התוסף הזה משתמש בשירות UrlFetch של Apps Script כדי להתחבר לממשק ה-API של Google Books ולקבל מידע על Google Books להצגה ב-Google Docs.

איך זה עובד

בקובץ המניפסט של התוסף של Google Workspace, הסקריפט מגדיר את התוסף כך שירחיב את Google Docs ויפעיל תצוגות מקדימות של קישורים לכתובות URL שתואמות לדפוסים מסוימים מהאתר של Google Books (https://books.google.com).

בקובץ הקוד, הסקריפט מתחבר ל-Google Books API ומשתמש בכתובת ה-URL על מנת לקבל מידע על הספר (שהוא מופע של המשאב Volume). הסקריפט משתמש במידע הזה כדי ליצור צ'יפ חכם שמציג את שם הספר וכרטיס תצוגה מקדימה שמציג סיכום, מספר הדפים, תמונה של כריכת הספר ומספר הדירוגים.

שירותי Apps Script

התוסף הזה משתמש בשירותים הבאים:

דרישות מוקדמות

כדי להשתמש בדוגמה הזו, נדרשות הדרישות המוקדמות הבאות:

הגדרת הסביבה

פתיחת הפרויקט ב-Cloud במסוף Google Cloud

אם הוא לא פתוח, פותחים את הפרויקט ב-Cloud שבו אתם מתכוונים להשתמש בדוגמה הזו:

  1. נכנסים לדף Select a project במסוף Google Cloud.

    בחירת פרויקט ב-Cloud

  2. בוחרים את הפרויקט ב-Google Cloud שבו רוצים להשתמש. לחלופין, לוחצים על יצירת פרויקט ופועלים לפי ההוראות שבמסך. אם אתם יוצרים פרויקט ב-Google Cloud, ייתכן שאתם צריכים להפעיל את החיוב בפרויקט.

הפעלת Google Books API

התוסף הזה מתחבר ל-Google Books API. כדי להשתמש ב-Google APIs, צריך להפעיל אותם בפרויקט ב-Google Cloud. אפשר להפעיל ממשק API אחד או יותר בפרויקט אחד ב-Google Cloud.

לתוסף הזה נדרש פרויקט ב-Cloud עם מסך הסכמה מוגדר. מסך ההסכמה של OAuth מגדיר את מה ש-Google מציגה למשתמשים, רושם את האפליקציה כך שתוכלו לפרסם אותה מאוחר יותר.

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > מסך ההסכמה של OAuth.

    מעבר למסך ההסכמה של OAuth

  2. בהגדרה סוג משתמש, בוחרים באפשרות פנימי ולוחצים על יצירה.
  3. ממלאים את טופס ההרשמה לאפליקציה ולוחצים על שמירה והמשך.

  4. בינתיים, אפשר לדלג על הוספת היקפים וללחוץ על שמירה והמשך. בעתיד, כשיוצרים אפליקציה לשימוש מחוץ לארגון ב-Google Workspace, צריך לשנות את סוג המשתמש לחיצוני ואז להוסיף את היקפי ההרשאות שנדרשים לאפליקציה.

  5. לבדוק את הסיכום של רישום האפליקציה. כדי לבצע שינויים, לוחצים על עריכה. אם הרישום של האפליקציה נראה בסדר, לוחצים על Back to Dashboard (חזרה למרכז השליטה).

קבלת מפתח API עבור Google Books API

  1. נכנסים למסוף Google Cloud. מוודאים שהפרויקט המופעל על ידי חיוב פתוח.

  2. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  3. לוחצים על Create credentials > API key.

  4. שומרים את מפתח ה-API ועושים בו שימוש בשלב מאוחר יותר.

הגדרת הסקריפט

יצירת פרויקט Apps Script

  1. צריך ללחוץ על הלחצן הבא כדי לפתוח את פרויקט Apps Script של תצוגה מקדימה מ-Google Books.
    פתיחת הפרויקט
  2. לוחצים על סקירה כללית.
  3. בדף הסקירה הכללית, לוחצים על הסמל ליצירת עותק יצירת עותק.
  4. בעותק של פרויקט Apps Script, עוברים לקובץ Code.gs ומחליפים את YOUR_API_KEY במפתח ה-API שיצרתם בקטע הקודם.

העתקת מספר הפרויקט ב-Cloud

  1. במסוף Google Cloud, נכנסים לתפריט > IAM & Admin > הגדרות.

    כניסה לדף IAM & Admin Settings

  2. מעתיקים את הערך בשדה Project number.

הגדרת הפרויקט בענן של פרויקט Apps Script

  1. בפרויקט Apps Script, לוחצים על הסמל של הגדרות הפרויקט Project Settings.
  2. בקטע פרויקט Google Cloud Platform (GCP), לוחצים על שינוי פרויקט.
  3. בקטע מספר פרויקט GCP, מדביקים את מספר הפרויקט ב-Google Cloud.
  4. לוחצים על Set project.

בדיקת התוסף

התקנה של פריסת בדיקה

  1. בפרויקט Apps Script, לוחצים על עריכה.
  2. פותחים את הקובץ Code.gs ולוחצים על הפעלה. כשמתבקשים, מאשרים את הסקריפט.
  3. לוחצים על פריסה > בדיקת פריסות.
  4. לוחצים על התקנה > סיום.
  1. יוצרים מסמך ב-Google Docs בכתובת docs.new.
  2. מדביקים את כתובת ה-URL הבאה במסמך ומקישים על מקש Tab כדי להמיר את כתובת ה-URL לצ'יפ חכם: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
  3. מחזיקים את הסמן מעל הצ'יפ החכם, וכשמוצגת בקשה, מאשרים גישה כדי להפעיל את התוסף. בכרטיס התצוגה המקדימה מוצג מידע על הספר.

התמונה הבאה מציגה את התצוגה המקדימה של הקישור:

תצוגה מקדימה של קישור לספר, Software Engineering ב-Google.

בדיקת הקוד

כדי לבדוק את הקוד של Apps Script של התוסף, לוחצים על הצגת קוד המקור למטה:

הצגת קוד המקור

appsscript.json

solutions/add-on/book-smartchip/appsscript.json
{
  "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
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();
  }
}

השלבים הבאים