הטמעה של Google Picker באפליקציות למחשב ולאפליקציות לנייד

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

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

תכונות

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

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

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

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

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

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

הגדרת הסביבה

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

הפעלת ה-API

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

הגדרת אימות והרשאה

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

אישור פרטי כניסה לאפליקציה למחשב

כדי ליצור מזהה לקוח ב-OAuth 2.0, פועלים לפי השלבים הבאים:

  1. ב-Google API Console, עוברים אל תפריט > Google Auth platform > Clients.

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

  2. לוחצים על Create Client.
  3. לוחצים על Application type‏ > Desktop app.
  4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק ב-Google API Console.
  5. לוחצים על יצירה.

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

כדי שאפליקציות יקבלו הרשאה לגשת לקבצים שההרשאה אליהם ניתנה להן בעבר, צריך לבצע את השלבים הבאים:

  1. צריך לקבל אסימון OAuth 2.0 עם היקף ההרשאות drive.file, drive או drive.readonly באמצעות ההוראות האלה: שימוש ב-OAuth 2.0 כדי לגשת אל Google APIs. מידע נוסף על היקפי גישה זמין במאמר בחירה של היקפי גישה ל-Google Drive API.

  2. מעבירים את אסימון OAuth 2.0 אל Drive API כדי לקרוא ולשנות קבצים שהמשתמש העניק גישה אליהם בעבר.

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

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

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

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

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

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

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

כדי לאפשר למשתמשים להעניק גישה לקבצים נוספים או לבחור קבצים לשימוש בתהליך של האפליקציה, פועלים לפי השלבים הבאים:

  1. כדי לבקש גישה להיקף drive.file ולפתוח את דף הגישה של OAuth 2.0 בכרטיסייה חדשה בדפדפן, פועלים לפי ההוראות במאמר שימוש ב-OAuth 2.0 כדי לגשת אל Google APIs. למידע נוסף על היקפי הרשאות, אפשר לעיין במאמר בחירת היקפי הרשאות של Google Drive API.

    שימו לב שמותר להשתמש בהיקף drive.file בלבד באפליקציות האלה, ואי אפשר לשלב אותו עם היקף אחר.

  2. כתובת ה-URL של הכרטיסייה החדשה בדפדפן מקבלת את כל הפרמטרים של מחרוזת השאילתה הרגילה של OAuth.

    צריך לצרף את פרמטרים של כתובת ה-URL prompt ו-trigger_onepick לבקשת כתובת ה-URL להרשאה ב-OAuth 2.0. אפשר גם להתאים אישית את בורר הקבצים של Google באמצעות כמה פרמטרים אחרים:

    פרמטר תיאור סטטוס
    prompt=consent ההנחיה כללה קובץ שאין לך גישה אליו. חובה
    trigger_onepick=true מפעילים את כלי הבחירה של Google. חובה
    allow_multiple=true אם הערך הוא True, המשתמש יכול לבחור כמה קבצים. אופציונלי
    mimetypes=MIMETYPES רשימה של סוגי MIME שמופרדים בפסיקים, לסינון תוצאות החיפוש. אם לא מגדירים את ההגדרה הזו, הקבצים מכל סוגי ה-MIME מוצגים בתצוגה. אופציונלי
    file_ids=FILE_IDS רשימה מופרדת בפסיקים של מזהי קבצים, לסינון תוצאות החיפוש. אם לא מציינים ערך, כל הקבצים מוצגים בתצוגה. אופציונלי
    allow_folder_selection=true אם המדיניות מוגדרת כ-True, המשתמש יכול לבחור גם תיקיות. אופציונלי

    בדוגמה הבאה מוצגת בקשה לכתובת URL להרשאה ב-OAuth 2.0:

    https://accounts.google.com/o/oauth2/v2/auth? \
client_id=CLIENT_ID \
&scope=https://www.googleapis.com/auth/drive.file \
&redirect_uri=REDIRECT_URI \
&response_type=code \
&access_type=offline \
&prompt=consent \
&trigger_onepick=true

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫CLIENT_ID: מזהה הלקוח של האפליקציה.

    • ‫REDIRECT_URI: המקום שאליו שרת ההרשאות מפנה את הדפדפן של המשתמש אחרי אימות מוצלח. לדוגמה, https://www.cymbalgroup.com/oauth2callback.

      הערך שצוין ב-redirect_uri חייב להיות כתובת URL ציבורית מסוג HTTPS. אם רוצים להשתמש בפרוטוקול מותאם אישית או בכתובת URL של localhost בשביל redirect_uri, צריך להשתמש בכתובת URL ציבורית מסוג HTTPS שמפנה לפרוטוקול המותאם אישית או לכתובת ה-URL של localhost.

  3. אחרי שהמשתמש מעניק גישה ובוחר את הקבצים הרלוונטיים, פרוטוקול OAuth מפנה אוטומטית אל redirect_uri שצוין בבקשה, עם הפרמטרים הבאים של כתובת ה-URL שנוספו:

    • ‫picked_file_ids: אם המשתמש העניק גישה ובחר קבצים, רשימה מופרדת בפסיקים של מזהי הקבצים שנבחרו.

    • ‫code: אסימון הגישה או קוד הגישה על סמך הפרמטר response_type שהוגדר בבקשה. הפרמטר הזה כולל קוד הרשאה חדש.

    • ‫scope: ההיקפים שנכללים בבקשה.

    • ‫error: אם המשתמש ביטל את הבקשה בתהליך בקשת ההסכמה, תוצג שגיאה.

    בדוגמה הבאה מוצגת תגובה של כתובת URL להרשאת OAuth 2.0:

    https://REDIRECT_URI?picked_file_ids=PICKED_FILE_IDS&code=CODE&scope=SCOPES

  4. האפליקציות צריכות להחליף את קוד ההרשאה משלב 3 באסימון חדש מסוג OAuth 2.0. מידע נוסף זמין במאמר בנושא החלפת קוד הרשאה באסימוני רענון וגישה.

  5. לאחר מכן, האפליקציות יכולות להשתמש במזהי הקבצים מפרמטר כתובת ה-URL בשלב 3 ובאסימון OAuth 2.0 שהתקבל בשלב 4 כדי לקרוא ל-Drive API. מידע נוסף זמין בסקירה הכללית על Google Drive API.

שימוש בכלי לבחירת קבצים של Google באפליקציות ל-Android

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

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

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

כדי להציג את בוחר הקבצים של Google במהלך ההרשאה, צריך ליצור AuthorizationRequest ולהשתמש בפרמטר המשאב PICKER_OAUTH_TRIGGER באובייקט AuthorizationRequest.ResourceParameter.

כשבונים את AuthorizationRequest:

  • משתמשים בהיקף drive.file.

  • קוראים לפונקציה setOptOutIncludingGrantedScopes ל-true כדי לוודא שהטוקן שמוחזר הוא רק עבור היקף ההרשאות drive.file ולא עבור היקפי הרשאות שניתנו בעבר.

  • מגדירים את השדה AuthorizationRequest.Prompt לערך CONSENT כדי להציג למשתמש בקשת הסכמה גם אם הוא כבר נתן אותה.

  • אפשר גם להשתמש באופרטור bitmap ‏OR ‏(|) כדי להגדיר את השדה AuthorizationRequest.Prompt לערך SELECT_ACCOUNT, וכך לאפשר למשתמש לבחור חשבון לפני שמוצגת לו בקשת ההסכמה.

הפעלת הכלי לבחירת קבצים של Google

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

  • ‫PICKER_ALLOW_MULTIPLE: מאפשר למשתמשים לבחור כמה קבצים.
  • ‫PICKER_MIMETYPES: מקבלת רשימה מופרדת בפסיקים של סוגי MIME לסינון תוצאות החיפוש. אם לא מוגדר, הקבצים מכל סוגי ה-MIME מוצגים בתצוגה.
  • ‫PICKER_FILE_IDS: מקבלת רשימה מופרדת בפסיקים של מזהי קבצים לסינון תוצאות החיפוש. אם לא מגדירים את ההגדרה הזו, כל הקבצים מוצגים בתצוגה.
  • ‫PICKER_ALLOW_FOLDER_SELECTION: מאפשר למשתמשים לבחור גם תיקיות.

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

אחרי שהמשתמש מעניק גישה ובוחר את הקבצים הרלוונטיים, מוחזר האובייקט getTokenResponseParams של המשאב AuthorizationResult. אם המשתמש העניק גישה, האובייקט הזה מכיל את הערך picked_file_ids, שהוא רשימה מופרדת בפסיקים של מזהי הקבצים שנבחרו.