منتقي Google هو مربّع حوار "فتح الملف" للاطّلاع على المعلومات المُخزّنة على Google Drive. تتضمن منتقي Google الميزات التالية:
- شكل وأسلوب يشبهان واجهة مستخدم Google Drive.
- العديد من طرق العرض التي تعرض معاينات وصورًا مصغّرة لملفات Drive
- نافذة مشروطة مضمَّنة حتى لا يغادر المستخدمون التطبيق الرئيسي مطلقًا.
Google Picker API هي واجهة برمجة تطبيقات JavaScript يمكنك استخدامها في تطبيقات الويب للسماح للمستخدمين بفتح ملفات 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، انتقِل إلى رمز القائمة > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.
- انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
- يتم عرض مفتاح واجهة برمجة التطبيقات الجديد.
- انقر على رمز النسخ لنسخ مفتاح واجهة برمجة التطبيقات الخاص بك لاستخدامه في رمز تطبيقك. يمكن أيضًا العثور على مفتاح واجهة برمجة التطبيقات في قسم "مفاتيح واجهة برمجة التطبيقات" في بيانات اعتماد مشروعك.
- انقر على تقييد المفتاح لتعديل الإعدادات المتقدّمة والحدّ من استخدام مفتاح واجهة برمجة التطبيقات. للحصول على مزيد من التفاصيل، يُرجى الاطّلاع على تطبيق قيود مفتاح واجهة برمجة التطبيقات.
تفويض بيانات الاعتماد لتطبيق ويب
للمصادقة كمستخدم كمستخدم والوصول إلى بيانات المستخدم في تطبيقك، عليك إنشاء معرِّف عميل OAuth 2.0 أو أكثر. يتم استخدام معرِّف العميل لتحديد تطبيق واحد لخوادم OAuth من Google. إذا كان تطبيقك يعمل على أنظمة أساسية متعددة، يجب إنشاء معرِّف عميل منفصل لكل نظام أساسي.
- في وحدة تحكّم Google Cloud، انتقِل إلى رمز القائمة > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.
- انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
- انقر على نوع التطبيق > تطبيق الويب.
- في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في وحدة تحكم Google Cloud.
- أضِف معرّفات الموارد المنتظمة (URI) المُعتمَدة ذات الصلة بتطبيقك:
- التطبيقات من جهة العميل (JavaScript): ضمن مصادر JavaScript المسموح بها، انقر على إضافة معرّف الموارد المنتظم (URI). بعد ذلك، أدخِل معرّف الموارد المنتظم (URI) المطلوب استخدامه لطلبات المتصفّح. يحدِّد هذا الإعداد النطاقات التي يمكن لتطبيقك إرسال طلبات واجهة برمجة التطبيقات منها إلى خادم OAuth 2.0.
- التطبيقات من جهة الخادم (Java وPython وغير ذلك): ضمن معرِّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه، انقر على إضافة معرِّف موارد منتظم (URI). بعد ذلك، أدخِل معرِّف الموارد المنتظم (URI) لنقطة النهاية الذي يمكن لخادم OAuth 2.0 إرسال استجابات إليه.
- انقر على إنشاء. ستظهر شاشة OAuth التي أنشأها العميل، والتي تعرض معرِّف العميل والرمز الجديد للعميل.
سجِّل معرِّف العميل. لا تُستخدم أسرار العملاء لتطبيقات الويب.
- انقر على حسنًا. تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرِّفات عميل OAuth 2.0.
Picker. لطلب رمز الدخول، يُرجى الاطلاع على استخدام OAuth 2.0 للدخول إلى Google APIs.
عرض منتقي Google
تتناول بقية هذا الدليل كيفية تحميل منتقي Google وعرضه من تطبيق ويب. للاطّلاع على المثال الكامل، يُرجى الانتقال إلى نموذج رمز منتقي Google.تحميل مكتبة Google Picker
لتحميل مكتبة Google Picker، اطلب 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.
يمكنك الاستفادة من مكتبة JavaScript google.accounts.oauth2 للحصول على موافقة المستخدمين والحصول على رمز الدخول لاستخدام بيانات المستخدمين.
تُعدّ الطريقة initTokenClient() برنامج رمز مميز جديدًا باستخدام معرِّف عميل تطبيق الويب. لمزيد من المعلومات، اطّلع على استخدام نموذج الرمز المميّز.
تحمِّل الدالة onApiLoad() مكتبات Google Picker. ويتم
طلب دالة رد الاتصال onPickerApiLoad() بعد تحميل مكتبة Google Picker
بنجاح.
عرض منتقي 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('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();
في ما يلي قائمة باللغات المتاحة حاليًا:
afamarbgbncacs |
dadeelenen-GBeses-419 |
eteufafifilfrfr-CA |
glguhihrhuidis |
itiwjaknkoltlv |
mlmrmsnlnoplpt-BR |
pt-PTroruskslsrsv |
swtatethtrukur |
vizh-CNzh-HKzh-TWzu |