Przewodnik porównawczy interfejsu Drive API v2 i v3

Najnowsza wersja interfejsu Google Drive API to v3. W wersji 3 wydajność jest lepsza, bo wyszukiwania zwracają tylko podzbiór pól. Używaj bieżącej wersji, chyba że potrzebujesz kolekcji v2. Jeśli używasz wersji v2, rozważ migrację do wersji v3. Aby przeprowadzić migrację, zapoznaj się z artykułem Migracja do interfejsu Drive API w wersji 3. Pełną listę różnic w wersjach znajdziesz w dokumentacji porównawczej interfejsów Drive API w wersjach 2 i 3.

Jeśli chcesz nadal używać wersji 2, zapoznaj się z poprawką do interfejsu Guide to Drive API (wersja 2), aby dowiedzieć się, jak zmienić niektóre instrukcje w przewodnikach dla tej wersji – dla deweloperów wersji 2.

Aby dowiedzieć się więcej o ulepszeniach interfejsu Drive API w wersji 3, obejrzyj ten film, w którym inżynierowie Google omawiają nowy interfejs API.

Ulepszenia wersji 3

W celu optymalizacji wydajności i uproszczenia działania interfejsu API w wersji 3 wprowadziliśmy te ulepszenia w porównaniu z poprzednią wersją:

  • Domyślnie wyszukiwanie plików i dysków współdzielonych nie zwraca pełnych zasobów. Zwracany jest tylko podzbiór często używanych pól. Więcej informacji o metodzie fields znajdziesz w opisie metod files.list i drives.list.
  • Prawie wszystkie metody zwracające odpowiedź wymagają teraz parametru fields. Listę wszystkich metod wymagających atrybutu fields znajdziesz w dokumentacji interfejsu Drive API.
  • Zasoby ze zduplikowanymi możliwościami zostały usunięte. Oto kilka przykładów:
    • Metoda files.list działa tak samo jak kolekcje Children i Parents, dlatego 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, który zwraca dane aplikacji za pomocą metod files.list i changes.list, ale spowalnia to wydajność. W wersji 3 ustawiasz zakres drive.appdata oraz ustawiasz parametr zapytania spaces=appDataFolder tak, aby żądał danych aplikacji.
  • Wszystkie operacje aktualizacji używają parametru PATCH zamiast PUT.
  • Aby wyeksportować Dokumenty Google, użyj metody files.export.
  • Metoda changes.list działa inaczej. Zamiast identyfikatorów zmian używaj nieprzezroczystych tokenów stron. Aby sondować kolekcję 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 określające pola, których nie można zapisać.
  • Pola exportFormats i importFormats (wersja 2) w zasobie about to listy dozwolonych formatów importu lub eksportu. W wersji 3 są to mapy typów MIME możliwych celów na wszystkie obsługiwane operacje importu i eksportu.
  • Aliasy appdata i appfolder w wersji 2 są teraz appDataFolder w wersji 3.
  • Zasób properties został usunięty z wersji 3. Zasób files ma pole properties zawierające prawdziwe pary klucz-wartość. Pole properties zawiera właściwości publiczne, a pole appProperties zawiera właściwości prywatne, więc to pole jest niepotrzebne.
  • 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 ustawisz pole setModifiedDate.
  • Pole viewedByMeTime w zasobie files nie jest aktualizowane automatycznie.
  • Aby zaimportować formaty Dokumentów Google, ustaw odpowiedni docelowy mimeType w treści zasobu. W wersji 2 masz ustawioną wartość ?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 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 za pomocą polecenia children.delete możesz usunąć plik podrzędny z folderu nadrzędnego.
    • W wersji 3 należy używać files.update w elemencie podrzędnym z ?removeParents=parent_id w adresie URL.

Inne różnice

Nazwy pól i parametrów są różne w wersji 3. Oto kilka przykładów:

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