Google Picker API הוא API של JavaScript שאפשר להשתמש בו באפליקציות האינטרנט כדי לאפשר למשתמשים לבחור או להעלות קבצים מ-Google Drive. המשתמשים יכולים להעניק לאפליקציות שלך הרשאת גישה נתוני Drive, שמספקים דרך מאובטחת ומורשית לאינטראקציה עם הקבצים.
Google Picker פועל כ-File Open (פתיחת קבצים) תיבת דו-שיח למידע שמאוחסן ב-Drive והוא כולל את התכונות הבאות:
- מראה וסגנון דומים לממשק המשתמש של Google Drive.
- כמה תצוגות עם תצוגות מקדימות ותמונות ממוזערות של קובצי Drive.
- חלון מודאלי מוטבע, כך שהמשתמשים אף פעם לא יוצאים מהאפליקציה הראשית.
הערה: הבורר של Google לא מאפשר למשתמשים לארגן, להעביר או להעתיק קבצים מתיקייה אחת למכשיר אחר. כדי לעשות את זה, אפשר להשתמש ב-Google Drive API. או בממשק המשתמש של Drive.
דרישות לגבי אפליקציות
אפליקציות שמשתמשות ב-Google Picker חייבות לציית לכל ההגדרות הקיימות תנאים והגבלות. הדבר החשוב ביותר הוא את עצמכם בבקשות שלכם.
יש לכם גם פרויקט ב-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 ו- שירותים > פרטי כניסה.
- לוחצים על יצירת פרטי כניסה >. API key.
- מפתח ה-API החדש מוצג.
- לוחצים על 'העתקה' . כדי להעתיק את מפתח ה-API לשימוש בקוד של האפליקציה. מפתח ה-API יכול להיות גם נמצא ב'מפתחות API'. בפרטי הכניסה של הפרויקט.
- לוחצים על Restrict key כדי לעדכן את ההגדרות המתקדמות ולהגביל את השימוש. של מפתח ה-API. מידע נוסף זמין במאמר החלת הגבלות על מפתחות API.
אישור פרטי כניסה לאפליקציית אינטרנט
כדי לאמת משתמשי קצה ולגשת לנתוני המשתמשים באפליקציה: ליצור מזהה לקוח אחד או יותר של OAuth 2.0. מזהה לקוח משמש לזיהוי אפליקציה יחידה לשרתי OAuth של Google. אם האפליקציה שלכם פועלת בכמה פלטפורמות, צריך ליצור מזהה לקוח נפרד לכל פלטפורמה.
- במסוף Google Cloud, נכנסים לתפריט > APIs & שירותים > פרטי כניסה.
- לוחצים על יצירת פרטי כניסה > מזהה לקוח OAuth.
- לוחצים על Application type (סוג אפליקציה) > Web application.
- בשדה 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 Picker מאפליקציית אינטרנט. שפת תרגום כדי לראות את הדוגמה המלאה, עוברים לדוגמת הקוד של 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 Picker.
מתבצעת קריאה לפונקציית הקריאה החוזרת של onPickerApiLoad() אחרי ספריית Google Picker
נטען בהצלחה.
הצגת הכלי לבחירת Google
הפונקציה createPicker() בודקת כדי לוודא שהטעינה של Google Picker API הסתיימה
ושנוצר אסימון OAuth. משתמשים ב
השדה setAppId כדי להגדיר את
מזהה האפליקציה ב-Drive כדי לאפשר לאפליקציה לגשת לקבצים של המשתמש. את הפונקציה הזאת
יוצר מופע של Google Picker ומציג אותו:
// 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)
.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: ''});
}
}
כדי ליצור מופע של Google Picker, צריך ליצור Picker
באמצעות PickerBuilder.
PickerBuilder לוקח את View, אסימון OAuth,
ופונקציית קריאה חוזרת (callback) להפעלה מוצלחת (pickerCallback).
האובייקט Picker מבצע רינדור של View אחד בכל פעם. יש לציין לפחות תצוגה אחת,
באמצעות ViewId (google.picker.ViewId.*) או על ידי יצירת מופע של
סוג (google.picker.*View). יש לציין את התצוגה לפי סוג כדי להוסיף
לשלוט על אופן העיבוד של התצוגה.
אם מוסיפים יותר מתצוגה אחת לבורר של Google, המשתמשים יכולים לעבור מתצוגה אחת לאחרת, על ידי
לחיצה על כרטיסייה בצד ימין. אפשר לקבץ כרטיסיות באופן לוגי עם אובייקטים מסוג ViewGroup.
הטמעת הקריאה החוזרת (callback) של Google Picker
אפשר להשתמש בקריאה חוזרת (callback) של Google Picker כדי להגיב לאינטראקציות של משתמשים ב-Google Picker, למשל
בחירת קובץ או לחיצה על 'ביטול'. 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 Picker (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 Picker
אפשר להשתמש באובייקט 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
באמצעות ה-method 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 |