Zwracanie określonych pól

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

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

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 żą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.

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

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

Aby sprawdzić, 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. Więcej informacji o wyszukiwanych słowach dotyczących plików znajdziesz w sekcji Wyszukiwane słowa i operatory.

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 symbolu wieloznacznego 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"
    }
  ]
}