واجهة برمجة تطبيقات Google Picker

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

يؤدي "منتقي Google" وظيفة "فتح ملف" مربّع حوار للمعلومات المخزَّنة على Drive وتضم هذه الميزات:

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

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

متطلّبات تقديم طلب الانضمام

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

إعداد البيئة

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

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

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

• في "وحدة تحكُّم Google Cloud"، فعِّل Google Picker API.

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

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

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

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

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

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

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

تفويض بيانات الاعتماد لتطبيق ويب

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

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

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

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

   سجِّل معرِّف العميل. لا يتم استخدام أسرار العملاء لتطبيقات الويب.

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

عرض أداة اختيار Google

تحميل مكتبة منتقي Google

لتحميل مكتبة Google Picker، يمكنك استدعاء gapi.load() مع اسم المكتبة ودالة callback لتشغيلها بعد تحميلها بنجاح:

    <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() {
        // TODO(developer): 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.

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

تُحمِّل الدالة onApiLoad() مكتبات "أداة اختيار Google". تشير رسالة الأشكال البيانية يتم استدعاء دالة معاودة الاتصال onPickerApiLoad() بعد مكتبة أداة اختيار Google بنجاح.

عرض "منتقي Google"

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

    // Create and render a Google Picker object for selecting from Drive.
    function createPicker() {
      const showPicker = () => {
        // TODO(developer): Replace with your API key
        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: ''});
      }
    }
    

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

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

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

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

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

    // A simple callback implementation.
    function pickerCallback(data) {
      const 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;
    }
    

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

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

استخدِم ViewGroup كطريقة لفلترة عناصر معيّنة. يوضح نموذج التعليمة البرمجية التالي كيفية استجابة "Google 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();
    

ضبط مظهر أداة اختيار 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();