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

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

הפעלת Drive API

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

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

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

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

   • כתובת ה-URL הזו חייבת להכיל שם דומיין שמוגדר במלואו. localhost לא עובד.
   • כתובת ה-URL הזו צריכה להיות נגישה למשתמשים המיועדים של האפליקציה. אם יש לכם כמה גרסאות של האפליקציה, למשל גרסה אחת לשימוש ציבורי וגרסה אחת לשימוש מוגבל למשתמשים נבחרים, לכל גרסה צריכה להיות כתובת URL ייחודית. לאחר מכן תוכלו ליצור הגדרות אפליקציה שונות לכל גרסה.
   • עליכם לאמת את הבעלות על כתובת ה-URL הזו כדי שתוכלו להוסיף את האפליקציה שלכם ל-Google Workspace Marketplace.
   • כברירת מחדל, פרמטר השאילתה 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, מסמנים את התיבה ייבוא.

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.