Zwracanie określonych pól

Z tego dokumentu dowiesz się, jak używać parametru fields na Dysku Google.

Aby uzyskać tylko potrzebne pola i zwiększyć wydajność, użyj w wywołaniu metody fields parametru system.

Informacje o innych parametrach systemowych, które mają zastosowanie do interfejsu Drive API, znajdziesz w artykule Alternatywne parametry systemowe.

Jak działa parametr fields

Parametr fields używa elementu FieldMask do filtrowania odpowiedzi. Maski pól służą do określania podzbioru pól, które powinny być zwracane w odpowiedzi na żądanie. Używanie maski pola to dobra praktyka projektowania, która pozwala uniknąć żądania niepotrzebnych danych, co z kolei pomaga skrócić czas przetwarzania.

Jeśli nie określisz parametru fields, serwer zwróci domyślny zestaw pól specyficznych dla danej metody. Na przykład metoda list w metodzie files zwraca tylko pola kind, id, name i mimeType. Metoda get w zasobie permissions zwraca inny zestaw domyślnych pól.

W przypadku wszystkich metod zasobów about, comments (z wyjątkiem delete) i replies (z wyjątkiem delete) musisz ustawić parametr fields. Te metody nie zwracają domyślnego zestawu pól.

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”. Prawidłowy parametr fields w tym przykładzie to files.list(fields='files(id,capabilities/canAddChildren)').

Aby określić pola, które możesz zwrócić za pomocą parametru fields, otwórz stronę dokumentacji zasobu, o który wysyłasz zapytanie. Aby na przykład sprawdzić, jakie pola możesz zwrócić w przypadku pliku, zapoznaj się z dokumentacją zasobu files. Więcej informacji o zapytaniach dotyczących konkretnych plików znajdziesz w artykule Zapytania i operatory wyszukiwania.

Reguły formatowania parametrów pól

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

  • Użyj listy oddzielonej przecinkami, aby wybrać wiele 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 zagnieżdżonego zasobu.

  • 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 „()”. Przykład: 'permissions(id)' zwraca tylko identyfikator uprawnienia każdego elementu w tablicy uprawnień.

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

Żądanie

W tym przykładzie podajemy parametr ścieżki identyfikatora pliku i kilka pól jako parametr zapytania w żądaniu. Odpowiedź zawiera 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 zagnieżdżonego zasobu

Gdy pole odnosi się do innego zasobu, możesz określić, które pola zagnieżdżonego zasobu 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).

Żądanie

W tym przykładzie podajemy parametr ścieżki identyfikatora pliku i kilka pól, w tym niektóre pola zagnieżdżonego zasobu uprawnień, jako parametr zapytania w żądaniu. Odpowiedź zawiera 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"
    }
  ]
}

Alternatywne parametry systemu

Parametry zapytania, które mają zastosowanie do wszystkich operacji interfejsu Google Drive API, są opisane w sekcji Parametry systemowe.