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

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

الأهداف

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

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

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

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

طريقة العمل

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

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

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

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

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

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

لاستخدام هذا النموذج، تحتاج إلى المتطلبات الأساسية التالية:

إعداد البيئة

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

فتح مشروعك على Google Cloud في "وحدة تحكُّم Google Cloud"

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

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

    اختيار مشروع على Google Cloud

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

تفعيل واجهة برمجة تطبيقات "كتب Google"

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

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

  1. في Google Cloud Console، انتقِل إلى القائمة > واجهات برمجة التطبيقات والخدمات > شاشة موافقة OAuth.

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

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

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

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

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

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

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

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

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

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

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

تقوم الأقسام التالية بإعداد النص البرمجي لإنشاء الوظيفة الإضافية.

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

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

نسخ رقم المشروع على Google Cloud

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

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

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

إعداد مشروع "برمجة تطبيقات Google" على السحابة الإلكترونية

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

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

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

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

  1. في مشروع "برمجة تطبيقات Google"، انقر على محرِّر.
  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

مراجعة الرمز البرمجي

لمراجعة رمز برمجة التطبيقات لهذه الإضافة، انقر على عرض رمز المصدر لتوسيع القسم:

عرض رمز المصدر

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();
  }
}