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

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

מטרות

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

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

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

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

איך זה עובד

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

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

שירותי Apps Script

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

  • ‫UrlFetch Service – מתחבר ל-Google Books API כדי לקבל מידע על ספרים (שהם מופעים של Volume resource של ממשקי ה-API).
  • Card Service – יוצר את ממשק המשתמש של התוסף.

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

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

  • חשבון Google (יכול להיות שחשבונות Google Workspace ידרשו אישור אדמין).

  • דפדפן אינטרנט עם גישה לאינטרנט.

  • פרויקט ב-Google Cloud.

הגדרת הסביבה

בקטעים הבאים מוסבר איך להגדיר את הסביבה כדי ליצור את התוסף.

פותחים את פרויקט בענן במסוף Google Cloud

אם הוא לא פתוח, פותחים את פרויקט בענן שבו רוצים להשתמש בדוגמה הזו:

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

    בוחרים פרויקט בענן

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

הפעלת Google Books API

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

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

  1. ב-Google API Console, עוברים אל תפריט > פלטפורמת אימות של Google > מיתוג.

    מעבר לדף Branding

  2. אם כבר הגדרתם את פלטפורמת אימות Google, אתם יכולים לקבוע את ההגדרות הבאות של מסך ההסכמה ל-OAuth בקטעים Branding,‏ Audience וData Access. אם מופיעה ההודעה Google Auth platform not configured yet, לוחצים על Get Started:
    1. בקטע App Information בשדה App name, מזינים שם לאפליקציה.
    2. בקטע User support email, בוחרים כתובת אימייל לתמיכה שאליה משתמשים יפנו אם יש להם שאלות לגבי ההסכמה שלהם.
    3. לוחצים על Next.
    4. בקטע Audience, לוחצים על Internal.
    5. לוחצים על Next.
    6. בקטע Contact Information, מזינים כתובת אימייל שאליה אפשר לשלוח התראות על שינויים בפרויקט.
    7. לוחצים על Next.
    8. בקטע Finish, קוראים את המדיניות של Google בנושא נתוני משתמשים בשירותי API. אם אתם מסכימים, סמנו את התיבה I agree to the Google API Services: User Data Policy.
    9. לוחצים על Continue.
    10. לוחצים על Create.
  3. כרגע אתם יכולים לדלג על הוספת היקפי הרשאות. בעתיד, כשתיצרו אפליקציה לשימוש מחוץ לארגון שלכם ב-Google Workspace, תצטרכו לשנות את סוג המשתמש ל-External. לאחר מכן מוסיפים את היקפי ההרשאות שהאפליקציה דורשת. למידע נוסף, אפשר לעיין במדריך המלא בנושא הגדרת הסכמה ל-OAuth.

קבלת מפתח API ל-Google Books API

  1. עוברים אל Google API Console. מוודאים שהפרויקט שמוגדר בו חיוב פתוח.

  2. במסוף Google API, נכנסים לתפריט > 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 שיצרתם בקטע הקודם.

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

בדיקת התוסף

בקטעים הבאים נבדוק את התוסף שיצרתם.

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

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

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

תצוגה מקדימה של הקישור לספר Software Engineering at 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
/**
 * Copyright 2025 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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