Aby zwrócić dokładnie te pola, których potrzebujesz, i poprawić wydajność, użyj w wywołaniu metody parametru zapytania fields
.
Domyślnie serwer wysyła zbiór pól specyficznych dla zasobu, którego dotyczy zapytanie. Na przykład metoda files.get
może zwracać tylko wartości id
, name
i mimeType
dla zasobu files
. Metoda permissions.get
zwraca inny zestaw domyślnych pól dla zasobu permissions
.
Gdy serwer przetworzy prawidłowe żądanie z parametrem zapytania fields
, razem z żądanymi danymi odsyła kod stanu HTTP 200 OK
. Jeśli parametr zapytania dotyczącego pól zawiera błąd lub jest nieprawidłowy z innego powodu, serwer zwraca kod stanu HTTP 400 Bad Request
i komunikat o błędzie z informacją, co jest nie tak z wybranymi polami. Na przykład files.list(fields='files(id,capabilities,canAddChildren)')
zwraca błąd „Nieprawidłowy wybór pola canAddChildren”. Prawidłowy parametr zapytania w tym przykładzie to files.list(fields='files(id,capabilities/canAddChildren)')
.
Aby określić pola, które możesz zwrócić przy użyciu parametru fields
, otwórz stronę dokumentacji zasobu, którego dotyczy zapytanie. Na przykład informacje o tym, które pola można zwrócić w przypadku pliku, znajdziesz w dokumentacji zasobów files
.
Reguły formatu parametrów pól
Format wartości parametru żądania pól jest luźno oparty na składni XPath. Poniżej znajdziesz reguły formatowania parametru fields
. Wszystkie te reguły korzystają z przykładów związanych z metodą files.get
.
Użyj listy oddzielonej przecinkami, aby wybrać większą liczbę pól, np.
'name, mimeType'
.Użyj
a/b
, aby wybrać poleb
zagnieżdżone w polua
, np.'capabilities/canDownload'
. Więcej informacji znajdziesz w artykule o pobieraniu 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 „()”. Na przykład
'permissions(id)'
zwraca tylko identyfikator uprawnień dla każdego elementu w tablicy uprawnień.Aby zwrócić wszystkie pola w obiekcie, użyj symbolu wieloznacznego (*) jako symbolu wieloznacznego w wyborze pól. Na przykład
'permissions/permissionDetails/*'
wybiera w przypadku każdego uprawnienia wszystkie dostępne pola szczegółów uprawnień. Pamiętaj, że użycie tego symbolu wieloznacznego może negatywnie wpłynąć na wydajność żądania.
Pokaż przykład
Wyślij prośbę
W tym przykładzie w żądaniu podajemy parametr ścieżki identyfikatora pliku i wiele pól jako parametr zapytania. 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 } }
Pobierz pola 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 dowolnej z tych opcji:
permissions.get
za pomocąfields=role
lubfields=*
.files.get
za pomocąfields=permissions(role)
lubfields=permissions/role
.files.get
z atrybutemfields=permissions
oznaczający wszystkie pola zagnieżdżonego zasobu.changes.list
ifields=changes(file(permissions(role)))
.
Aby pobrać wiele pól, użyj listy rozdzielanej przecinkami. Na przykład: files.list
z parametrem fields=files(id,name,createdTime,modifiedTime,size)
.
Pokaż przykład
Wyślij prośbę
W tym przykładzie jako parametr zapytania w żądaniu podajemy parametr ścieżki identyfikatora pliku oraz wiele pól, w tym niektóre pola zagnieżdżonych zasobów uprawnień. Odpowiedź zwraca wartości pól 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" } ] }