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