Przewodnik porównawczy interfejsu Drive API v2 i v3

Najnowsza wersja interfejsu Google Drive API to 3. Wersja 3 działa lepiej, ponieważ wyszukiwanie zwraca tylko część pól. Używaj bieżącej wersji, chyba że potrzebujesz kolekcji v2. Jeśli używasz wersji 2, rozważ przejście na wersję 3. Aby dowiedzieć się, jak przeprowadzić migrację, przeczytaj artykuł Migracja do interfejsu Drive API w wersji 3. Pełną listę różnic w wersjach znajdziesz w porównaniu interfejsów Drive API v2 i 3.

Jeśli chcesz nadal korzystać z wersji 2, zapoznaj się z poprawką dotyczącą Guide to Drive API w wersji 2, aby dowiedzieć się, jak zaktualizować niektóre instrukcje w przewodnikach po wersji 3.

Aby dowiedzieć się więcej o ulepszeniach interfejsu Drive API w wersji 3, obejrzyj ten film autorstwa inżynierów Google omawiających nowy wygląd interfejsów API.

Ulepszenia 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ą:

  • Wyszukiwanie plików i dysków współdzielonych domyślnie nie zwraca pełnych zasobów. Zwrócony jest tylko podzbiór często 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.
  • Zasoby ze zduplikowanymi funkcjami zostały usunięte. Oto kilka przykładów:
    • Metoda files.list ma takie same funkcje jak kolekcje Children i Parents, więc została usunięta z wersji 3.
    • Metody Realtime.* zostały usunięte.
  • Dane aplikacji nie są domyślnie zwracane w wynikach wyszukiwania. W wersji 2 możesz ustawić zakres drive.appdata, co zwraca dane aplikacji z metod files.list i changes.list, ale spowalnia to działanie. W wersji 3 ustawiasz zakres drive.appdata oraz parametr zapytania spaces=appDataFolder, aby żądać danych aplikacji.
  • Wszystkie operacje aktualizacji używają metody PATCH zamiast PUT.
  • Aby wyeksportować Dokumenty Google, użyj metody files.export.
  • Sposób działania metody changes.list jest inny. Zamiast identyfikatorów zmian używaj nieprzezroczystych tokenów stron. Aby odpytać zbieranie zmian, najpierw wywołaj metodę changes.getStartPageToken dla wartości początkowej. W przypadku kolejnych zapytań metoda changes.list zwraca wartość newStartPageToken.
  • Metody aktualizacji odrzucają teraz żądania, które zawierają pola, których nie można zapisać.
  • Pola exportFormats i importFormats w wersji 2 w zasobie about to listy dozwolonych formatów importu i eksportu. W wersji 3 są to mapy typów MIME możliwych celów na wszystkie obsługiwane importy i eksporty.
  • Aliasy appdata i appfolder w wersji 2 mają teraz postać appDataFolder w wersji 3.
  • Zasób properties został usunięty z wersji 3. Zasób files ma pole properties, które zawiera prawdziwe pary klucz-wartość. Pole properties zawiera właściwości publiczne, a pole appProperties – właściwości 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ć tylko podczas aktualizacji, jeśli ustawiono pole setModifiedDate.
  • Pole viewedByMeTime w zasobie files nie jest automatycznie aktualizowane.
  • Aby importować formaty Dokumentów Google, ustaw odpowiednią wartość docelową mimeType w treści zasobu. W wersji 2 ustawiasz ?convert=true.
  • Jeśli format nie jest obsługiwany, operacje importowania zwracają błąd 400.
  • Czytelnicy i komentujący nie mogą wyświetlać uprawnień.
  • Alias me uprawnień został usunięty.
  • Niektóre funkcje były dostępne jako część zasobu żądania, ale zamiast tego są dostępne jako parametr żądania. Na przykład:
    • W wersji 2 możesz za pomocą children.delete usunąć plik podrzędny z folderu nadrzędnego.
    • W wersji 3 użyj files.update w elemencie podrzędnym z tagiem ?removeParents=parent_id w adresie URL.

Inne różnice

W wersji 3 nazwy pól i parametrów są inne. Oto kilka przykładów:

  • Właściwość name zastępuje właściwość title w zasobie files.
  • Time to sufiks dla wszystkich pól daty i godziny, a nie Date.
  • Operacje listy nie korzystają z pola items do przechowywania zbioru wyników. Typ zasobu zawiera pole na wyniki (np. files lub changes).