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

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

الأهداف

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

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

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

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

آلية العمل

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

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

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

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

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

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

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

• حساب Google (قد تتطلّب حسابات Google Workspace موافقة المشرف).

• متصفّح ويب يمكنه الوصول إلى الإنترنت

• مشروع Google Cloud مع حساب فوترة مرتبط راجِع مقالة تفعيل الفوترة لمشروع.

إعداد البيئة

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

افتح مشروعك على السحابة الإلكترونية في Google Cloud Console

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

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

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

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

تفعيل Google Books API

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

• في مشروعك على Google Cloud، فعِّل Books API.

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

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

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

1. في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" menu > Google Auth platform > تحديد هوية العلامة التجارية.

   الانتقال إلى "الهوية البصرية للعلامة التجارية"

2. إذا سبق لك ضبط Google Auth platform، يمكنك ضبط إعدادات "شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth" التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك الرسالة Google Auth platform لم يتم ضبطه بعد، انقر على البدء:
1. ضمن معلومات التطبيق، في اسم التطبيق، أدخِل اسمًا للتطبيق.
2. في البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريد إلكتروني للدعم يمكن للمستخدمين التواصل معك من خلاله إذا كانت لديهم أسئلة حول موافقتهم.
3. انقر على التالي.
4. ضمن الجمهور، اختَر داخلي.
5. انقر على التالي.
6. ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني يمكنك تلقّي إشعارات فيه بشأن أي تغييرات تطرأ على مشروعك.
7. انقر على التالي.
8. ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، وإذا كنت توافق عليها، ضَع علامة في المربّع بجانب أوافق على سياسة بيانات المستخدمين في خدمات Google API.
9. انقر على متابعة.
10. انقر على إنشاء.
3. يمكنك حاليًا تخطّي إضافة النطاقات. في المستقبل، عند إنشاء تطبيق لاستخدامه خارج مؤسسة Google Workspace، عليك تغيير نوع المستخدم إلى خارجي. بعد ذلك، أضِف نطاقات التفويض التي يتطلّبها تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على الدليل الكامل حول ضبط موافقة OAuth.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. في مشروع "برمجة تطبيقات Google"، انقر على code المحرّر.
2. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الخاص بواجهة Google Books API الذي تم إنشاؤه في قسم سابق.
3. انقر على نشر > اختبار عمليات النشر.
4. انقر على تثبيت > تم.

معاينة رابط في "مستندات Google"

1. أنشئ مستندًا على "مستندات Google" من خلال الرابط 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