מדריך להשוואה של Drive API v2 ו-v3

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

אם אתם רוצים להמשיך להשתמש בגרסה 2, כדאי לעיין בתיקון Guide to Drive API v2 כדי ללמוד איך מפתחים שמשתמשים בגרסה 2 צריכים לשנות חלק מההוראות במדריכים לגרסה 3.

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

שיפורים בגרסה 3

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

• חיפושים של קבצים ותיקיות באחסון שיתופי לא מחזירים משאבים מלאים כברירת מחדל, אלא רק קבוצת משנה של שדות נפוצים. פרטים נוספים על fields זמינים במאמר על השיטה files.list ועל השיטה drives.list.
• כמעט בכל השיטות שבהן מוחזרת תשובה נדרש עכשיו הפרמטר fields. רשימה של כל השיטות שדורשות fields מופיעה במאמר בנושא הפניות ל-Drive API.
• הוסרו משאבים עם יכולות כפולות. דוגמאות:
  • השיטה files.list מבצעת את אותה פעולה כמו האוספים Children ו-Parents, ולכן הם הוסרו מגרסה 3.
  • השיטות Realtime.* הוסרו.
• כברירת מחדל, נתוני האפליקציה לא מוחזרים בחיפושים. בגרסה 2, אפשר להגדיר את ההיקף drive.appdata, והיא מחזירה נתוני אפליקציה מהשיטה files.list ומהשיטה changes.list, אבל היא מאטה את הביצועים. בגרסה 3, מגדירים את ההיקף drive.appdata ומגדירים גם את פרמטר השאילתה spaces=appDataFolder כדי לבקש נתוני אפליקציה.
• כל פעולות העדכון משתמשות ב-PATCH במקום ב-PUT.
• כדי לייצא מסמכי Google, משתמשים ב-method‏ files.export.
• ההתנהגות של השיטה changes.list שונה. במקום מזהי שינויים, צריך להשתמש באסימוני דפים אטומים. כדי לבצע שאילתה לאיסוף השינויים, קודם צריך לקרוא לשיטה changes.getStartPageToken כדי לקבל את הערך הראשוני. בשביל שאילתות הבאות, השיטה changes.list מחזירה את הערך newStartPageToken.
• שיטות העדכון דוחות עכשיו בקשות שמציינות שדות שאי אפשר לכתוב בהם.
• השדות v2 exportFormats ו-importFormats במשאב about הם רשימות של פורמטים מותרים לייבוא או לייצוא. בגרסה 3, אלה מיפויים של סוגי MIME של יעדים אפשריים לכל הייבוא או הייצוא הנתמכים.
• הכתובות החלופיות appdata ו-appfolder בגרסה 2 הן עכשיו appDataFolder בגרסה 3.
• המשאב properties הוסר מגרסה 3. למשאב files יש שדה properties שמכיל צמדי מפתח/ערך אמיתיים. השדה properties מכיל מאפיינים ציבוריים, והשדה appProperties מכיל מאפיינים פרטיים, ולכן לא צריך את שדה החשיפה.
• השדה modifiedTime במשאב files מתעדכן בפעם האחרונה שמישהו שינה את הקובץ. בגרסה 2, השדה modifiedDate היה ניתן לשינוי בעדכון רק אם הגדרתם את השדה setModifiedDate.
• השדה viewedByMeTime במשאב files לא מתעדכן באופן אוטומטי.
• כדי לייבא פורמטים של Google Docs, מגדירים את יעד mimeType המתאים בגוף המשאב. בגרסה 2, הגדרתם את ?convert=true.
• פעולות ייבוא מחזירות שגיאה 400 אם הפורמט לא נתמך.
• בעלי הרשאת קריאה ובעלי הרשאת תגובה לא יכולים לראות את ההרשאות.
• הכינוי me להרשאות יוסר.
• חלק מהפונקציות היו זמינות כחלק ממשאב הבקשה, אבל עכשיו הן זמינות כפרמטר בקשה. לדוגמה:
  • בגרסה 2, אפשר להשתמש ב-children.delete כדי להסיר קובץ צאצא מתיקיית הורה.
  • בגרסה 3, משתמשים ב-files.update בפריט הילד עם ?removeParents=parent_id בכתובת ה-URL.

הבדלים אחרים

השדות ושמות הפרמטרים שונים בגרסה 3. הנה כמה דוגמאות:

• המאפיין name מחליף את המאפיין title במשאב files.
• Time הוא הסיומת של כל שדות התאריך והשעה במקום Date.
• בפעולות של רשימה לא נעשה שימוש בשדה items כדי להכיל את קבוצת התוצאות. סוג המשאב מספק שדה לתוצאות (למשל files או changes).