Wskazówki dotyczące skuteczności

W tym dokumencie opisujemy techniki, które mogą poprawić wydajność Twojej aplikacji. Aby przedstawić niektóre rozwiązania, użyliśmy przykładów z innych interfejsów API lub ogólnych interfejsów API. Jednak te same pojęcia są używane w interfejsach API Zdjęć Google.

Kompresja za pomocą gzip

Kompresja gzip pozwala łatwo i wygodnie zmniejszyć przepustowość potrzebną do obsługi żądań. Dekompresja wyników wymaga dodatkowego czasu pracy procesora, jednak w zestawieniu z kosztami związanymi z siecią to rozwiązanie wypada bardzo korzystnie.

Aby odebrać odpowiedź zakodowaną w formacie gzip, ustaw nagłówek Accept-Encoding i dodaj do klienta użytkownika tekst gzip. Oto przykład poprawnych nagłówków HTTP, za pomocą których włączysz kompresję 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 żądania tylko o część danych, które Cię interesują. Dzięki temu aplikacja nie musi przesyłać, analizować i zapisywać niepotrzebnych pól, co pozwala wydajniej 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ć lepsze wyniki, możesz wysłać do serwera żądanie o odpowiedź częściową, czyli dostarczenie 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 odebrać w odpowiedzi. Tego parametru możesz użyć w każdym żądaniu, które zwraca dane odpowiedzi.

Przykład

Ten przykład przedstawia sposób użycia parametru fields w generycznym (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

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 to żądanie serwer wysyła tylko informacje o rodzaju i uproszczoną tablicę, w której każdy element 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"
    }
  },
  ...
  ]
}

Odpowiedź jest wysyłana w formie obiektu JSON, który zawiera tylko wybrane pola i obiekty nadrzędne.

Szczegółowe informacje o formatowaniu parametru fields znajdziesz poniżej. Opisaliśmy też szczegółowo zawartość odpowiedzi.

Podsumowanie składni parametru fields

Format wartości parametru żądania fields jest oparty na składni XPath. Podsumowanie obsługiwanej składni znajdziesz poniżej. Więcej przykładów przedstawiliśmy w następnej sekcji.

Aby wybrać wiele pól, użyj listy rozdzielonej przecinkami.
Użyj a/b, aby wybrać pole b zagnieżdżone w polu a. Użyj a/b/c, aby wybrać pole c zagnieżdżone w polu b.

Wyjątek: jeśli odpowiedź interfejsu API używa kodu danych i jest zagnieżdżona w obiekcie data, który wygląda jak data: { ... }, nie dodawaj „data” do specyfikacji fields. Dodanie do specyfikacji fields obiektu data, takiego jak data/a/b, powoduje błąd. Użyj tylko specyfikacji fields, takiej jak a/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 e-mail autora każdego elementu w tablicy. Możesz też podać jedno pole podrzędne, gdzie fields=items(id) jest równoważne z fields=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 zastosowania 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. W przykładach w tym dokumencie kodowanie zostało pominięte, aby ułatwić ich czytanie.

Wskaż pola, które chcesz otrzymać w odpowiedzi, lub wybierz odpowiednie 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ę list, 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 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ą innych pól podrzędnych, o ile nie wybrano ich wprost.
`context/facets/label`	Zwraca tylko pole `label` każdego elementu tablicy `facets`, która jest zagnieżdżona w obiekcie `context`.
`items/pagemap/*/title`	Zwraca tylko pole `title` (jeśli jest obecne) każdego elementu tablicy we wszystkich obiektach podrzędnych obiektu `pagemap`.

Oto kilka przykładów na poziomie zasobu:

Przykłady	Efekt
`title`	Zwraca pole `title` żądanego zasobu.
`author/uri`	Zwraca pole podrzędne `uri` obiektu `author` w żądanym zasobie.
`links/*/href`	Zwraca pole `href` każdego obiektu podrzędnego względem `links`.

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 użyć odpowiedzi, która zawiera tylko pewne 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` i `uri` 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 (na przykład "Invalid field selection a/b").

Poniżej znajdziesz przykładową odpowiedź częściową, o której była już mowa wcześniej, we wprowadzeniu. 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ę. Jeśli ich nie zastosujesz, wzrost wydajności wynikający z odpowiedzi częściowej może nie zostać osiągnięty.