معاينة الروابط من "كتب Google" باستخدام الشرائح الذكية

مستوى الترميز: متوسط
المدة: 30 دقيقة
نوع المشروع: إضافة Google Workspace

الأهداف

  • فهم وظيفة الإضافة
  • فهم كيفية إنشاء إضافة باستخدام "برمجة تطبيقات Google"، ومعرفة ما تفعله خدمات "برمجة تطبيقات Google"
  • اضبط إعدادات البيئة.
  • إعداد النص البرمجي
  • شغِّل النص البرمجي.

لمحة عن إضافة Google Workspace هذه

في هذا المثال، يمكنك إنشاء إضافة Google Workspace تعمل على معاينة الروابط من كتب Google في مستند "مستندات Google". عند كتابة عنوان URL في "كتب Google" أو لصقه في أحد المستندات، تتعرّف الإضافة على الرابط وتشغّل ميزة معاينة الرابط. لمعاينة الرابط، يمكنك تحويله إلى شريحة ذكية مع الاستمرار في وضع المؤشر فوق الرابط لعرض بطاقة تعرض مزيدًا من المعلومات عن الكتاب.

تستخدِم هذه الإضافة خدمة UrlFetch في Apps Script لربط Google Books API والحصول على معلومات عن "كتب Google" لعرضها في "مستندات Google".

آلية العمل

في ملف بيان الإضافة الخاصة بخدمة Google Workspace، يضبط النص البرمجي الإضافة لتوسيع نطاق "مستندات Google" وتشغيل معاينات الروابط لعناوين URL التي تتطابق مع أنماط معيّنة من موقع "كتب Google" الإلكتروني (https://books.google.com).

في ملف الرموز البرمجية، يتصل النص البرمجي بواجهة برمجة التطبيقات Google Books API ويستخدم عنوان URL للحصول على معلومات عن الكتاب (الذي يمثّل مثيلًا Volume للمورد). يستخدم النص البرمجي هذه المعلومات لإنشاء شريحة ذكية تعرِض عنوان الكتاب وبطاقة معاينة تعرِض ملخّصًا وعدد الصفحات وصورة لغلاف الكتاب وعدد التقييمات.

خدمات "برمجة تطبيقات Google"

تستخدِم هذه الإضافة الخدمات التالية:

  • خدمة UrlFetch: تتصل بواجهة برمجة تطبيقات "كتب Google" للحصول على معلومات عن الكتب (التي هي نُسخ من موارد واجهة برمجة التطبيقات Volume).
  • خدمة البطاقات: لإنشاء واجهة مستخدم الإضافة.

المتطلبات الأساسية

لاستخدام هذا العيّنة، يجب استيفاء المتطلبات الأساسية التالية:

إعداد البيئة

تهدف الأقسام التالية إلى إعداد بيئة إنشاء الإضافة.

فتح مشروعك على Cloud في Google Cloud Console

افتح مشروع Cloud الذي تريد استخدامه لهذه العيّنة إذا لم يكن مفتوحًا من قبل:

  1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة اختيار مشروع.

    اختيار مشروع على السحابة الإلكترونية

  2. اختَر مشروع Google Cloud الذي تريد استخدامه. أو انقر على إنشاء مشروع واتّبِع التعليمات الظاهرة على الشاشة. في حال إنشاء مشروع على Google Cloud، قد تحتاج إلى تفعيل الفوترة للمشروع.

تفعيل Google Books API

تتصل هذه الإضافة بواجهة برمجة التطبيقات Google Books API. قبل استخدام واجهات برمجة تطبيقات Google، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيقات واحدة أو أكثر في مشروع واحد على Google Cloud.

تتطلّب هذه الإضافة مشروعًا على Cloud يتضمّن شاشة موافقة تم ضبطها. من خلال ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth، يمكنك تحديد ما يلي: المحتوى الذي تعرضه Google للمستخدمين وتسجيل تطبيقك كي تتمكّن من نشره لاحقًا.

  1. في وحدة تحكّم Google Cloud، انتقِل إلى رمز القائمة > APIs & Services (واجهات برمجة التطبيقات والخدمات) > OAuth consent screen (شاشة موافقة OAuth).

    الانتقال إلى شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

  2. في حقل نوع المستخدم، اختَر داخلي، ثم انقر على إنشاء.
  3. املأ نموذج تسجيل التطبيق، ثم انقر على حفظ ومتابعة.

  4. في الوقت الحالي، يمكنك تخطّي إضافة النطاقات والنقر على حفظ ومتابعة. في المستقبل، عند إنشاء تطبيق لاستخدامه خارج مؤسستك على Google Workspace، عليك تغيير نوع المستخدم إلى خارجي، ثم إضافة نطاقات التفويض التي يتطلبها تطبيقك.

  5. راجِع ملخّص تسجيل تطبيقك. لإجراء تغييرات، انقر على تعديل. إذا كان تسجيل التطبيق يبدو جيدًا، انقر على الرجوع إلى لوحة البيانات.

الحصول على مفتاح واجهة برمجة تطبيقات لخدمة Google Books API

  1. انتقِل إلى Google Cloud Console. تأكَّد من أنّ مشروعك المفعَّل فيه خيار الفوترة مفتوح.

  2. في وحدة تحكّم Google Cloud، انتقِل إلى رمز القائمة > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

    الانتقال إلى "بيانات الاعتماد"

  3. انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.

  4. سجِّل مفتاح واجهة برمجة التطبيقات لاستخدامه في خطوة لاحقة.

إعداد النص البرمجي

تحدِّد الأقسام التالية النص البرمجي لإنشاء الإضافة.

إنشاء مشروع "برمجة تطبيقات Google"

  1. انقر على الزر التالي لفتح مشروع معاينة الروابط من "كتب Google" في Apps Script.
    فتح المشروع
  2. انقر على نظرة عامة.
  3. في صفحة النظرة العامة، انقر على رمز لإنشاء نسخة إنشاء نسخة.
  4. في نسختك من مشروع Apps Script، انتقِل إلى ملف Code.gs واستبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الذي أنشأته في القسم السابق.

نسخ رقم مشروع Cloud

  1. في Google Cloud Console، انتقِل إلى القائمة > إدارة الهوية وإمكانية الوصول (IAM) والمشرف > الإعدادات.

    الانتقال إلى "إدارة الهوية وإمكانية الوصول" و"إعدادات المشرف"

  2. في حقل رقم المشروع، انسخ القيمة.

ضبط مشروع Cloud لمشروع "برمجة التطبيقات"

  1. في مشروعك على Apps Script، انقر على رمز إعدادات المشروع إعدادات المشروع.
  2. ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.
  3. في حقل رقم مشروع Google Cloud Platform، الصِق رقم مشروع Google Cloud.
  4. انقر على ضبط المشروع.

اختبار الإضافة

تختبر الأقسام التالية الإضافة التي أنشأتها.

تثبيت عملية نشر تجريبية

  1. في مشروعك على Apps Script، انقر على المحرِّر.
  2. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة تطبيقات Google Books API الذي تم إنشاؤه في القسم السابق.
  3. انقر على نشر > اختبار عمليات النشر.
  4. انقر على تثبيت > تم.
  1. أنشئ مستندًا في "مستندات Google" على الرابط 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();
  }
}