واجهة برمجة تطبيقات 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. تُستخدم طريقة المصادقة هذه للوصول إلى البيانات المتاحة للجميع بشكل مجهول. مثل ملفات 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"، يمكنك استدعاء الدالة 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() {
        // 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 APIs.

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

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

عرض "منتقي Google"

تتحقّق الدالة createPicker() للتأكّد من اكتمال تحميل Google Picker API. وأنه يتم إنشاء رمز OAuth مميز. يمكنك استخدام setAppId لضبط رقم تعريف تطبيق Drive للسماح للتطبيق بالوصول إلى ملفات المستخدم. تتضمن هذه الدالة تنشئ مثيلاً لأداة اختيار 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. باستخدام السمة PickerBuilder. تشير رسالة الأشكال البيانية يأخذ PickerBuilder الرمز View، وهو رمز OAuth مميز، ومفتاح مطوّر برامج ودالة معاودة الاتصال لطلبها عند النجاح (pickerCallback).

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

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

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

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

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

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

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

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

    let 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)
        .setCallback(pickerCallback)
        .build();
    

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

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

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

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

عرض "منتقي Google" بلغات أخرى

حدِّد لغة واجهة المستخدم من خلال توفير اللغة PickerBuilder. على سبيل المثال باستخدام الطريقة setLocale(locale).

يوضح نموذج التعليمات البرمجية التالي كيفية تعيين اللغة على الفرنسية:

    let picker = new google.picker.PickerBuilder()
        .addView(google.picker.ViewId.IMAGE_SEARCH)
        .setLocale('fr')
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();
    

في ما يلي قائمة اللغات المتاحة حاليًا: