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

مربّع حوار "أداة اختيار الملفات من Google"

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

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

الميزات

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

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

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

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

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

يجب أيضًا أن يكون لديك مشروع على 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 للمصادقة > العملاء.

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

  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

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

تحميل مكتبة أداة اختيار الملفات في Google

لتحميل مكتبة أداة اختيار الملفات في Google، استخدِم 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. يتم استدعاء دالة ردّ الاتصال onPickerApiLoad بعد تحميل مكتبة أداة اختيار الملفات في Google بنجاح.

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

عرض أداة اختيار الملفات في Google

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

    // 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: رقم مشروع على السحابة الإلكترونية.

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

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

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

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

تنفيذ دالة ردّ الاتصال في أداة اختيار الملفات في Google

يمكن استخدام دالة ردّ اتصال في أداة اختيار الملفات في Google للتفاعل مع تفاعلات المستخدم في أداة اختيار الملفات في Google، مثل اختيار ملف أو النقر على "إلغاء". تنقل واجهة 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‏ (google.picker.Response.ACTION). إذا اختار المستخدم عنصرًا، تتم أيضًا تعبئة مصفوفة google.picker.Response.DOCUMENTS. في هذا المثال، يظهر 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.

تعديل مظهر أداة اختيار الملفات في Google

يمكنك استخدام عنصر Feature لتفعيل الميزات أو إيقافها لطرق عرض مختلفة. لضبط مظهر نافذة أداة اختيار الملفات في Google، استخدِم طريقة 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();