תצוגה מקדימה של קישורים מ-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).
• ‫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 API, אם צריכים להפעיל אותם בפרויקט ב-Google Cloud. בכל פרויקט אפשר להפעיל ממשק API אחד או יותר.

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

  הפעלת ה-API

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

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

1. במסוף Google Cloud, עוברים אל תפריט menu > Google Auth platform > Branding.

   מעבר לדף Branding

2. אם כבר הגדרתם את Google Auth platform, אתם יכולים לקבוע את ההגדרות הבאות של מסך ההסכמה ל-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 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. מעתיקים את הערך בשדה מספר הפרויקט.

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

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

בדיקת התוסף

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

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

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