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 żądanie powinno zwrócić. 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 parametr fields zawiera błąd lub jest nieprawidłowy z innego powodu, serwer zwróci kod stanu HTTP 400 Bad Request i komunikat o błędzie z wyjaśnieniem, na czym polega problem 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. Aby na przykład sprawdzić, jakie pola możesz zwrócić w przypadku pliku, zapoznaj się z dokumentacją zasobu 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().

  • Aby wybrać wiele pól, np. 'name, mimeType', użyj listy rozdzielonej przecinkami.

  • 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 znaku zapytania może negatywnie wpłynąć na wydajność żą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 dla 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 jednej 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 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"
    }
  ]
}