W tym dokumencie opisujemy kilka technik, które mogą poprawić wydajność Twojej aplikacji. W niektórych przypadkach do zilustrowania przedstawionych pomysłów użyliśmy przykładów z innych interfejsów API lub ogólnych interfejsów API. Te same pojęcia są używane w interfejsie Google Classroom API.
Kompresja za pomocą programu gzip
Kompresja gzip pozwala łatwo i wygodnie zmniejszyć przepustowość potrzebną do obsługi żądań. Chociaż dekompresja wyników wymaga dodatkowego czasu procesora, to kompresja kosztów sieciowych zazwyczaj jest bardzo korzystna.
Aby odebrać odpowiedź zakodowaną w formacie gzip, ustaw nagłówek Accept-Encoding
i dodaj do klienta użytkownika ciąg znaków gzip
. Oto przykład prawidłowo sformułowanych nagłówków HTTP, które umożliwiają włączenie kompresji gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)
Praca z częściowymi zasobami
Innym sposobem na poprawę wydajności wywołań interfejsu API jest wysyłanie żądań tylko do tych części danych, które Cię interesują. Dzięki temu aplikacja unika przesyłania, analizowania i przechowywania niepotrzebnych pól, a tym samym efektywniej wykorzystywać zasoby, w tym sieć, procesor i pamięć.
Odpowiedź częściowa
Po przetworzeniu żądań serwer domyślnie odsyła pełną reprezentację zasobu. Aby uzyskać lepszą wydajność, możesz wysłać do serwera żądanie o odpowiedź częściową, czyli wysłanie tylko tych pól, których potrzebujesz.
Aby wysłać takie żądanie, użyj parametru żądania fields
, określając w nim pola, które chcesz otrzymać w odpowiedzi. Tego parametru możesz użyć w każdym żądaniu, które zwraca dane odpowiedzi.
Przykład
Przykład poniżej pokazuje użycie parametru fields
z ogólnym (fikcyjnym) interfejsem API „Demo”.
Proste żądanie: to żądanie HTTP GET
pomija parametr fields
i zwraca pełny zasób.
https://www.googleapis.com/demo/v1
Odpowiedź z pełnym zasobem: pełne dane zasobu obejmują poniższe pola i wiele innych pól pominiętych ze względu na długość odpowiedzi.
{ "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 powyższe żądanie serwer wysyła odpowiedź, która zawiera tylko informacje o rodzaju oraz tablicę elementów ze zminimalizowaną liczbą elementów, która w każdym elemencie zawiera tylko tytuł HTML i informacje o długości.
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
Pamiętaj, że odpowiedź jest obiektem JSON, który zawiera tylko wybrane pola i ich obiekty nadrzędne.
Szczegółowe informacje o formatowaniu parametru fields
znajdziesz poniżej. Opisaliśmy też szczegółowo zawartość odpowiedzi.
Podsumowanie składni parametrów pól
Format wartości parametru żądania fields
jest oparty na składni XPath. Podsumowanie obsługiwanej składni znajdziesz poniżej. Dodatkowe przykłady znajdziesz w następnej 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 „data” i jest zagnieżdżona w obiekcie
data
, który wygląda jakdata: { ... }
, nie dodawaj „data
” do specyfikacjifields
. Dodanie do specyfikacji fields obiektu data, takiego jakdata/a/b
, powoduje błąd. Użyj tylko 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 „
( )
”.Przykład:
fields=items(id,author/email)
zwraca tylko identyfikator elementu i adres e-mail autora każdego elementu w tablicy items. Możesz też podać jedno pole podrzędne, gdziefields=items(id)
jest równoważne zfields=items/id
. - Jeśli to konieczne, w wybranych polach używaj symboli wieloznacznych.
Przykład:
fields=items/pagemap/*
wybiera wszystkie obiekty w elemencie pagemap.
Więcej przykładów użycia parametru fields
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. Aby zwiększyć czytelność, w przykładach w tym dokumencie kodowanie zostało pominięte.
- Zidentyfikuj pola, które chcesz zwrócić, lub wybierz pola.
- Wartość parametru żądania
fields
ma postać listy pól oddzielonej przecinkami. 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 również zostaną wyraźnie zaznaczone.context/facets/label
Zwraca tylko pole label
każdego elementu 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
wszystkich obiektów podrzędnych obiektulinks
. - Aby żądać tylko fragmentów pól, dokonaj wyborów podrzędnych.
- Jeśli żądanie dotyczy określonych pól, serwer zwraca domyślnie całe obiekty lub elementy tablicy. Możesz określić odpowiedź zawierającą tylko określone 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 tablicy.
Obsługa odpowiedzi częściowych
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 (np. "Invalid field selection a/b"
).
Oto przykład odpowiedzi częściowej, którą znajdziesz we wprowadzeniu 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 (na przykład maxResults
i nextPageToken
), te parametry pozwalają zmniejszyć liczbę wyników zapytań do rozmiaru, który ułatwia obsługę. W przeciwnym razie wzrost wydajności wynikający z odpowiedzi częściowej może nie zostać osiągnięty.