W tym dokumencie opisano pewne metody, których możesz użyć, aby poprawić wydajność aplikacji. W niektórych przypadkach do prezentowania ilustracji służą przykłady innych interfejsów API lub ogólne interfejsy API. Jednak te same pojęcia są używane w interfejsie Google Slides API.
Kompresja za pomocą gzip
Prosty i wygodny sposób na zmniejszenie przepustowości wymaganej do każdego żądania to włączenie kompresji gzip. Chociaż wymaga to dodatkowego czasu na skompresowanie wyników, może okazać się bardzo korzystne dla kompromisu z kosztami sieci.
Aby odebrać odpowiedź zakodowaną w formacie gzip, ustaw nagłówek Accept-Encoding
i zmodyfikuj klienta użytkownika, tak aby zawierał ciąg gzip
. Oto przykład poprawnie sformułowanych nagłówków HTTP umożliwiających włączenie kompresji gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)
Praca z częściowymi zasobami
Innym sposobem na zwiększenie skuteczności wywołań interfejsu API jest wysłanie żądania tylko części danych, które Cię interesują. Dzięki temu aplikacja nie musi przesyłać, analizować ani przechowywać niepotrzebnych pól, co pozwala wydajniej wykorzystywać zasoby, w tym sieć, procesor i pamięć.
Częściowa odpowiedź
Po przetworzeniu żądań serwer domyślnie odsyła pełną reprezentację zasobu. Aby uzyskać lepsze wyniki, możesz wysłać do serwera żądanie częściowej odpowiedzi tylko w tych polach, których potrzebujesz.
Aby wysłać częściową odpowiedź, użyj parametru żądania fields
, określając w nim pola, które chcesz zwrócić. Tego parametru możesz używać z każdym żądaniem, które zwraca dane odpowiedzi.
Przykład
Poniższy przykład pokazuje zastosowanie parametru fields
w zwykłym (fikcyjnym) interfejsie API „Demo”.
Proste żądanie: to żądanie HTTP GET
pomija parametr fields
i zwraca pełny zasób.
https://www.googleapis.com/demo/v1
Pełna odpowiedź na zasób: pełne dane zasobu obejmują pola podane poniżej oraz wiele innych, które zostały pominięte ze względu na zwięzłość.
{ "kind": "demo", ... "items": [ { "title": "First title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }, { "title": "Second title", "comment": "Second comment.", "characteristics": { "length": "long", "accuracy": "medium" "followers": [ ], }, "status": "pending", ... }, ... ] }
Żądanie odpowiedzi częściowej: poniższe żądanie tego samego zasobu używa parametru fields
, aby znacząco zmniejszyć ilość zwracanych danych.
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
Odpowiedź częściowa: w odpowiedzi na żądanie powyżej serwer wysyła odpowiedź zawierającą tylko informację o rodzaju i skróconą tablicę elementów zawierającą tylko informacje o tytule i długości.
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
Odpowiedź jest obiektem JSON zawierającym tylko wybrane pola i ich obiekty nadrzędne.
Szczegółowe informacje na temat formatowania parametru fields
znajdziesz poniżej. Opisaliśmy też szczegółowo zawartość odpowiedzi.
Podsumowanie składni parametru Pola
Format wartości parametru żądania fields
jest oparty na składni XPath. Podsumowanie obsługiwanej składni znajdziesz poniżej, a dodatkowe przykłady znajdziesz w tej sekcji.
- Aby wybrać wiele pól, użyj listy rozdzielonej przecinkami.
- Użyj
a/b
, aby wybrać poleb
zagnieżdżone w polua
. Użyja/b/c
, aby wybrać polec
zagnieżdżone w polub
.
Wyjątek: jeśli odpowiedź interfejsu API używa kodu danych i jest zagnieżdżona w obiekcie
data
, który wygląda jakdata: { ... }
, nie dodawaj „data
” do specyfikacjifields
. Uwzględnienie obiektu danych w specyfikacji pól, np.data/a/b
, powoduje błąd. Zamiast tego użyj specyfikacjifields
, takiej jaka/b
. - 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
fields=items(id,author/email)
zwraca tylko identyfikator elementu i adres e-mail autora każdego elementu w tablicy elementów. Możesz też podać jedno pole podrzędne, w którymfields=items(id)
jest odpowiednikiem polafields=items/id
. - Jeśli to konieczne, w wybranych polach używaj symboli wieloznacznych.
Na przykład:
fields=items/pagemap/*
wybiera wszystkie obiekty w mapie strony.
Więcej przykładów użycia parametru field
W poniższych przykładach opisano, jak wartość parametru fields
wpływa na odpowiedź.
Uwaga: tak jak każda wartość parametru zapytania, wartość parametru fields
musi być zakodowana na potrzeby adresu URL. W przykładach w tym dokumencie kodowanie zostało pominięte, aby łatwiej je odczytać.
- Znajdź pola, które chcesz zwrócić, lub wybierz pola.
- Wartość parametru żądania
fields
jest listą pól rozdzielonych przecinkami, a każde pole jest określane względem elementu głównego odpowiedzi. Oznacza to, że jeśli wykonujesz operację na liście, w odpowiedzi otrzymasz kolekcję, która zwykle zawiera tablicę zasobów. Jeśli wykonujesz operację, która zwraca 1 zasób, pola są określane względem tego zasobu. Jeśli wybrane pole jest tablicą (lub jest jej częścią), serwer zwraca wybraną część wszystkich elementów tablicy.
Oto kilka przykładów na poziomie kolekcji:
Przykłady Efekt items
Zwraca wszystkie elementy tablicy, łącznie ze wszystkimi polami w każdym elemencie (nie zwraca żadnych innych pól). etag,items
Zwraca zarówno pole etag
, jak i wszystkie elementy tablicy.items/title
Zwraca tylko pole title
każdego elementu tablicy.
Gdy jest zwracane zagnieżdżone pole, odpowiedź zawiera obiekty nadrzędne. Pola nadrzędne nie zawierają żadnych innych pól podrzędnych, chyba że zostaną wybrane inaczej.context/facets/label
Zwraca tylko pole label
każdego użytkownika tablicyfacets
, która jest zagnieżdżona w obiekciecontext
.items/pagemap/*/title
Zwraca tylko pole title
(jeśli jest obecne) każdego elementu tablicy we wszystkich obiektach podrzędnych obiektupagemap
.
Oto kilka przykładów na poziomie zasobu:
Przykłady Efekt title
Zwraca pole title
żądanego zasobu.author/uri
Zwraca pole podrzędne uri
obiektuauthor
w żądanym zasobie.links/*/href
Zwraca pole href
każdego obiektu podrzędnego względemlinks
. - Aby żądać tylko fragmentów pól, dokonaj wyborów podrzędnych.
- Domyślnie, jeśli żądanie określa określone pola, serwer zwraca wszystkie obiekty lub elementy tablicy w całości. Możesz określić odpowiedź, która zawiera tylko niektóre pola podrzędne. W tym celu użyj składni wyboru podrzędnego „
( )
”, jak pokazujemy w tym przykładzie.Przykład Efekt items(title,author/uri)
Zwraca tylko wartości title
iuri
autora z każdego elementu w tablicy.
Radzenie sobie z odpowiedziami częściowymi
Gdy serwer przetworzy prawidłowe żądanie z parametrem zapytania fields
, razem z żądanymi danymi wyśle kod stanu HTTP 200 OK
. Jeśli parametr zapytania 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 "Invalid field selection a/b"
).
Oto przykładowa odpowiedź częściowa przedstawiona w sekcji wprowadzającej powyżej. Aby określić, które pola zwrócić, żądanie używa parametru fields
.
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
Odpowiedź częściowa wygląda tak:
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
Uwaga: w interfejsach API, które obsługują parametry zapytania do podziału danych na strony (np. maxResults
i nextPageToken
), możesz użyć tych parametrów, by zmniejszyć liczbę wyników zapytań do rozmiaru, który ułatwia obsługę. W przeciwnym razie wzrost skuteczności przy użyciu częściowej odpowiedzi może się nie udać.