Google Picker API הוא ממשק API של JavaScript שאפשר להשתמש בו באפליקציות אינטרנט כדי לאפשר למשתמשים לבחור או להעלות קבצים מ-Google Drive. המשתמשים יכולים להעניק הרשאה לאפליקציות שלכם לגשת לנתונים שלהם ב-Drive, וכך לספק דרך מאובטחת ומורשית לאינטראקציה עם הקבצים שלהם.
כלי בחירת הקבצים של Google פועל כתיבת דו-שיח של 'פתיחת קובץ' למידע שמאוחסן ב-Drive, ויש לו כמה תכונות:
- ממשק משתמש דומה לזה של Google Drive.
- כמה תצוגות שרואים בהן תצוגות מקדימות ותמונות ממוזערות של קבצים ב-Drive.
- חלון מודאלי מוטבע, כך שהמשתמשים אף פעם לא יוצאים מהאפליקציה הראשית.
שימו לב: הכלי לבחירת קבצים של Google לא מאפשר למשתמשים לארגן, להעביר או להעתיק קבצים מתיקייה אחת לתיקייה אחרת. כדי לנהל קבצים, צריך להשתמש ב- Google Drive API או בממשק המשתמש של Drive.
דרישות מוקדמות
אפליקציות שמשתמשות ב-Google Picker חייבות לפעול בהתאם לכל התנאים וההגבלות הקיימים. הכי חשוב: עליכם לזהות את עצמכם בצורה נכונה בבקשות.
צריך גם פרויקט ב-Google Cloud.
הגדרת הסביבה
כדי להתחיל להשתמש ב-Google Picker API, צריך להגדיר את הסביבה.
הפעלת ה-API
לפני שמשתמשים בממשקי Google API, צריך להפעיל אותם בפרויקט ב-Google Cloud. אפשר להפעיל ממשק API אחד או יותר בפרויקט אחד ב-Google Cloud.במסוף Google Cloud, מפעילים את Google Picker API.
יצירה של מפתח API
מפתח API הוא מחרוזת ארוכה שמכילה אותיות רישיות וקטנות, מספרים, קווים תחתונים ומקפים, למשל AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe.
שיטת האימות הזו משמשת לגישה אנונימית לנתונים שזמינים לציבור, כמו קבצים ב-Google Workspace ששותפו באמצעות הגדרת השיתוף 'כל מי שיש לו את הקישור הזה באינטרנט'. פרטים נוספים זמינים במאמר בנושא ניהול מפתחות API.
כך יוצרים מפתח API:
- במסוף Google Cloud, לוחצים על סמל התפריט > APIs & Services > Credentials.
- לוחצים על Create credentials > API key.
- מפתח ה-API החדש מוצג.
- לוחצים על סמל ההעתקה כדי להעתיק את מפתח ה-API לשימוש בקוד של האפליקציה. מפתח ה-API מופיע גם בקטע API Keys (מפתחות API) בפרטי הכניסה של הפרויקט.
- כדי למנוע שימוש לא מורשה, מומלץ להגביל את המקומות שבהם אפשר להשתמש במפתח ה-API ואת ממשקי ה-API שאפשר להשתמש בו עבורם. פרטים נוספים זמינים במאמר בנושא הוספת הגבלות על ממשקי API.
אישור פרטי כניסה לאפליקציית אינטרנט
כדי לאמת משתמשי קצה ולגשת לנתוני משתמשים באפליקציה, צריך ליצור מזהה לקוח אחד או יותר ב-OAuth 2.0. מזהה לקוח משמש לזיהוי של אפליקציה אחת בשרתי OAuth של Google. אם האפליקציה פועלת בכמה פלטפורמות, צריך ליצור מזהה לקוח נפרד לכל פלטפורמה.- אפליקציות בצד הלקוח (JavaScript) – בקטע מקורות מורשים של JavaScript, לוחצים על הוספת URI. לאחר מכן, מזינים URI לשימוש בבקשות של הדפדפן. הפרמטר הזה מזהה את הדומיינים שמהם האפליקציה יכולה לשלוח בקשות API לשרת OAuth 2.0.
- אפליקציות בצד השרת (Java, Python ועוד) – בקטע כתובות URI מורשות להפניה אוטומטית, לוחצים על הוספת כתובת URI. לאחר מכן, מזינים URI של נקודת קצה שאליה שרת OAuth 2.0 יכול לשלוח תגובות.
פרטי הכניסה החדשים שנוצרו מופיעים בקטע מזהי לקוח ב-OAuth 2.0.
חשוב לשים לב למזהה הלקוח. אין שימוש בסודות לקוח באפליקציות אינטרנט.
חשוב: כשיוצרים אובייקט Picker, האפליקציה צריכה לשלוח אסימון גישה מסוג OAuth 2.0 עם תצוגות שמאפשרות גישה לנתונים פרטיים של משתמשים. במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs מוסבר איך לבקש אסימון גישה.
ניהול הכלי לבחירת קבצים של 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() {
// 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 נטענת בהצלחה.
הערה: אם אתם משתמשים ב-TypeScript, אתם יכולים להתקין את @types/google.picker כדי להשתמש ב-window.google.picker. כדי לדווח על בעיה בסוגים האלה, צריך לפתוח כרטיס תמיכה.
הצגת הכלי לבחירת קבצים של Google
הפונקציה createPicker מוודאת שממשק Google Picker API סיים להיטען ושנוצר אסימון OAuth 2.0. משתמשים בשיטה PickerBuilder.setAppId כדי להגדיר את מזהה אפליקציית Drive באמצעות מספר הפרויקט ב-Cloud, כדי לאפשר לאפליקציה לגשת לקבצים של המשתמש. הפונקציה הזו יוצרת מופע של Google Picker ומציגה אותו:
// 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: מפתח ה-API. -
APP_ID: מספר הפרויקט ב-Cloud.
כדי ליצור מופע של Google Picker, צריך ליצור אובייקט Picker באמצעות PickerBuilder. הפונקציה PickerBuilder מקבלת את הפרמטרים View, אסימון OAuth 2.0, מפתח מפתח ופונקציית קריאה חוזרת להפעלה במקרה של הצלחה (pickerCallback).
האובייקט Picker מעבד כל פעם View אחד. מציינים לפחות תצוגה אחת, באמצעות ViewId (google.picker.ViewId.*) או באמצעות יצירת מופע של DocsView כדי לקבל שליטה נוספת על אופן העיבוד של התצוגה.
אם מוסיפים יותר מתצוגה מפורטת אחת לכלי לבחירת קבצים של Google, המשתמשים יכולים לעבור מתצוגה מפורטת אחת לאחרת בלחיצה על כרטיסייה בצד ימין. אפשר לקבץ כרטיסיות באופן לוגי באמצעות אובייקטים של ViewGroup.
רשימה של תצוגות תקפות זמינה במאמר ViewId בנושא כלי בחירת הקבצים של Google. כדי לקבל את הטוקן של אחת מהתצוגות האלה, צריך להשתמש בהיקף ההרשאות https://www.googleapis.com/auth/drive.file.
הטמעה של קריאה חוזרת (callback) של הכלי לבחירת קבצים ב-Google
אפשר להשתמש בקריאה חוזרת (callback) של Google Picker כדי להגיב לאינטראקציות של המשתמשים ב-Google Picker, כמו בחירת קובץ או לחיצה על 'ביטול'. בממשק 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). אם המשתמש בוחר פריט, מתבצע גם מילוי של המערך google.picker.Response.DOCUMENTS. בדוגמה הזו, 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.
שינוי המראה של כלי בחירת הקבצים של 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();