پیش نمایش پیوندها از Google Books با تراشه های هوشمند

سطح کدنویسی : متوسط
مدت زمان : 30 دقیقه
نوع پروژه : افزونه Google Workspace

اهداف

  • درک کنید که افزونه چه کاری انجام می دهد.
  • نحوه ساخت افزونه با استفاده از Apps Script را بدانید و بدانید که خدمات Apps Script چه کاری انجام می دهند.
  • محیط خود را تنظیم کنید.
  • اسکریپت را تنظیم کنید
  • اسکریپت را اجرا کنید.

درباره این افزونه Google Workspace

در این نمونه، یک افزونه Google Workspace ایجاد می‌کنید که پیوندهای Google Books را در سند Google Docs پیش‌نمایش می‌کند. وقتی URL کتاب‌های Google را تایپ می‌کنید یا در سندی جای‌گذاری می‌کنید، افزونه پیوند را می‌شناسد و پیش‌نمایش پیوند را راه‌اندازی می‌کند. برای پیش نمایش پیوند، می توانید پیوند را به یک تراشه هوشمند تبدیل کنید و نشانگر را روی پیوند نگه دارید تا کارتی را مشاهده کنید که اطلاعات بیشتری درباره کتاب نمایش می دهد.

این افزونه از سرویس 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 است) استفاده می‌کند. این اسکریپت از این اطلاعات برای تولید یک تراشه هوشمند استفاده می کند که عنوان کتاب را نمایش می دهد و یک کارت پیش نمایش که خلاصه، تعداد صفحات، تصویر جلد کتاب و تعداد رتبه بندی ها را نمایش می دهد.

خدمات اسکریپت برنامه ها

این افزونه از خدمات زیر استفاده می کند:

  • سرویس UrlFetch – برای دریافت اطلاعات درباره کتاب‌ها (که نمونه‌هایی از منبع Volume API هستند) به Google Books API متصل می‌شود.
  • خدمات کارت - رابط کاربری افزونه را ایجاد می کند.

پیش نیازها

برای استفاده از این نمونه به پیش نیازهای زیر نیاز دارید:

محیط خود را تنظیم کنید

بخش های زیر محیط شما را برای ساختن افزونه تنظیم می کند.

پروژه Cloud خود را در کنسول Google Cloud باز کنید

اگر قبلاً باز نشده است، پروژه Cloud را که می‌خواهید برای این نمونه استفاده کنید باز کنید:

  1. در کنسول Google Cloud، به صفحه انتخاب پروژه بروید.

    یک پروژه Cloud را انتخاب کنید

  2. پروژه Google Cloud را که می خواهید استفاده کنید انتخاب کنید. یا روی ایجاد پروژه کلیک کنید و دستورالعمل های روی صفحه را دنبال کنید. اگر یک پروژه Google Cloud ایجاد می‌کنید، ممکن است لازم باشد صورت‌حساب پروژه را روشن کنید .

Google Books API را روشن کنید

این افزونه به Google Books API متصل می شود. قبل از استفاده از Google API، باید آنها را در پروژه Google Cloud روشن کنید. می‌توانید یک یا چند API را در یک پروژه Google Cloud روشن کنید.

این افزونه به یک پروژه Cloud با صفحه رضایت پیکربندی شده نیاز دارد. پیکربندی صفحه رضایت OAuth مشخص می کند که Google چه چیزی را برای کاربران نمایش می دهد و برنامه شما را ثبت می کند تا بتوانید بعداً آن را منتشر کنید.

  1. در کنسول Google Cloud، به منو > APIs & Services > صفحه رضایت OAuth بروید.

    به صفحه رضایت OAuth بروید

  2. برای نوع User Internal را انتخاب کنید، سپس روی Create کلیک کنید.
  3. فرم ثبت نام برنامه را تکمیل کنید، سپس روی ذخیره و ادامه کلیک کنید.

  4. در حال حاضر، می‌توانید از افزودن دامنه‌ها صرفنظر کنید و روی ذخیره و ادامه کلیک کنید. در آینده، وقتی برنامه‌ای را برای استفاده خارج از سازمان Google Workspace خود ایجاد می‌کنید، باید نوع کاربر را به خارجی تغییر دهید و سپس محدوده‌های مجوز مورد نیاز برنامه خود را اضافه کنید.

  5. خلاصه ثبت برنامه خود را مرور کنید. برای ایجاد تغییرات، روی ویرایش کلیک کنید. اگر ثبت برنامه خوب به نظر می رسد، روی بازگشت به داشبورد کلیک کنید.

یک کلید API برای Google Books API دریافت کنید

  1. به کنسول Google Cloud بروید. مطمئن شوید پروژه دارای صورتحساب شما باز است.

  2. در کنسول Google Cloud، به منو > APIs & Services > Credentials بروید.

    به Credentials بروید

  3. روی ایجاد اعتبارنامه > کلید API کلیک کنید.

  4. کلید API خود را برای استفاده در مرحله بعد یادداشت کنید.

اسکریپت را تنظیم کنید

بخش‌های زیر اسکریپت را برای ساخت افزونه تنظیم می‌کنند.

پروژه Apps Script را ایجاد کنید

  1. روی دکمه زیر کلیک کنید تا پیوندهای پیش‌نمایش از پروژه Google Books Apps Script باز شود.
    پروژه را باز کنید
  2. روی نمای کلی کلیک کنید.
  3. در صفحه نمای کلی، کلیک کنید نماد ایجاد یک کپی یک کپی تهیه کنید .
  4. در کپی پروژه Apps Script، به فایل Code.gs بروید و کلید API را که در بخش قبلی ایجاد کردید جایگزین YOUR_API_KEY کنید.

شماره پروژه Cloud را کپی کنید

  1. در کنسول Google Cloud، به منو > IAM & Admin > تنظیمات بروید.

    به تنظیمات IAM و Admin بروید

  2. در قسمت Project number مقدار را کپی کنید.

پروژه Cloud پروژه Apps Script را تنظیم کنید

  1. در پروژه Apps Script خود، کلیک کنید نماد تنظیمات پروژه تنظیمات پروژه
  2. در پروژه Google Cloud Platform (GCP) ، روی تغییر پروژه کلیک کنید.
  3. در شماره پروژه GCP ، شماره پروژه Google Cloud را جای‌گذاری کنید.
  4. روی تنظیم پروژه کلیک کنید.

افزونه را تست کنید

بخش‌های زیر افزونه‌ای را که ایجاد کرده‌اید آزمایش می‌کنند.

یک برنامه آزمایشی نصب کنید

  1. در پروژه Apps Script خود، روی ویرایشگر کلیک کنید.
  2. YOUR_API_KEY با کلید API برای Google Books API که در بخش قبلی ایجاد شده است، جایگزین کنید.
  3. روی Deploy > Test Deployments کلیک کنید.
  4. روی Install > Done کلیک کنید.
  1. یک سند Google Docs در docs.new ایجاد کنید.
  2. URL زیر را در سند جای‌گذاری کنید و کلید تب را فشار دهید تا URL به یک تراشه هوشمند تبدیل شود: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
  3. نشانگر را روی تراشه هوشمند نگه دارید و هنگامی که از شما خواسته شد، اجازه دسترسی برای اجرای افزونه را بدهید. کارت پیش نمایش اطلاعات کتاب را نمایش می دهد.

تصویر زیر پیش نمایش لینک را نشان می دهد:

پیش نمایش لینک کتاب مهندسی نرم افزار در گوگل.

کد را مرور کنید

برای بازبینی کد 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();
  }
}