دمج Google Picker في تطبيقات الويب

مربّع حوار Google Picker يوضّح هذا المستند كيفية دمج Google Picker في تطبيقات الويب باستخدام Google Picker API.

‫Google Picker API هي واجهة برمجة تطبيقات JavaScript يمكنك تنفيذها للسماح للمستخدمين باختيار ملفات Google Drive أو تحميلها باستخدام Google Picker. يمكن للمستخدمين منح الإذن لتطبيقاتك بالوصول إلى بياناتهم على Drive، ما يوفّر طريقة آمنة ومصرَّح بها للتفاعل مع ملفاتهم.

الميزات

يتضمّن "أداة اختيار Google" عدة ميزات:

  • مظهر مشابه لواجهة مستخدم Google Drive
  • عدّة طرق عرض تعرض معاينات وصورًا مصغّرة لملفات Drive
  • طرق عرض تمت فلترتها مسبقًا ولا تعرض سوى أنواع ملفات معيّنة (مثل ملفات PDF أو الصور) أو مجلدات معيّنة
  • نافذة مضمّنة مشروطة، حتى لا يغادر المستخدمون التطبيق الرئيسي أبدًا

يُرجى العِلم أنّه على الرغم من إمكانية اختيار الملفات وتحميلها باستخدام Google Picker، لا يتيح هذا التطبيق للمستخدمين تنظيم الملفات أو نقلها أو نسخها من مجلد إلى آخر. لإدارة الملفات، يجب استخدام Google Drive API أو واجهة مستخدم Drive.

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

يجب أن تلتزم التطبيقات التي تستخدم Google Picker بجميع بنود الخدمة الحالية، والأهم من ذلك، يجب أن تحدّد هويتك بشكل صحيح في طلباتك.

يجب أن يكون لديك أيضًا مشروع على السحابة الإلكترونية من Google Cloud.

إعداد البيئة

لبدء استخدام Google Picker API، عليك إعداد بيئتك.

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

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

إنشاء مفتاح واجهة برمجة تطبيقات

مفتاح واجهة برمجة التطبيقات هو سلسلة طويلة تحتوي على أحرف كبيرة وصغيرة وأرقام وشرطات سفلية وشرطات، مثل AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. تُستخدم طريقة المصادقة هذه للوصول بشكل مجهول إلى البيانات المتاحة للجميع، مثل ملفات Google Workspace التي تتم مشاركتها باستخدام إعداد المشاركة "يمكن لأي مستخدم على الإنترنت لديه هذا الرابط الوصول إلى الملف". لمزيد من التفاصيل، اطّلِع على إدارة مفاتيح واجهة برمجة التطبيقات.

لإنشاء مفتاح واجهة برمجة تطبيقات، اتّبِع الخطوات التالية:

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

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

  2. انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
  3. يظهر مفتاح واجهة برمجة التطبيقات الجديد.
    • انقر على "نسخ" لنسخ مفتاح واجهة برمجة التطبيقات واستخدامه في رمز تطبيقك. يمكن العثور على مفتاح واجهة برمجة التطبيقات أيضًا في قسم "مفاتيح واجهة برمجة التطبيقات" ضمن بيانات اعتماد مشروعك.
    • لمنع الاستخدام غير المصرّح به، ننصحك بفرض قيود على الأماكن التي يمكن فيها استخدام مفتاح واجهة برمجة التطبيقات والواجهات التي يمكن استخدامه معها. لمزيد من التفاصيل، اطّلِع على إضافة قيود على واجهة برمجة التطبيقات.

منح الإذن باستخدام بيانات الاعتماد لتطبيق ويب

لمصادقة المستخدمين النهائيين والوصول إلى بيانات المستخدمين في تطبيقك، عليك إنشاء معرّف عميل واحد أو أكثر من معرّفات عملاء OAuth 2.0. يُستخدم معرّف العميل لتعريف تطبيق واحد على خوادم OAuth من Google. إذا كان تطبيقك يعمل على منصات متعددة، عليك إنشاء معرّف عميل منفصل لكل منصة.
  1. في Google API Console، انتقِل إلى "القائمة" > منصة Google Auth > العملاء.

    الانتقال إلى "العملاء"

  2. انقر على إنشاء عميل.
  3. انقر على نوع التطبيق > تطبيق الويب.
  4. في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في Google API Console.
  5. أضِف معرّفات الموارد المنتظمة (URI) المعتمَدة ذات الصلة بتطبيقك:
    • التطبيقات من جهة العميل (JavaScript): ضمن مصادر JavaScript المسموح بها، انقر على إضافة معرّف الموارد المنتظم (URI)، ثم أدخِل معرّف موارد منتظم (URI) لاستخدامه في طلبات المتصفّح. يحدّد هذا المعرّف النطاقات التي يمكن لتطبيقك إرسال طلبات واجهة برمجة التطبيقات منها إلى خادم OAuth 2.0.
    • التطبيقات من جهة الخادم (Java وPython وغير ذلك): ضمن معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه، انقر على إضافة معرّف الموارد المنتظمة (URI)، ثم أدخِل معرّف الموارد المنتظمة (URI) لنقطة النهاية التي يمكن لخادم OAuth 2.0 إرسال الردود إليها.
  6. انقر على إنشاء.

    تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرّفات عميل OAuth 2.0.

    دوِّن معرّف العميل، لأنّ الرموز السرية للعميل لا تُستخدَم لتطبيقات الويب.

ملاحظة مُهمّة: يجب أن يرسل تطبيقك رمز دخول OAuth 2.0 مع طرق العرض التي تصل إلى بيانات المستخدم الخاصة عند إنشاء عنصر Picker. لطلب رمز مميز للوصول، يُرجى الاطّلاع على استخدام بروتوكول OAuth 2.0 للدخول إلى Google APIs.

إدارة Google Picker

يتناول الجزء المتبقي من هذا المستند كيفية تحميل أداة اختيار الملفات من Google وعرضها من تطبيق ويب، بالإضافة إلى تنفيذ وظيفة معاودة الاتصال. للاطّلاع على عينة التعليمات البرمجية الكاملة، يُرجى الانتقال إلى استخدام ميزات Google Picker API في تطبيقات الويب.

تحميل مكتبة Google Picker

لتحميل مكتبة Google Picker، استدعِ الدالة gapi.load مع اسم المكتبة ودالة ردّ الاتصال التي سيتم استدعاؤها بعد اكتمال التحميل بنجاح:

    <script>
      let tokenClient;
      let accessToken = null;
      let pickerInited = false;
      let gisInited = false;

      // Use the API Loader script to load google.picker.
      function onApiLoad() {
        gapi.load('picker', onPickerApiLoad);
      }

      function onPickerApiLoad() {
        pickerInited = true;
      }

      function gisLoaded() {
        // Replace with your client ID and required scopes.
        tokenClient = google.accounts.oauth2.initTokenClient({
          client_id: 'CLIENT_ID',
          scope: 'SCOPES',
          callback: '', // defined later
        });
        gisInited = true;
    }
    </script>
    <!-- Load the Google API Loader script. -->
    <script async defer src="https://apis.google.com/js/api.js" onload="onApiLoad()"></script>
    <script async defer src="https://accounts.google.com/gsi/client" onload="gisLoaded()"></script>

غيِّر القيم في السلسلة على الشكل التالي:

  • CLIENT_ID: رقم تعريف العميل لتطبيقك المستنِد إلى الويب.
  • SCOPES: نطاق واحد أو أكثر من نطاقات OAuth 2.0 التي عليك طلبها للوصول إلى Google APIs، وذلك حسب مستوى الوصول الذي تحتاجه. لمزيد من المعلومات، يُرجى الاطّلاع على نطاقات OAuth 2.0 لواجهات Google APIs.

تساعدك مكتبة JavaScript google.accounts.oauth2 في طلب موافقة المستخدم والحصول على رمز مميّز للوصول إلى بيانات المستخدم. تُنشئ طريقة initTokenClient عميل رمز مميّز جديدًا باستخدام معرّف عميل تطبيق الويب. لمزيد من المعلومات، راجِع استخدام نموذج الرموز المميزة.

تحمّل الدالة onApiLoad مكتبات Google Picker. يتم استدعاء دالة ردّ الاتصال onPickerApiLoad بعد تحميل مكتبة Google Picker بنجاح.

ملاحظة: إذا كنت تستخدم TypeScript، يمكنك تثبيت @types/google.picker لاستخدام window.google.picker. للإبلاغ عن مشكلة في هذه الأنواع، يمكنك فتح بطاقة دعم.

عرض Google Picker

لإنشاء مثيل Google Picker، يجب إنشاء عنصر Picker باستخدام PickerBuilder. يأخذ PickerBuilder View ورمز OAuth 2.0 المميز ومفتاح المطوّر ودالّة رد الاتصال التي يتم استدعاؤها عند النجاح (pickerCallback).

تضمن الدالة createPicker انتهاء تحميل Google Picker API وإنشاء رمز مميز OAuth 2.0. استخدِم الطريقة PickerBuilder.setAppId لضبط معرّف تطبيق Drive باستخدام رقم مشروع على السحابة الإلكترونية للسماح للتطبيق بالوصول إلى ملفات المستخدم. تنشئ هذه الدالة بعد ذلك مثيلاً من Google Picker وتعرضه:

    // Create and render a Google Picker object for selecting from Drive.
    function createPicker() {
      const showPicker = () => {
        // Replace with your API key and App ID.
        const picker = new google.picker.PickerBuilder()
            .addView(google.picker.ViewId.DOCS)
            .setOAuthToken(accessToken)
            .setDeveloperKey('API_KEY')
            .setCallback(pickerCallback)
            .setAppId('APP_ID')
            .build();
        picker.setVisible(true);
      }

      // Request an access token.
      tokenClient.callback = async (response) => {
        if (response.error !== undefined) {
          throw (response);
        }
        accessToken = response.access_token;
        showPicker();
      };

      if (accessToken === null) {
        // Prompt the user to select a Google Account and ask for consent to share their data
        // when establishing a new session.
        tokenClient.requestAccessToken({prompt: 'consent'});
      } else {
        // Skip display of account chooser and consent dialog for an existing session.
        tokenClient.requestAccessToken({prompt: ''});
      }
    }

غيِّر القيم في السلسلة على الشكل التالي:

  • استبدِل API_KEY بمفتاح واجهة برمجة التطبيقات.
  • ‫APP_ID: رقم مشروع على السحابة الإلكترونية.

يعرض العنصر Picker عنصر View واحدًا في كل مرة. حدِّد طريقة عرض واحدة على الأقل، إما باستخدام ViewId (google.picker.ViewId.*) أو عن طريق إنشاء مثيل من DocsView للتحكّم بشكل إضافي في طريقة عرض العرض.

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

للاطّلاع على قائمة بالعروض الصالحة، راجِع ViewId في مرجع Google Picker. للحصول على الرمز المميّز لأي من طرق العرض هذه، استخدِم النطاق https://www.googleapis.com/auth/drive.file.

تنفيذ وظيفة استدعاء Google Picker

يمكن استخدام دالة ردّ الاتصال في Google Picker للردّ على تفاعلات المستخدمين في Google Picker، مثل اختيار ملف أو النقر على "إلغاء". تعرض واجهة ResponseObject معلومات حول اختيارات المستخدم.

    // A callback implementation.
    function pickerCallback(data) {
      let url = 'nothing';
      if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
        const doc = data[google.picker.Response.DOCUMENTS][0];
        url = doc[google.picker.Document.URL];
      }
      const message = `You picked: ${url}`;
      document.getElementById('result').textContent = message;
    }

يتلقّى برنامج معالجة البيانات ردّ الاتصال كائن بيانات مشفّر بتنسيق JSON. يحتوي هذا الكائن على action ينفّذه المستخدم باستخدام Google Picker (google.picker.Response.ACTION). إذا اختار المستخدم عنصرًا، سيتم أيضًا ملء مصفوفة docs. في هذا المثال، يتم عرض google.picker.Document.URL على الصفحة الرئيسية. للاطّلاع على تفاصيل حول جميع الخصائص، راجِع واجهة ResponseObject.

فلترة أنواع ملفات معيّنة

استخدِم ViewGroup كطريقة لفلترة عناصر معيّنة. يوضّح نموذج الرمز البرمجي التالي كيف تعرض طريقة العرض الفرعية "Drive" المستندات والعروض التقديمية فقط.

    const picker = new google.picker.PickerBuilder()
        .addViewGroup(
          new google.picker.ViewGroup(google.picker.ViewId.DOCS)
              .addView(google.picker.ViewId.DOCUMENTS)
              .addView(google.picker.ViewId.PRESENTATIONS))
        .setOAuthToken(oauthToken)
        .setDeveloperKey(developerKey)
        .setAppId(cloudProjectNumber)
        .setCallback(pickerCallback)
        .build();

للاطّلاع على قائمة بأنواع العرض الصالحة، يُرجى الرجوع إلى ViewId. يمكن أيضًا استخدام العنصر DocsView لخيارات فلترة إضافية.

ضبط مظهر "أداة اختيار Google"

يمكنك استخدام العنصر Feature لتفعيل الميزات أو إيقافها في طرق عرض مختلفة. لضبط مظهر نافذة Google Picker بدقة، استخدِم الطريقة PickerBuilder.enableFeature أو PickerBuilder.disableFeature. على سبيل المثال، إذا كان لديك ملف شخصي واحد فقط، قد تحتاج إلى إخفاء لوحة التنقّل (Feature.NAV_HIDDEN) لمنح المستخدمين مساحة أكبر للاطّلاع على العناصر.

تعرض عينة التعليمات البرمجية التالية مثالاً على أداة اختيار البحث في جدول بيانات باستخدام هذه الميزة:

    const picker = new google.picker.PickerBuilder()
        .addView(google.picker.ViewId.SPREADSHEETS)
        .enableFeature(google.picker.Feature.NAV_HIDDEN)
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();