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

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

الأهداف

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

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

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

تستخدم هذه الإضافة خدمة UrlFetch لبرمجة التطبيقات للاتصال بواجهة برمجة تطبيقات "كتب 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 في Google Cloud Console

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ضبط مشروع السحابة الإلكترونية لمشروع برمجة التطبيقات

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

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

تثبيت نشر تجريبي

1. في مشروع "برمجة تطبيقات Google"، انقر على محرِّر.
2. افتح ملف Code.gs وانقر على Run (تشغيل). امنح الإذن للنص البرمجي عندما يُطلب منك ذلك.
3. انقر على نشر > اختبار عمليات النشر.
4. انقر على تثبيت > تم.

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

1. أنشئ مستندًا في "مستندات Google" على docs.new.
2. الصِق عنوان URL التالي في المستند، واضغط على مفتاح Tab لتحويل عنوان URL إلى شريحة ذكية: https://www.google.com/books/edition/Software_Engineering_at_Google/V3TTDwAAQBAJ
3. اضغط مع الاستمرار على مؤشر الماوس فوق الشريحة الذكية، ثم امنح الإذن بالوصول لتنفيذ الإضافة عندما يُطلب منك ذلك. تعرض بطاقة المعاينة معلومات حول الكتاب.

تعرض الصورة التالية معاينة الرابط:

مراجعة الرمز

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

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

appsscript.json

solutions/add-on/book-smartchip/appsscript.json

العرض على GitHub

{
  "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

العرض على GitHub

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"