Przewodnik porównawczy interfejsu Drive API v2 i v3
Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Najnowsza wersja interfejsu Google Drive API to v3. Wersja 3 jest wydajniejsza, ponieważ wyszukiwania zwracają tylko podzbiór pól. Korzystaj z bieżącej wersji, chyba że potrzebujesz kolekcji v2. Jeśli używasz wersji 2, rozważ migrację do wersji 3. Aby przeprowadzić migrację, zapoznaj się z artykułem Migracja do interfejsu Drive API w wersji 3. Pełną listę różnic między wersjami znajdziesz w porównaniu interfejsów Drive API w wersji 2 i 3.
Jeśli chcesz nadal korzystać z wersji 2, zapoznaj się z dodatkiem do przewodnika po interfejsie Drive API w wersji 2, aby dowiedzieć się, jak deweloperzy korzystający z wersji 2 powinni zmodyfikować niektóre instrukcje w przewodnikach po wersji 3.
Aby dowiedzieć się więcej o ulepszeniach w interfejsie Drive API w wersji 3, obejrzyj poniższy film, w którym inżynierowie Google omawiają nowy projekt interfejsu API.
Ulepszenia w wersji 3
Aby zoptymalizować wydajność i zmniejszyć złożoność działania interfejsu API, wersja 3 zawiera te ulepszenia w porównaniu z poprzednią wersją interfejsu API:
Wyszukiwanie plików i dysków współdzielonych domyślnie nie zwraca pełnych zasobów, tylko podzbiór najczęściej używanych pól. Więcej informacji o fields znajdziesz w metodach files.list i drives.list.
Prawie wszystkie metody, które zwracają odpowiedź, wymagają teraz parametru fields. Listę wszystkich metod wymagających fields znajdziesz w
przewodniku po interfejsie Drive API.
Zasoby, które mają zduplikowane możliwości, zostały usunięte. Oto kilka przykładów:
Metoda files.list ma takie same funkcje jak kolekcje Children i Parents, więc zostały one usunięte z wersji 3.
Metody Realtime.* zostały usunięte.
Dane aplikacji nie są domyślnie zwracane w wyszukiwaniach. W wersji 2 możesz ustawić zakres drive.appdata, a funkcja zwraca dane aplikacji z metody files.list i metody changes.list, ale spowalnia to działanie. W wersji 3 ustawiasz zakres drive.appdata, a także parametr zapytania spaces=appDataFolder, aby poprosić o dane aplikacji.
Wszystkie operacje aktualizacji używają metody PATCH zamiast PUT.
Aby wyeksportować dokumenty Google, użyj metody files.export.
Działanie metody changes.list jest inne. Zamiast identyfikatorów zmian używaj nieprzejrzystych tokenów strony. Aby sprawdzić kolekcję zmian, najpierw wywołaj metodę
changes.getStartPageToken
w przypadku wartości początkowej. W przypadku kolejnych zapytań metoda changes.list zwraca wartość newStartPageToken.
Metody aktualizacji odrzucają teraz żądania, które określają pola, w których nie można zapisywać danych.
Pola v2 exportFormats i importFormats w zasobie about to listy dozwolonych formatów importu lub eksportu. W wersji 3 są to mapy typów MIME możliwych miejsc docelowych wszystkich obsługiwanych importów lub eksportów.
Aliasy appdata i appfolder w wersji 2 to teraz appDataFolder w wersji 3.
Zasób properties zostanie usunięty z wersji 3. Zasób
files ma pole properties, które zawiera prawidłowe pary klucz-wartość. Pole properties zawiera usługi publiczne, a pole appProperties – usługi prywatne, więc pole widoczności nie jest potrzebne.
Pole modifiedTime w zasobie files aktualizuje czas ostatniej modyfikacji pliku przez dowolną osobę. W wersji 2 pole modifiedDate można było zmieniać podczas aktualizacji tylko wtedy, gdy ustawiono pole setModifiedDate.
Pole viewedByMeTime w zasobie files nie jest aktualizowane automatycznie.
Aby zaimportować formaty Dokumentów Google, ustaw odpowiedni cel mimeTypew treści zasobu. W wersji 2 ustawiasz ?convert=true.
Operacje importu zwracają błąd 400, jeśli format nie jest obsługiwany.
Czytelnicy i komentujący nie mogą wyświetlać uprawnień.
Alias me dla uprawnień zostanie usunięty.
Niektóre funkcje były dostępne w ramach zasobu żądania, ale są teraz dostępne jako parametr żądania. Na przykład:
W wersji 2 możesz użyć metody children.delete, aby usunąć plik podrzędny z folderu nadrzędnego.
W wersji 3 używasz tagu files.update w przypadku elementu podrzędnego z parametrem ?removeParents=parent_id w adresie URL.
Inne różnice
Pola i nazwy parametrów w wersji 3 są inne. Oto kilka przykładów:
Właściwość name zastępuje właściwość title w zasobie files.
Time jest przyrostkiem wszystkich pól daty i godziny zamiast Date.
Operacje na listach nie używają pola items do przechowywania zestawu wyników. Typ zasobu zawiera pole wyników (np. files lub changes).
[[["Łatwo zrozumieć","easyToUnderstand","thumb-up"],["Rozwiązało to mój problem","solvedMyProblem","thumb-up"],["Inne","otherUp","thumb-up"]],[["Brak potrzebnych mi informacji","missingTheInformationINeed","thumb-down"],["Zbyt skomplikowane / zbyt wiele czynności do wykonania","tooComplicatedTooManySteps","thumb-down"],["Nieaktualne treści","outOfDate","thumb-down"],["Problem z tłumaczeniem","translationIssue","thumb-down"],["Problem z przykładami/kodem","samplesCodeIssue","thumb-down"],["Inne","otherDown","thumb-down"]],["Ostatnia aktualizacja: 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`)."]]
