הגדרת שילוב עם ממשק משתמש של Drive

כדי להציג את האפליקציה שלכם ב-Google Drive כשמשתמש יוצר או פותח קובץ, תחילה עליכם להגדיר שילוב של ממשק המשתמש (UI) של Drive. ההגדרה נדרשת גם כדי שהאפליקציה תופיע ב-Google Workspace Marketplace.

הפעלת ה-API של Drive

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

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

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

  הפעלה של ה-API

הגדרת שילוב עם ממשק המשתמש של Drive

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

   כניסה לדף Enabled APIs & services.

2. בחלק התחתון של מרכז השליטה של ממשקי ה-API והשירותים, לוחצים על Google Drive API. מופיע דף ההגדרות האישיות של Google Drive API.
3. בוחרים בכרטיסייה שילוב ממשק המשתמש של Drive.
4. (אופציונלי) מזינים שם בשדה שם האפליקציה. שם האפליקציה מוצג למשתמשים בכרטיסייה 'ניהול אפליקציות' בהגדרות של Drive.
5. (אופציונלי) מזינים תיאור קצר של שורה אחת בשדה Short description. התיאור הקצר מוצג למשתמשים בכרטיסייה 'ניהול אפליקציות' בהגדרות Drive.
6. (אופציונלי) מזינים תיאור מלא בשדה תיאור ארוך.

7. מעלים סמל אפליקציה אחד או יותר שיוצגו ברשימת האפליקציות המקושרות של Drive, ובתפריט ההקשר 'פתיחה באמצעות'. הסמלים צריכים להיות בפורמט PNG עם רקע שקוף. ייתכן שיחלפו עד 24 שעות לפני שסמלים יופיעו ב-Drive.

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

8. כדי להשתמש בפריט התפריט 'פתיחה באמצעות' בממשק המשתמש של Drive, מזינים את כתובת ה-URL של האפליקציה בשדה Open URL. כתובת ה-URL הזו משמשת את תפריט ההקשר 'פתיחה באמצעות'.

   • כתובת ה-URL חייבת להכיל שם דומיין שמוגדר במלואו. השדה localhost לא פועל.
   • כתובת ה-URL הזו צריכה להיות נגישה למשתמשים הרצויים באפליקציה. אם יש לכם כמה גרסאות של האפליקציה, למשל גרסה לציבור הרחב וגרסה במהדורה מוגבלת למשתמשים נבחרים, צריך להשתמש בכתובת URL ייחודית לכל גרסה. לאחר מכן אפשר ליצור הגדרות שונות לאפליקציה לכל גרסה.
   • כדי לפרסם את האפליקציה ב-Google Workspace Marketplace, צריך לאמת את הבעלות על כתובת ה-URL הזו.
   • כברירת מחדל, פרמטר של שאילתה state מצורף לכתובת ה-URL הזו כדי להעביר נתונים מממשק המשתמש של Drive לאפליקציה שלכם. למידע על תוכן הפרמטר state, קראו את הפרמטר state.
   אזהרה: האפשרות להציג באופן אוטומטי את מסך ההסכמה של OAuth 2.0 הוצאה משימוש. אין לסמן את התיבה הזו. האפליקציה צריכה להפעיל את כל בקשות ההרשאה.

9. (אופציונלי) מזינים את ברירת המחדל של סוגי MIME וסיומות קבצים בשדות ברירת המחדל של סוגי MIME וסיומות הקבצים של ברירת המחדל. סוגי ה-MIME וסיומות הקבצים שמוגדרים כברירת מחדל מייצגים קבצים שהאפליקציה נוצרה באופן ייחודי לפתיחה. לדוגמה, יכול להיות שייפתח פורמט מובנה ליצירת שכבות ולעריכת תמונות. מומלץ לכלול רק סוגי מדיה סטנדרטיים, ולוודא שאין בהם שגיאות הקלדה ושגיאות איות. אם האפליקציה פותחת רק קובצי קיצור דרך או קובצי קיצור של צד שלישי, אפשר להשאיר את סוג ה-MIME ריק.

10. (אופציונלי) מזינים סוגי MIME משניים וסיומות קבצים בשדות סוגי MIME משניים וסיומות קובץ משניות. סוגי MIME משניים וסיומות קבצים מייצגים קבצים שהאפליקציה יכולה לפתוח, אבל הם לא ספציפיים לאפליקציה. לדוגמה, האפליקציה שלכם יכולה להיות אפליקציה לעריכת תמונות שפותחת תמונות PNG ו-JPG. מומלץ לכלול רק סוגי מדיה סטנדרטיים, ולוודא שאין בהם שגיאות הקלדה ושגיאות איות. אם האפליקציה פותחת רק קובצי קיצור דרך או קובצי קיצור של צד שלישי, אפשר להשאיר את סוג ה-MIME ריק.

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

11. אם רוצים להשתמש בלחצן 'חדש' בממשק המשתמש של Drive ולבקש מהמשתמשים ליצור קובץ באפליקציה, צריך לסמן את התיבה יצירת קבצים. השדות New URL (כתובת URL חדשה) ו-Document name (שם המסמך) האופציונליים יופיעו.

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

12. מזינים כתובת URL בשדה כתובת URL חדשה. הלחצן 'חדש' משתמש בכתובת ה-URL הזו כדי להפנות את המשתמש לאפליקציה.

    הערה: משאירים את השדה 'שם המסמך' ריק. השדה הזה לא בשימוש יותר.

13. (אופציונלי) אם אתם רוצים שהאפליקציה תפתח קבצים שנתמכים ב-Google Workspace, מסמנים את התיבה Importing.

14. (אופציונלי) אם האפליקציה צריכה לנהל קבצים בתיקיות אחסון שיתופי, מסמנים את התיבה תמיכה בתיקיות אחסון שיתופי. במאמר הטמעת תמיכה בתיקיות אחסון שיתופי מוסבר בהרחבה איך משתמשים בתיקיות אחסון שיתופי באפליקציה.

15. לוחצים על שליחה.

שליחת בקשה להיקף ההרשאות drive.install

כדי לאפשר לאפליקציות להופיע כאפשרות בתפריט 'פתיחה באמצעות' או 'חדש', צריך לבקש שההיקף של https://www.googleapis.com/auth/drive.install ישתלב עם ממשק המשתמש של Drive. כשמשתמשים בהיקף בקשה כזה, תופיע תיבת דו-שיח דומה לזו:

איור 1. תיבת הדו-שיח של ההתקנה כשמשתמשים בהיקפים של ממשק המשתמש של Drive.

במאמר מידע על הרשאות ואימות ספציפיות ל-API תוכלו לקרוא מידע נוסף על ההיקפים שאפשר לבקש לאפליקציות Drive, ועל האופן שבו ניתן לבקש אותן.

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

הפרמטר state

כברירת מחדל, הפרמטר state מצורף גם לכתובת ה-URL הפתוחה וגם לכתובת ה-URL החדשה כדי להעביר נתונים מממשק המשתמש של Drive לאפליקציה. הפרמטר הזה מכיל מחרוזת מקודדת של JSON עם משתני תבנית ונתונים לגבי הבקשה לאפליקציה. המשתנים הכלולים תלויים בסוג כתובת ה-URL שבה השתמשתם (Open URL או New URL):

משתנה של תבנית	התיאור	אפליקציה של כתובת URL
{ids}	רשימה מופרדת בפסיקים של מזהי קבצים שפתוחים.	פתיחת כתובת URL
{exportIds}	רשימה של מזהי הקבצים שיוצאו, שמופרדים בפסיקים (משמשת רק לפתיחת מסמכים מובנים של Google).	פתיחת כתובת URL
{resourceKeys}	מילון JSON של מזהי קבצים שממופים למפתחות המשאבים התואמים שלהם.	פתיחת כתובת URL
{folderId}	המזהה של תיקיית ההורה.	כתובת URL חדשה
{folderResourceKey}	קוד הגישה של תיקיית ההורה.	כתובת URL חדשה
{userId}	מזהה הפרופיל שמזהה את המשתמש.	פתיחה של כתובת ה-URL וכתובת ה-URL החדשה
{action}	הפעולה שמבוצעת. הערך הוא open כשמשתמשים בכתובת URL פתוחה או ב-create כשמשתמשים בכתובת URL חדשה.	פתיחה של כתובת ה-URL וכתובת ה-URL החדשה

הפרמטר state מקודד בכתובת URL, ולכן האפליקציה צריכה לטפל בתווים בריחה (escape) ולנתח אותו כ-JSON. אפליקציות יכולות לזהות את הערך create בפרמטר state כדי לאמת בקשה ליצירת קובץ.

דוגמה לנתוני מצב ב-JSON של כתובת URL חדשה

פרטי state של כתובת URL חדשה הם:

{
  "action":"create",
  "folderId":"FOLDER_ID",
  "folderResourceKey":"FOLDER_RESOURCE_KEY",
  "userId":"USER_ID"
}

דוגמה לנתוני מצב ב-JSON של כתובת URL פתוחה

פרטי state של כתובת URL פתוחה הם:

{
  "ids": ["ID"],
  "resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
  "action":"open",
  "userId":"USER_ID"
}

המזהים ומפתחות המשאבים משמשים לאחזור מטא-נתונים של קבצים ולהורדת תוכן של קבצים. אחרי שהאפליקציה קיבלה את מזהה הקובץ ואסימון גישה, היא יכולה לבדוק את ההרשאות, לאחזר את המטא-נתונים של הקובץ ולהוריד את תוכן הקובץ כפי שמתואר ב-method files.get.

הערה: כל האפליקציות, כולל אפליקציות שפותחות קבצים מקיצורי דרך ומקיצורי דרך של צד שלישי, צריכות לבצע קריאה ל-method files.get כדי לבדוק את הרשאות המשתמש במסמך. אפליקציות צריכות להזהיר משתמשים עם הרשאת קריאה בלבד כשהם פותחים קובץ שהם לא יכולים לערוך או לשמור (במקום לתת להם לבזבז זמן בעריכה ואז להציג הודעת שגיאה בשמירה).

נושאים קשורים

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