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

Zwiększanie wydajności

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ć 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. Uwzględnienie obiektu danych w specyfikacji pól, np. data/a/b, powoduje błąd. Zamiast tego użyj 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 „( )”.
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órym fields=items(id) jest odpowiednikiem pola fields=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 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.

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` i `uri` 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ć.