תצוגה מקדימה של קישורים מ-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 ממשקי ה-API).
• שירות כרטיסים – יצירת ממשק המשתמש של התוסף.

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

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

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

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

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

הגדרת הסביבה

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

פתיחת הפרויקט ב-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, מפעילים את Books API.

  הפעלת ה-API

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

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

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

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

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

4. בשלב הזה אפשר לדלג על הוספת היקפי הרשאות וללחוץ על שמירה והמשך. בעתיד, כשתיצרו אפליקציה לשימוש מחוץ לארגון ב-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.

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

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

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

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

1. לוחצים על הלחצן הבא כדי לפתוח את פרויקט Apps Script של תצוגה מקדימה של קישורים מ-Google Books.
   פתיחת הפרויקט
2. לוחצים על info_outline סקירה כללית.
3. בדף הסקירה הכללית לוחצים על יצירת עותק.
4. בעותק של פרויקט Apps Script, עוברים לקובץ Code.gs ומחליפים את 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, מדביקים את מספר הפרויקט ב-Google Cloud.
4. לוחצים על Set project (הגדרת פרויקט).

בדיקת התוסף

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

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

1. בפרויקט Apps Script, לוחצים על code Editor.
2. מחליפים את YOUR_API_KEY במפתח ה-API של Google Books API שנוצר בקטע הקודם.
3. לוחצים על Deploy (פריסה) > Test installations (בדיקת פריסות).
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 של התוסף הזה, לוחצים על View source code כדי להרחיב את הקטע:

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