معاينة الروابط من "كتب 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) ). تشير رسالة الأشكال البيانية يستخدم النص البرمجي هذه المعلومات لإنشاء شريحة ذكية تعرض محتوى الكتاب عنوان وبطاقة معاينة تعرض ملخصًا وعدد الصفحات وصورة وغلاف الكتاب وعدد التقييمات.

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

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

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

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

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

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

• متصفح ويب متصل بالإنترنت.

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

إعداد البيئة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. في مشروع "برمجة تطبيقات Google"، النقر على إعدادات المشروع:
2. ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.
3. في رقم مشروع Google Cloud Platform، الصِق رقم مشروع 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. ضَع المؤشر فوق الشريحة الذكية، ومنح إذن الوصول إلى البيانات عندما يُطلب منك ذلك. لتنفيذ الوظيفة الإضافية. يتم عرض بطاقة المعاينة المعلومات حول الكتاب.

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

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

لمراجعة رمز "برمجة تطبيقات Google" لهذا الغرض انقر على عرض رمز المصدر لتوسيع :

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