Porady dotyczące skuteczności

W tym dokumencie opisujemy kilka technik, których możesz użyć, aby poprawić wydajność swojej 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 dotyczą jednak interfejsu Custom Search JSON API.

Kompresja za pomocą gzip

Kompresja gzip pozwala łatwo i wygodnie zmniejszyć przepustowość potrzebną do obsługi żądań. Mimo że 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 tekstowy gzip. Oto przykład prawidłowo sformatowanych 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 nie musi przesyłać, analizować i przechowywać 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 zwiększyć wydajność, możesz wysłać do serwera żądanie, by wysyłał tylko te pola, których potrzebujesz, i otrzymał odpowiedź częściową.

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 przypadku każdego żądania, które zwraca dane odpowiedzi.

Przykład

Przykład poniżej pokazuje wykorzystanie 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 znacznie 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 skróconą tablicę elementów, która w każdym elemencie zawiera tylko informacje o tytule HTML i długości elementów.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Pamiętaj, że odpowiedź to obiekt 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 sekcji poniżej.

• Aby wybrać wiele pól, użyj listy oddzielonej 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 adres e-mail autora każdego elementu 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 użycia parametru fields

W poniższych przykładach opisano, jak wartość parametru fields wpływa na odpowiedź.

Uwaga: tak jak w przypadku wszystkich wartości parametrów 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 rozdzielonych 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 wybrane.
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 wszystkich obiektów podrzędnych obiektu 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 określić odpowiedź, która zawiera 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 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 zwraca kod stanu HTTP 400 Bad Request i komunikat o błędzie z informacją o problemie z wyborem pól (na przykład "Invalid field selection a/b").

Poniżej znajdziesz przykładową odpowiedź częściową, o której mowa powyżej, 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 przypadku interfejsów 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.