Google Picker API

תיבת הדו-שיח של 'בוחר Google'.

Google Picker API הוא ממשק JavaScript API שניתן להשתמש בו באפליקציות האינטרנט כדי לאפשר למשתמשים לבחור או להעלות קבצים ל-Google Drive. המשתמשים יכולים להעניק לאפליקציות שלך הרשאת גישה לנתונים שלהם ב-Drive, וכך לספק דרך מאובטחת ומורשה לבצע פעולות בקבצים שלהן.

הכלי לבחירת Google משמש כתיבת הדו-שיח 'פתיחת קובץ' לקבלת מידע המאוחסן ב-Drive, וכולל את התכונות הבאות:

  • מראה וסגנון דומים לממשק המשתמש של Google Drive.
  • מספר תצוגות שמציגות תצוגות מקדימות ותמונות ממוזערות של קבצים ב-Drive.
  • חלון מודולרי מוטבע, כך שהמשתמשים לעולם לא יעזבו את האפליקציה הראשית.

שים לב שהכלי לבחירת Google לא מאפשר למשתמשים לארגן, להעביר או להעתיק קבצים מתיקייה אחת לאחרת. לשם כך תוכלו להשתמש ב-Google Drive API או בממשק המשתמש של Drive.

דרישות היישום

אפליקציות שמשתמשות ב-Google Picker חייבות לציית לכל התנאים וההגבלות הקיימים. הדבר החשוב ביותר הוא שאתם צריכים להזדהות בצורה נכונה בבקשות.

צריך להיות לכם גם פרויקט ב-Google Cloud.

הגדרת הסביבה

כדי להתחיל להשתמש ב-Google Picker API, עליכם להגדיר את הסביבה.

מפעילים את ה-API

כדי להשתמש ב-Google APIs, צריך להפעיל אותם בפרויקט ב-Google Cloud. אפשר להפעיל ממשק API אחד או יותר בפרויקט אחד ב-Google Cloud.

יצירה של מפתח API

מפתח API הוא מחרוזת ארוכה שמכילה אותיות רישיות וקטנות, מספרים, קווים תחתונים ומקפים, כמו AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. שיטת האימות הזו משמשת לגישה אנונימית לנתונים שזמינים באופן ציבורי, כמו קבצים של Google Workspace ששותפו באמצעות הגדרת השיתוף 'כל אחד באינטרנט שיש לו את הקישור הזה'. למידע נוסף, קראו את המאמר אימות באמצעות מפתחות API.

כך יוצרים מפתח API:

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create credentials > API key.
  3. מפתח ה-API החדש מוצג.
    • לוחצים על סמל ההעתקה כדי להעתיק את מפתח ה-API ולהשתמש בו בקוד של האפליקציה. אפשר למצוא את מפתח ה-API גם בקטע API Keys (מפתחות API) של פרטי הכניסה לפרויקט.
    • לוחצים על Restrict key כדי לעדכן הגדרות מתקדמות ולהגביל את השימוש במפתח ה-API. פרטים נוספים זמינים במאמר החלת הגבלות על מפתחות API.

אישור פרטי כניסה לאפליקציית אינטרנט

כדי לאמת משתמשי קצה ולגשת לנתוני המשתמשים באפליקציה, צריך ליצור מזהה לקוח אחד או יותר של OAuth 2.0. מזהה הלקוח משמש לזיהוי אפליקציה יחידה לשרתי OAuth של Google. אם האפליקציה פועלת בכמה פלטפורמות, צריך ליצור מזהה לקוח נפרד לכל פלטפורמה.

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על יצירת פרטי כניסה > מזהה לקוח OAuth.
  3. לוחצים על Application type (סוג האפליקציה) > Web application (אפליקציית אינטרנט).
  4. בשדה שם, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. מוסיפים מזהי URI מורשים שקשורים לאפליקציה:
    • אפליקציות בצד הלקוח (JavaScript) – בקטע מקורות JavaScript מורשים, לוחצים על הוספת URI. לאחר מכן מזינים URI שישמש לבקשות דפדפן. מזהה את הדומיינים שמהם האפליקציה שלך יכולה לשלוח בקשות API לשרת OAuth 2.0.
    • אפליקציות בצד השרת (Java, Python ועוד) – בקטע Authorized redirect URIs (אפליקציות בצד השרת, Java, Python ועוד) – לוחצים על Add URI (הוספת URI). לאחר מכן מזינים URI של נקודת קצה שאליה שרת OAuth 2.0 יכול לשלוח תגובות.
  6. לוחצים על Create. מופיע המסך של לקוח OAuth שנוצר, ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.

    יש לציין את מזהה הלקוח. סודות לקוח לא משמשים לאפליקציות אינטרנט.

  7. לוחצים על אישור. פרטי הכניסה החדשים שנוצרו מופיעים בקטע מזהי לקוח ב-OAuth 2.0.
חשוב: כשיוצרים אובייקט Picker, האפליקציה צריכה לשלוח אסימון גישה מסוג OAuth 2.0 עם תצוגות שמקבלות גישה לנתונים פרטיים של משתמשים. כדי לבקש אסימון גישה, ראו שימוש ב-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 API.

ספריית JavaScript של google.accounts.oauth2 עוזרת לך לבקש הסכמת משתמשים ולקבל אסימון גישה כדי לעבוד עם נתוני משתמשים. השיטה initTokenClient() מפעילה לקוח אסימון חדש עם מזהה הלקוח של אפליקציית האינטרנט שלך. מידע נוסף זמין במאמר שימוש במודל האסימון.

הפונקציה onApiLoad() טוענת את ספריות Google Picker. מתבצעת הפעלה של פונקציית הקריאה החוזרת (callback) 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, צריך ליצור אובייקט Picker באמצעות PickerBuilder. הקוד PickerBuilder משתמש ב-View, באסימון OAuth, במפתח מפתח ובפונקציית קריאה חוזרת כדי להפעיל את השיטה בהצלחה (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 Picker בשפות אחרות

מציינים את שפת ממשק המשתמש על ידי ציון הלוקאל למכונה PickerBuilder באמצעות השיטה setLocale(locale).

דוגמת הקוד הבאה מראה כיצד להגדיר את המקום לצרפתית:

    let picker = new google.picker.PickerBuilder()
        .addView(google.picker.ViewId.IMAGE_SEARCH)
        .setLocale('fr')
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();
    

רשימת הלוקאלים שנתמכים כרגע:

af
am
ar
bg
bn
ca
cs
da
de
el
en
en-GB
es
es-419
et
eu
fa
fi
fil
fr
fr-CA
gl
gu
hi
hr
hu
id
is
it
iw
ja
kn
ko
lt
lv
ml
mr
ms
nl
no
pl
pt-BR
pt-PT
ro
ru
sk
sl
sr
sv
sw
ta
te
th
tr
uk
ur
vi
zh-CN
zh-HK
zh-TW
zu