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

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

הפעלת Drive API

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

כדי להתחיל בשילוב עם ממשק המשתמש של Google Drive, צריך להפעיל את ה-API של Drive. כך תקבלו גישה ל-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. (אופציונלי) מזינים שם בשדה Application name (שם האפליקציה). שם האפליקציה מוצג למשתמשים בכרטיסייה 'ניהול אפליקציות' בהגדרות של Drive.
5. (אופציונלי) מזינים תיאור קצר של שורה אחת בשדה Short description. התיאור הקצר מוצג למשתמשים בכרטיסייה 'ניהול אפליקציות' בהגדרות Drive.
6. (אופציונלי) מזינים תיאור מלא בשדה Long description.

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

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

8. כדי להשתמש בפריט התפריט 'פתיחה באמצעות' בממשק המשתמש של Drive, מזינים את כתובת ה-URL של האפליקציה בשדה כתובת 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 ולאפשר למשתמשים ליצור קובץ באמצעות האפליקציה, מסמנים את התיבה יצירת קבצים. השדות כתובת URL חדשה ושם המסמך (אופציונלי) מופיעים.

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

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

    הערה: משאירים את השדה Document name (שם המסמך) ריק. השדה הזה כבר לא בשימוש.

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

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

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

בקשה להיקף drive.install

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

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

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

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

הפרמטר state

כברירת מחדל, הפרמטר state מצורף גם לכתובת ה-URL לפתיחה וגם לכתובת ה-URL החדשה כדי להעביר נתונים מממשק המשתמש של Drive לאפליקציה. הפרמטר הזה מכיל מחרוזת בקידוד JSON עם משתני תבנית ונתונים על הבקשה לאפליקציה. המשתנים הכלולים תלויים בסוג כתובת ה-URL שבה נעשה שימוש (כתובת URL לפתיחה או כתובת 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, כך שהאפליקציה צריכה לטפל בתוויות הבריחה ולנתח אותו כ-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"
}

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

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

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

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