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

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

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

‫Google Picker API هي واجهة برمجة تطبيقات 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.

في Google Cloud Console، فعِّل Google Picker API.

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

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

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

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

في Google Cloud Console، انتقِل إلى "القائمة" > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.
الانتقال إلى "بيانات الاعتماد"
انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة تطبيقات.
يظهر مفتاح واجهة برمجة التطبيقات الجديد.
- انقر على "نسخ" لنسخ مفتاح واجهة برمجة التطبيقات لاستخدامه في رمز تطبيقك. يمكنك أيضًا العثور على مفتاح واجهة برمجة التطبيقات في قسم "مفاتيح واجهة برمجة التطبيقات" ضمن بيانات اعتماد مشروعك.
- لمنع الاستخدام غير المصرّح به، ننصحك بتقييد الأماكن وواجهات برمجة التطبيقات التي يمكن استخدام مفتاح واجهة برمجة التطبيقات فيها. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة إضافة قيود على واجهة برمجة التطبيقات.

إذا كنت تقيّد مفتاح واجهة برمجة التطبيقات لمنع الاستخدام غير المصرّح به، عليك تطبيق الإعدادات التالية:

قيود التطبيق: إذا ضبطت قيود التطبيق على المواقع الإلكترونية، عليك إضافة نطاق تطبيقك (على سبيل المثال، https://example.com/*) و https://docs.google.com/* إلى قائمة المواقع الإلكترونية المحدّدة ضمن القيود على المواقع الإلكترونية. بما أنّ أداة اختيار الملفات في Google يتم عرضها في iframe مستضاف على docs.google.com، فإنّ حذفها يؤدي إلى عرض أداة اختيار الملفات في Google للخطأ "مفتاح المطوّر لواجهة برمجة التطبيقات غير صالح".
قيود واجهة برمجة التطبيقات: إذا كنت تقيّد المفتاح بواجهات برمجة تطبيقات معيّنة، اختَر Google Picker API (وGoogle Drive API إذا كان تطبيقك يُجري طلبات مباشرة إلى Drive API).

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

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

في Google Cloud Console، انتقِل إلى "القائمة" > منصة Google للمصادقة > العملاء.
الانتقال إلى "العملاء"
انقر على إنشاء عميل.
انقر على نوع التطبيق > تطبيق ويب.
في حقل الاسم ، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في Google Cloud Console.
أضِف معرّفات الموارد المنتظمة (URI) المفوّضة المرتبطة بتطبيقك:
- تطبيقات من جهة العميل (JavaScript): ضمن مصادر JavaScript المفوّضة، انقر على إضافة معرّف الموارد المنتظم (URI). بعد ذلك، أدخِل معرّف الموارد المنتظم (URI) لاستخدامه في طلبات المتصفح. يحدّد هذا المعرّف النطاقات التي يمكن لتطبيقك إرسال طلبات واجهة برمجة التطبيقات منها إلى خادم OAuth 2.0.
- تطبيقات من جهة الخادم (Java وPython والمزيد): ضمن معرّفات الموارد المنتظمة (URI) المفوّضة لإعادة التوجيه، انقر على إضافة معرّف الموارد المنتظم (URI). بعد ذلك، أدخِل معرّف الموارد المنتظم (URI) لنقطة نهاية يمكن لخادم OAuth 2.0 إرسال الردود إليه.
انقر على إنشاء.
تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرّفات عميل 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"

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

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

يعرض الكائن 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). إذا اختار المستخدم عنصرًا، تتم أيضًا تعبئة مصفوفة docs. في هذا المثال، يظهر 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. يمكن أيضًا استخدام الكائن DocsView لخيارات فلترة إضافية.

تعديل مظهر "أداة اختيار الملفات في 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();

تضمين "أداة اختيار الملفات في Google" في iframe

يمكنك تضمين "أداة اختيار الملفات في Google" مباشرةً في iframe بتنسيق HTML، بدلاً من استخدام مربّع الحوار التلقائي، وذلك باستخدام طريقة PickerBuilder.toUri. تُنشئ الطريقة PickerBuilder.toUri معرّف الموارد المنتظم (URI) لكائن PickerBuilder.

يوضّح نموذج الرمز التالي كيفية تضمين "أداة اختيار الملفات في Google" في iframe:

    // Create a Google Picker builder.
    const builder = new google.picker.PickerBuilder()
        .setDeveloperKey('API_KEY')
        .setAppId('APP_ID')
        .setOAuthToken(accessToken)
        .addView(google.picker.ViewId.DOCS)
        .setCallback(pickerCallback);

    // Create an iframe and use .toUri as the source.
    const pickerContainer = document.getElementById('IFRAME_CONTAINER_ID');
    const iframe = document.createElement('iframe');

    iframe.setAttribute("src", builder.toUri().toString());
    iframe.style.width = "100%";
    iframe.style.height = "600px";
    iframe.style.border = "none";

    // Attach it to your page.
    pickerContainer.appendChild(iframe);

غيِّر القيم في السلسلة على الشكل التالي:

API_KEY: مفتاح واجهة برمجة التطبيقات.
APP_ID: رقم مشروع على السحابة الإلكترونية.
IFRAME_CONTAINER_ID: معرّف حاوية iframe.

عينة تعليمات برمجية: استخدام ميزات Google Picker API في تطبيقات الويب
استخدام مكوّن الويب "أداة اختيار الملفات في Google"
اختيار نطاقات Google Drive API

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

الميزات

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

إعداد البيئة

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

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

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

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

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

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

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

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

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

تضمين "أداة اختيار الملفات في Google" في iframe

مواضيع ذات صلة

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