Zwracanie określonych pól

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

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

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

Jak działa parametr fields

Parametr fields używa FieldMask do filtrowania odpowiedzi. Maski pól służą do określania podzbioru pól, które powinny zostać zwrócone w odpowiedzi na żądanie. Używanie maski pól to dobra praktyka projektowania, która pozwala uniknąć żądania niepotrzebnych danych, co z kolei pomaga uniknąć niepotrzebnego czasu przetwarzania.

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

W przypadku wszystkich metod zasobów about, approvals, 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 "Invalid field selection 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 terminach zapytań dotyczących plików znajdziesz w sekcji Terminy i operatory zapytań.

Reguły formatowania parametru pola

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 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 sekcji 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 w obiekcie, użyj gwiazdki (*) jako symbolu wieloznacznego w wyborze pola. Na przykład 'permissions/permissionDetails/*' wybiera wszystkie dostępne pola szczegółów uprawnień dla każdego uprawnienia. Pamiętaj, że użycie symbolu wieloznacznego może negatywnie wpłynąć na wydajność żądania.

  • Nie możesz wybierać poszczególnych elementów mapy, jeśli ich klucze zawierają znaki specjalne (np. ukośniki / lub kropki .). Na przykład próba wybrania konkretnego klucza formatu eksportu w exportLinks za pomocą fields=exportLinks/application/pdf powoduje błąd HTTP 400 Bad Request , ponieważ parser ścieżki interpretuje / jako ogranicznik właściwości zagnieżdżonej. Aby pobrać pary klucz-wartość ze znakami specjalnymi w kluczach, poproś o całą mapę (np. fields=exportLinks) i odfiltruj wyniki po stronie klienta.

Żądanie

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

Gdy 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 (zasób zagnieżdżony) 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ć kilka pól, użyj listy oddzielonej przecinkami. Na przykład files.list z fields=files(id,name,createdTime,modifiedTime,size).

Aby określić pola zagnieżdżone w tablicach lub obiektach zagnieżdżonych, użyj zagnieżdżonych nawiasów. Aby na przykład wyświetlić listę plików z ich identyfikatorami, nazwami i zagnieżdżonymi szczegółami właściciela (nazwą wyświetlaną i adresem e-mail), a także pobrać token następnej strony na potrzeby podziału na strony: files.list z fields=nextPageToken,files(id,name,owners(displayName,emailAddress)).

Żą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ź 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"
    }
  ]
}

Alternatywne parametry systemowe

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