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

پیش نیازها

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

• یک حساب Google (حساب‌های Google Workspace ممکن است به تأیید سرپرست نیاز داشته باشند).

• یک مرورگر وب با دسترسی به اینترنت.

• یک پروژه Google Cloud با یک حساب صورت‌حساب مرتبط. به فعال کردن صورتحساب برای یک پروژه مراجعه کنید.

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

پروژه 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 خود، Books API را روشن کنید.

  API را روشن کنید

صفحه رضایت OAuth را پیکربندی کنید

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

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

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

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

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

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

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

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

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

   به Credentials بروید

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

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

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

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

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

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

1. در کنسول Google Cloud، به menu منو > 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 خود، روی ویرایشگر code کلیک کنید.
2. فایل Code.gs را باز کرده و روی Run کلیک کنید. وقتی از شما خواسته شد، اسکریپت را مجاز کنید.
3. روی Deploy > Test Deployments کلیک کنید.
4. روی Install > Done کلیک کنید.

پیش نمایش یک پیوند در Google Docs

1. یک سند Google Docs در docs.new ایجاد کنید.
2. URL زیر را در سند جای‌گذاری کنید و کلید تب را فشار دهید تا 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