Przewodnik porównawczy interfejsu Drive API v2 i v3

Najnowsza wersja interfejsu Google Drive API to v3. Wersja 3 działa lepiej, 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 dokumentacji interfejsu Drive API.
  • Usunęliśmy zasoby, które miały zduplikowane możliwości. 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, który zwraca dane aplikacji z metody files.list i metody changes.list, ale spowalnia 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 importowania zwracają błąd 400, jeśli format nie jest obsługiwany.
  • Czytelnicy i komentatorzy 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 tagiem ?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).