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

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

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

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

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

כדי לשפר את הביצועים ולצמצם את המורכבות של התנהגות ה-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 Docs, משתמשים ב-method‏ files.export.
• התנהגות השיטה changes.list שונה. במקום לשנות את המזהים, כדאי להשתמש באסימוני דפים אטומים. כדי לבדוק את אוסף השינויים, קודם צריך להפעיל את השיטה changes.getStartPageToken כדי לקבל את הערך הראשוני. בשאילתות הבאות, השיטה changes.list מחזירה את הערך newStartPageToken.
• שיטות העדכון דוחים עכשיו בקשות שמציינות שדות שלא ניתן לכתוב בהם.
• השדות exportFormats ו-importFormats בגרסה 2 במשאב 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).