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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

مربع حوار منتقي Google.

منتقي Google هو مربع حوار "فتح ملف" للمعلومات المخزنة على Google Drive. يتضمن منتقي Google الميزات التالية:

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

واجهة برمجة تطبيقات Google Picker هي واجهة برمجة تطبيقات جافا سكريبت يمكنك استخدامها في تطبيقات الويب للسماح للمستخدمين بفتح ملفات 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، وغير ذلك)–ضمن عناوين URL لإعادة التوجيه المُعتمَدة، انقر على إضافة URI. بعد ذلك، أدخِل معرّف الموارد المنتظم (URI) لنقطة النهاية الذي يمكن لخادم OAuth 2.0 إرسال الردود إليه.
  6. انقر على إنشاء. تظهر شاشة عميل OAuth الذي تم إنشاؤه وتعرض معرِّف العميل الجديد وسر العميل.

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

  7. انقر على حسنًا. تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرّفات عميل OAuth 2.0.
  8. اختياري: إذا كنت تنشئ بيانات اعتماد باعتبارها متطلبًا أساسيًا لبدء التشغيل السريع في JavaScript، عليك أيضًا إنشاء مفتاح واجهة برمجة تطبيقات.
ملاحظة مهمة: يجب أن يرسل تطبيقك رمز دخول مميز عبر 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: 'YOUR_CLIENT_ID',
          scope: 'YOUR_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>
    

تحمِّل الدالة onApiLoad() مكتبات منتقي Google. يتم استدعاء وظيفة رد الاتصال في onPickerApiLoad() بعد تحميل مكتبة منتقي Google بنجاح.

عرض منتقي Google

تتحقّق الدالة createPicker() من انتهاء عملية تحميل واجهة برمجة تطبيقات Google Picker ومن إنشاء رمز 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('YOUR_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، يجب تقديم View وoauthToken وdeveloperKey ودالة استدعاء للاتصال عند النجاح (pickerCallback).

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

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

تنفيذ رد اتصال المنتقي

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

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

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

     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