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

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

מטרות

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

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

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

התוסף הזה משתמש שירות UrlFetch של 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

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

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

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

הגדרת הסביבה

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

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

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

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

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

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

הפעלת Google Books API

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

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

  1. במסוף Google Cloud, נכנסים לתפריט > ממשקי API ו- Services (שירותים) > מסך ההסכמה של OAuth.

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

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

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

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

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

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

  2. במסוף Google Cloud, נכנסים לתפריט > ממשקי API ו- Services (שירותים) > פרטי כניסה.

    כניסה לדף Credentials

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

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

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

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

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

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

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

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

    כניסה לדף IAM & הגדרות אדמין

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

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

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

בדיקת התוסף

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

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

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

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

תצוגה מקדימה עם קישור לספר, 'הנדסת תוכנה' ב-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();
  }
}