Zwracanie konkretnych pól pliku

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ć pole b zagnieżdżone w polu a, 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.

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

{
  "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 lub fields=*.
• files.get za pomocą fields=permissions(role) lub fields=permissions/role.
• files.get z atrybutem fields=permissions oznaczający wszystkie pola zagnieżdżonego zasobu.
• changes.list i fields=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).

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

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