Zwracanie określonych pól

Aby zwrócić dokładnie te pola, których potrzebujesz, i zwiększyć wydajność, użyj w wywołaniu metody parametru fields system.

Parametr fields używa FieldMask do filtrowania odpowiedzi. Maski pól służą do określania podzbioru pól, które powinny zwrócić żądanie. Korzystanie z maski pola to dobra praktyka projektowania, która pozwala uniknąć wysyłania niepotrzebnych danych, a tym samym zbędę niepotrzebnego czasu przetwarzania.

Domyślnie serwer zwraca zestaw pól związanych z zapytanym zasobem. Na przykład metoda get() zasobu files może zwracać tylko wartości id, name i mimeType. Metoda get() zasobu permissions zwraca inny zestaw pól domyślnych.

Gdy serwer przetworzy prawidłowe żądanie z parametrem fields, razem z żądanymi danymi wyśle kod stanu HTTP 200 OK. Jeśli parametrfields zawiera błąd lub jest nieprawidłowy z innego powodu, serwer zwraca kod stanu HTTP 400 Bad Request i komunikat o błędzie z informacjami o problemach z wybranymi polami. Na przykład: files.list(fields='files(id,capabilities,canAddChildren)') powoduje błąd „Nieprawidłowy wybór pola canAddChildren”. W tym przykładzie prawidłowy parametr fields to files.list(fields='files(id,capabilities/canAddChildren)').

Aby dowiedzieć się, które pola możesz zwrócić za pomocą parametru fields, otwórz stronę dokumentacji zasobu, którego dotyczy zapytanie. Na przykład, jakie pola można zwrócić w przypadku pliku, zapoznaj się z dokumentacją zasobów files.

Reguły formatowania parametrów pól

Format wartości parametru żądania fields jest oparty na składni XPath. Poniżej znajdziesz reguły formatowania parametru fields. Wszystkie te reguły zawierają przykłady związane z metodą files.get().

  • Użyj listy rozdzielanej przecinkami, aby wybrać kilka pól, np. 'name, mimeType'.

  • Użyj a/b, aby wybrać pole b zagnieżdżone w polu a, np. 'capabilities/canDownload'. Więcej informacji znajdziesz w artykule Pobieranie pól zasobu zagnieżdżonego.

  • Użyj selektora podrzędnego, aby zażądać zbioru konkretnych podrzędnych pól tablic lub obiektów. W tym celu umieść wyrażenia w nawiasach „()”. Na przykład: 'permissions(id)' zwraca tylko identyfikator uprawnienia dla każdego elementu w tablicy uprawnień.

  • Aby zwrócić wszystkie pola obiektu, użyj gwiazdki (*) jako symbolu wieloznacznego w wybranych polach. Na przykład 'permissions/permissionDetails/*' wybiera wszystkie dostępne pola szczegółów uprawnień na podstawie uprawnienia. Pamiętaj, że użycie symboli wieloznacznych może mieć negatywny wpływ na skuteczność żądania.

Pokaż przykład

Wyślij prośbę

W tym przykładzie podajemy parametr ścieżki identyfikatora pliku i kilka pól jako parametr zapytania w żądaniu. Odpowiedź zwraca wartości pól identyfikatora pliku.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

Odpowiedź

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

Pobieranie pól zasobu zagnieżdżonego

Jeśli pole odwołuje się do innego zasobu, możesz określić, które pola zasobu zagnieżdżonego mają zostać pobrane.

Aby na przykład pobrać pole role (zagnieżdżony zasób) zasobu permissions, użyj dowolnej z tych opcji:

  • permissions.get() z fields=role.
  • permissions.get() z fields=*, aby wyświetlić wszystkie pola permissions.
  • files.get() z fields=permissions(role) lub fields=permissions/role.
  • files.get() z parametrem fields=permissions, aby wyświetlić wszystkie pola permissions.
  • changes.list() z fields=changes(file(permissions(role))).

Aby pobrać wiele pól, użyj listy rozdzielonej przecinkami. na przykład files.list() z fields=files(id,name,createdTime,modifiedTime,size).

Pokaż przykład

Wyślij prośbę

W tym przykładzie jako parametry zapytania podajemy parametr ścieżki identyfikatora pliku i kilka pól, w tym niektóre pola zasobu uprawnień zagnieżdżonego. Odpowiedź zwraca wartości pól dla identyfikatora pliku.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

Odpowiedź

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}