מדריך להשוואה של Drive API v2 ו-v3
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
הגרסה האחרונה של Google Drive API היא גרסה 3. הביצועים בגרסה 3 טובים יותר כי החיפושים מחזירים רק קבוצת משנה של שדות. צריך להשתמש בגרסה הנוכחית, אלא אם אתם צריכים את אוסף v2. אם אתם משתמשים בגרסה 2, כדאי לשקול מעבר לגרסה 3. הוראות למיגרציה מופיעות במאמר מעבר ל-Drive API v3. רשימה מלאה של ההבדלים בין הגרסאות מופיעה בהשוואה בין Drive API גרסה 2 לגרסה 3.
אם אתם רוצים להמשיך להשתמש בגרסה 2, תוכלו לעיין במדריך לתיקון 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).
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-08-29 (שעון UTC).
[null,null,["עדכון אחרון: 2025-08-29 (שעון UTC)."],[],[],null,["# Drive API v2 and v3 comparison guide\n\nThe latest Google Drive API version is v3. The performance in v3 is better because\nsearches only return a subset of fields. Use the current version unless you need\nthe [v2](/workspace/drive/api/v2/reference) collection. If you're using v2, consider\nmigrating to v3. To migrate, see [Migrate to Drive API v3](/workspace/drive/api/guides/migrate-to-v3). For a complete list of version differences, see\nthe [Drive API v2 and v3 comparison\nreference](/workspace/drive/api/guides/v2-to-v3-reference).\n\nIf you want to continue to use v2, see the [Guide to Drive API v2](/workspace/drive/api/guides/v2-guide) amendment to learn how some instructions in the v3\nguides must be amended for v2 developers.\n\nTo learn more about Drive API v3 improvements, you can watch the\nfollowing video by Google engineers discussing the new API design. \n\nV3 improvements\n---------------\n\nTo optimize performance and reduce API behavior complexity, v3 provides these\nimprovements over the previous API version:\n\n- Searches for files and shared drives don't return full resources by default, only a subset of commonly used fields gets returned. For more details on `fields`, see the [`files.list`](/workspace/drive/api/v3/reference/files/list) method and the [`drives.list`](/workspace/drive/api/v3/reference/drives/list) method.\n- Almost all methods that return a response now require the `fields` parameter. For a list of all methods requiring `fields`, see the [Drive API reference](/workspace/drive/api/v3/reference).\n- Resources that have duplicate capabilities were removed. Some examples:\n - The `files.list` method accomplishes the same functionality as the `Children` and `Parents` collections, so they're removed from v3.\n - The `Realtime.*` methods have been removed.\n- App Data isn't returned by default in searches. In v2, you can set the `drive.appdata` scope, and it returns application data from the `files.list` method and the [`changes.list`](/workspace/drive/api/v2/reference/changes/list) method, but it slows performance. In v3, you set the `drive.appdata` scope, and also set the query parameter `spaces=appDataFolder` to request application data.\n- All update operations use PATCH instead of PUT.\n- To export Google Documents, use the [`files.export`](/workspace/drive/api/v2/reference/files/export) method.\n- The `changes.list` method behavior is different. Instead of change IDs, use opaque page tokens. To poll the change collection, first call the [`changes.getStartPageToken`](/workspace/drive/api/v2/reference/changes/getStartPageToken) method for the initial value. For subsequent queries, the `changes.list` method returns the `newStartPageToken` value.\n- Update methods now reject requests that specify non-writable fields.\n- The v2 `exportFormats` and `importFormats` fields in the [`about`](/workspace/drive/api/reference/rest/v3/about) resource are lists of allowable import or export formats. In v3, they're MIME type maps of possible targets to all supported imports or exports.\n- The v2 `appdata` and `appfolder` aliases are now `appDataFolder` in v3.\n- The `properties` resource is removed from v3. The [`files`](/workspace/drive/api/v3/reference/files) resource has the `properties` field that contains true key-value pairs. The `properties` field contains public properties, and the `appProperties` field contains private properties, so the visibility field isn't needed.\n- The `modifiedTime` field in the `files` resource updates the last time anyone modified the file. In v2, the `modifiedDate` field was only mutable on update if you set the `setModifiedDate` field.\n- The `viewedByMeTime` field in the `files` resource doesn't automatically update.\n- To import Google Docs formats, you set the appropriate target `mimeType` in the resource body. In v2, you set `?convert=true`.\n- Import operations return a 400 error if the format isn't supported.\n- Readers and commenters can't view permissions.\n- The `me` alias for permissions is removed.\n- Some functionality was available as part of the request resource but is instead available as a request parameter. For example:\n - In v2, you can use `children.delete` to remove a child file from a parent folder.\n - In v3, you use`files.update` on the child with `?removeParents=parent_id` in the URL.\n\nOther differences\n-----------------\n\nFields and parameter names are different in v3. Some examples include:\n\n- The `name` property replaces `title` in the `files` resource.\n- `Time` is the suffix for all date and time fields instead of `Date`.\n- List operations don't use the `items` field to contain the result set. The resource type provides a field for the results (such as `files` or `changes`)."]]
