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

مربّع حوار أداة اختيار Google

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

تعمل أداة اختيار Google كمربع حوار "فتح ملف" للمعلومات المخزنة على Drive وتحتوي على الميزات التالية:

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

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

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

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

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

إعداد البيئة

لبدء استخدام واجهة برمجة تطبيقات Google Picker، يجب عليك إعداد بيئتك.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

عرض منتقي Google

يتناول الجزء المتبقي من هذا الدليل كيفية تحميل وعرض "أداة اختيار Google" من أحد تطبيقات الويب. لعرض المثال الكامل، انتقِل إلى نموذج رمز منتقي 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 مميز. تنشئ هذه الدالة بعد ذلك مثيلاً من منتقي 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)
            .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();
    
للحصول على قائمة بأنواع طرق العرض الصالحة، راجِع ViewId.

ضبط مظهر "منتقي 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();
    

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

af
am
ar
bg
bn
ca
cs
da
de
el
en
en-GB
es
es-419
et
eu
fa
fi
fil
fr
fr-CA
gl
gu
hi
hr
hu
id
is
it
iw
ja
kn
ko
lt
lv
ml
mr
ms
nl
no
pl
pt-BR
pt-PT
ro
ru
sk
sl
sr
sv
sw
ta
te
th
tr
uk
ur
vi
zh-CN
zh-HK
zh-TW
zu