תצוגה מקדימה של קישורים מ-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 – מתחבר ל-Google Books API כדי לקבל מידע על ספרים (שהם מופעים של המשאב Volume של ממשקי ה-API).
• Card Service – יצירת ממשק המשתמש של התוסף.

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

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

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

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

• פרויקט ב-Google Cloud עם חשבון לחיוב שמשויך אליו. אפשר לעיין במאמר הפעלת החיוב בפרויקט.

הגדרת הסביבה

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

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

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

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

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

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

הפעלת Google Books API

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

• מפעילים את Books API בפרויקט ב-Cloud.

  להפעלת ה-API

הגדרת מסך ההסכמה של OAuth

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

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

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

2. בקטע User type בוחרים באפשרות Internal ולוחצים על Create.
3. ממלאים את טופס הרישום של האפליקציה ולוחצים על שמירה והמשך.

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

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

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

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

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

   כניסה לדף Credentials

3. לוחצים על Create credentials (יצירת פרטי כניסה) > API key (מפתח API).

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

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

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

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

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

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

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

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

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

הגדרת הפרויקט ב-Cloud של פרויקט Apps Script

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

בדיקת התוסף

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

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

1. בפרויקט Apps Script, לוחצים על code עריכה.
2. מחליפים את YOUR_API_KEY במפתח ה-API של Google Books API שנוצר בקטע הקודם.
3. לוחצים על פריסה > בדיקת הפריסות.
4. לוחצים על התקנה > סיום.

הצגת תצוגה מקדימה של קישור ב-Google Docs

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

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

בדיקת הקוד

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

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

נושאים קשורים

• תצוגה מקדימה של קישורים באמצעות צ'יפים חכמים
• מאמרי העזרה של Google Books API