Google Picker API

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

Google Picker פועל כ-File Open (פתיחת קבצים) תיבת דו-שיח למידע שמאוחסן ב-Drive והוא כולל את התכונות הבאות:

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

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

דרישות לגבי אפליקציות

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

הגדרת הסביבה

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

הפעלת ה-API

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

• במסוף Google Cloud, מפעילים את Google Picker API.

  להפעלת ה-API

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

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

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

1. במסוף Google Cloud, נכנסים לתפריט menu > ממשקי API ו- שירותים > פרטי כניסה.

   כניסה לדף Credentials

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

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

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

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

   כניסה לדף Credentials

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

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

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

הצגת הכלי לבחירת Google

טעינת ספריית 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 Picker

הפונקציה 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();
    

כוונון המראה של 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();
    

זוהי רשימת הלוקאלים הנתמכים בשלב הזה: