בוחר Google הוא תיבת דו-שיח 'פתיחת קובץ' למידע המאוחסן ב-Google Drive. לבורר Google יש את התכונות הבאות:
- מראה ותחושה דומים לממשק המשתמש של Google Drive.
- מספר תצוגות מקדימות של תמונות ממוזערות של קובצי Drive.
- חלון מודאלי מוטבע כך שהמשתמשים לא יוצאים מהאפליקציה הראשית.
ממשק ה-API של Google Picker הוא JavaScript של JavaScript שניתן להשתמש בו באפליקציות האינטרנט שלכם כדי לאפשר למשתמשים לפתוח או להעלות קובצי Drive.
דרישות הבקשה
אפליקציות שמשתמשות בבורר של Google חייבות לעמוד בכל התנאים וההגבלות הקיימים. והכי חשוב, עליכם לזהות את עצמכם נכון בבקשות.
בנוסף, אתם צריכים פרויקט ב-Google Cloud.הגדרת הסביבה
כדי להתחיל להשתמש ב-Google Picker API, עליך להגדיר את הסביבה.
מפעילים את ה-API
לפני שמשתמשים ב-Google APIs, צריך להפעיל אותם בפרויקט ב-Google Cloud. אתם יכולים להפעיל ממשק API אחד או יותר בפרויקט אחד ב-Google Cloud.
במסוף Google Cloud, מפעילים את Google Picker API.
יצירה של מפתח API
מפתח API הוא מחרוזת ארוכה שמכילה אותיות רישיות וקטנות, מספרים, קו תחתון ומקפים, למשל AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe.
שיטת האימות הזו משמשת לגישה אנונימית לנתונים ציבוריים, כמו קובצי Google Workspace ששותפו באמצעות הגדרת השיתוף "כל מי שבאינטרנט עם הקישור הזה". לפרטים נוספים, ראו אימות באמצעות מפתחות API.
כך יוצרים מפתח API:
- במסוף Google Cloud, עוברים לתפריט > ממשקי API ושירותים > פרטי כניסה.
- לוחצים על Create credentials > API API.
- מפתח ה-API החדש שלכם מוצג.
- לוחצים על 'העתקה' כדי להעתיק את מפתח ה-API ולהשתמש בו בקוד האפליקציה. מפתח ה-API מופיע גם בקטע 'מפתחות API' בפרטי הכניסה של הפרויקט.
- לוחצים על Restrict key כדי לעדכן את ההגדרות המתקדמות ולהגביל את השימוש במפתח ה-API. מידע נוסף זמין במאמר החלת הגבלות על מפתחות API.
אישור פרטי כניסה עבור אפליקציית אינטרנט
כדי לבצע אימות כמשתמש קצה ולגשת לנתוני המשתמשים באפליקציה, עליכם ליצור מזהה לקוח אחד או יותר של OAuth 2.0. מזהה לקוח משמש לזיהוי אפליקציה אחת לשרתי OAuth של Google. אם האפליקציה פועלת בכמה פלטפורמות, עליכם ליצור מזהה לקוח נפרד לכל פלטפורמה.
- במסוף Google Cloud, עוברים לתפריט > ממשקי API ושירותים > פרטי כניסה.
- לוחצים על Create Credentials > OAuth client ID.
- לוחצים על סוג אפליקציה > אפליקציית אינטרנט.
- בשדה Name, מזינים שם לפרטי הכניסה. השם הזה מופיע רק במסוף Google Cloud.
- מוסיפים מזהי URI מורשים שקשורים לאפליקציה:
- אפליקציות בצד הלקוח (JavaScript) – בקטע מקורות JavaScript מורשים לוחצים על הוספת URI. לאחר מכן, יש להזין URI לשימוש בבקשות לדפדפן. מזהה את הדומיינים שמהם האפליקציה שלך יכולה לשלוח בקשות API לשרת OAuth 2.0.
- אפליקציות בצד השרת (Java, Python ועוד) – בקטע מזהי URI מורשים להפניה מחדש, לוחצים על הוספת URI. לאחר מכן מזינים URI של נקודת קצה שאליה שרת ה-OAuth 2.0 יכול לשלוח תגובות.
- לוחצים על יצירה. המסך שנוצר על ידי הלקוח ב-OAuth מופיע. הוא כולל את מספר הלקוח החדש ואת סוד הלקוח.
הערה: סודות של לקוחות לא נמצאים בשימוש באפליקציות אינטרנט.
- לוחצים על אישור. פרטי הכניסה החדשים שייווצרו יופיעו במזהי לקוחות ב-OAuth 2.0.
Picker. כדי לבקש אסימון גישה, עיינו במאמר שימוש ב-OAuth 2.0 לגישה אל Google APIs.
הצגה של בוחר Google
בהמשך המדריך נסביר איך לטעון ולהציג את הבורר של Google מאפליקציית אינטרנט. כדי לראות את הדוגמה המלאה, אתם יכולים לעיין בדוגמה של קוד Google Picker.טעינת הספרייה של 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 APIs.
ספריית JavaScript של google.accounts.oauth2 עוזרת לכם לבקש את הסכמת המשתמשים ולקבל אסימון גישה, כדי לעבוד עם נתוני המשתמשים.
השיטה initTokenClient() מפעילה לקוח אסימון חדש עם מזהה הלקוח של אפליקציית האינטרנט שלכם. מידע נוסף זמין במאמר שימוש במודל האסימון.
הפונקציה onApiLoad() טוענת את ספריות הבורר של Google. פונקציית הקריאה החוזרת של onPickerApiLoad() נקראת אחרי שספריית הבורר של Google נטענת.
הצגה של בוחר Google
הפונקציה createPicker() בודקת בהמשך כדי לוודא שה-API של 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, עליכם ליצור אובייקט Picker באמצעות PickerBuilder. ל-PickerBuilder יש צורך ב-View, באסימון OAuth, במפתח למפתחים ובפונקציית קריאה חוזרת כדי לקרוא להצלחה (pickerCallback).
האובייקט Picker מבצע רינדור View בכל פעם. אפשר לציין לפחות תצוגה אחת דרך ViewId (google.picker.ViewId.*) או על ידי יצירת מכונה מסוג (google.picker.*View). עליכם להגדיר את התצוגה לפי סוג כדי לקבל שליטה נוספת על אופן העיבוד של התצוגה.
אם מוסיפים יותר מתצוגה אחת לבורר של Google, המשתמשים יכולים לעבור בין התצוגות באמצעות לחיצה על כרטיסייה בצד ימין. אפשר לקבץ כרטיסיות באופן לוגי עם אובייקטים של ViewGroup.
הטמעת הקריאה החוזרת (callback) של Google Picker
אפשר להשתמש בקריאה חוזרת (callback) של Google Picker כדי להגיב לאינטראקציות של המשתמש בכלי לבחירת 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;
}
הקריאה החוזרת (callback) מקבלת אובייקט 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 Picker, אפשר להשתמש בפונקציה 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 |