שילוב של Google Picker באפליקציות אינטרנט

תיבת דו-שיח של הכלי לבחירת קבצים ב-Google.

במאמר הזה מוסבר איך לשלב את כלי הבחירה של Google באפליקציות האינטרנט שלכם באמצעות Google Picker API.

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

תכונות

לחלונית לבחירת קבצים ב-Google יש כמה תכונות:

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

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

דרישות מוקדמות

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

צריך גם פרויקט ב-Google Cloud.

הגדרת הסביבה

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

הפעלת ה-API

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

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

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

כדי לאמת משתמשי קצה ולגשת לנתוני משתמשים באפליקציה, צריך ליצור מזהה לקוח אחד או יותר ב-OAuth 2.0. מזהה הלקוח משמש לזיהוי של אפליקציה אחת בשרתי OAuth של Google. אם האפליקציה פועלת בכמה פלטפורמות, צריך ליצור מזהה לקוח נפרד לכל פלטפורמה.
  1. ב-Google API Console, עוברים אל תפריט > Google Auth platform > Clients.

    מעבר אל "לקוחות"

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

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

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

חשוב: כשיוצרים אובייקט Picker, האפליקציה צריכה לשלוח אסימון גישה מסוג OAuth 2.0 עם תצוגות שמאפשרות גישה לנתונים פרטיים של משתמשים. כדי לבקש אסימון גישה, אפשר לעיין במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

ניהול הכלי לבחירת קבצים של Google

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

טעינה של ספריית Google Picker

כדי לטעון את ספריית הכלי לבחירת קבצים של 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 נטענת בהצלחה.

הערה: אם אתם משתמשים ב-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();