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

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

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

תכונות

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

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

שימו לב: למרות שאפשר לבחור ולהעלות קבצים באמצעות בורר הקבצים של 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

    מפעילים את בורר הקבצים של Google כדי לאמת את האפליקציה.

  • תיבת דו-שיח לכניסה באמצעות חשבון Google והרשאות

    נכנסים לחשבון Google ומעניקים את ההרשאות הנדרשות.

  • ממשק לבחירת קבצים ב-Google Drive בתוך הכלי לבחירת קבצים

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

  • מסך אישור להוספת קובץ עם הכפתור 'הוספה'

    מאשרים את הבחירה ולוחצים על 'הוספה' כדי להוסיף את הקובץ לאפליקציה.

שילוב של בורר הקבצים של 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: כתובת ה-URL שאליה שרת ההרשאות מפנה את הדפדפן של המשתמש אחרי אימות מוצלח. לדוגמה, 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.

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