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

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

الأهداف

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

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

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

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

آلية العمل

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

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

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

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

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

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

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

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

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

• مشروع على Google Cloud

إعداد البيئة

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

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

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

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

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

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

تفعيل كتب Google API

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

• في مشروعك على السحابة الإلكترونية، فعِّل Books API.

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

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

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

1. في Google API Console، انتقِل إلى "القائمة" menu > منصة Google للمصادقة > العلامة التجارية.

   الانتقال إلى العلامة التجارية

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. في مشروع "برمجة تطبيقات Google"، انقر على code المحرّر.
2. انقر على النشر > عمليات النشر التجريبية.
3. انقر على تثبيت > تم.

معاينة رابط في Google Docs

1. أنشئ مستندًا على Google Docs على 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"
          }
        }
      ]
    }
  }
}

/**
 * Copyright 2025 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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