Ta strona została przetłumaczona przez Cloud Translation API.

Porady dotyczące skuteczności

W tym dokumencie opisujemy techniki, które możesz wykorzystać do poprawy działania swojej 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 koncepcje dotyczą interfejsu Custom Search JSON API.

Kompresja za pomocą gzip

Kompresja gzip pozwala łatwo i wygodnie zmniejszyć przepustowość potrzebną do obsługi żądań. Chociaż dekompresja wyników wymaga dodatkowego czasu pracy procesora, zrekompensowanie tego z kosztami sieci zazwyczaj jest bardzo opłacalne.

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 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ę skuteczności wywołań interfejsu API jest wysyłanie żądań tylko do części danych, która Cię interesuje. Pozwala to aplikacji uniknąć przesyłania, analizowania i przechowywania niepotrzebnych pól, dzięki czemu może 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ć lepszą wydajność, możesz poprosić serwer, aby wysłał tylko te pola, których potrzebujesz, i uzyskał odpowiedź częściową.

Aby wysłać takie żądanie, użyj parametru żądania fields i określ pola, które chcesz otrzymać. Tego parametru możesz używać w każdym żądaniu, które zwraca dane odpowiedzi.

Przykład

Przykład poniżej pokazuje sposób użycia parametru fields z ogólną (fikcyjną) wartością „Demo” API.

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 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 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ź zawierającą tylko informacje o rodzaju oraz skróconą tablicę elementów, w której każdy element zawiera tylko informacje o tytule HTML i długości danego elementu.

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 parametru pól

Format wartości parametru żądania fields jest oparty na składni XPath. Podsumowanie obsługiwanej składni znajdziesz w dalszej części tego artykułu.

Użyj listy rozdzielanej przecinkami, aby wybrać wiele pól.
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 b.

Wyjątek: w przypadku odpowiedzi interfejsu API zawierających słowo „dane” otoki, w których odpowiedź jest zagnieżdżona w obiekcie data, który wygląda jak data: { ... }, nie dodawaj „data”. w specyfikacji fields. Dodanie obiektu danych do specyfikacji pól, takich 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.
W razie potrzeby 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 pól

W przykładach poniżej 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 ułatwić czytanie, w przykładach w tym dokumencie pominięto kodowanie.

Określ pola, które chcesz zwrócić, lub wybierz odpowiednie pola.

Wartość parametru żądania fields ma postać listy pól rozdzielanej 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, w tym wszystkie pola 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ą też wybrane bezpośrednio.
`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 użyć odpowiedzi, która zawiera tylko niektóre pola podrzędne. W tym celu użyj polecenia „( )” jak w poniższym 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 błędzie z wybranymi polami (na przykład "Invalid field selection a/b").

Oto przykładowa odpowiedź częściowa, 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 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.