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

Porady dotyczące skutecznoś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. Te same pojęcia dotyczą jednak interfejsu Books 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 i odebranie 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ęć.

Istnieją 2 typy żądań częściowych:

Odpowiedź częściowa: w tym żądaniu wybierasz, które pola mają znajdować się w odpowiedzi (użyj parametru żądania fields).
Poprawka: w tym żądaniu aktualizacji wysyłasz tylko te pola, które chcesz zmienić (użyj czasownika HTTP PATCH).

Więcej informacji na temat tworzenia częściowych żądań znajdziesz w kolejnych sekcjach.

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.

Pamiętaj, że parametr fields wpływa tylko na dane odpowiedzi. Nie ma wpływu na dane, które chcesz wysłać. Aby zmniejszyć ilość danych wysyłanych po zmianie zasobów, użyj żądania poprawki.

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ć.

Poprawka (częściowa aktualizacja)

Nie musisz też wysyłać niepotrzebnych danych podczas modyfikowania zasobów. Aby wysyłać tylko zaktualizowane dane pól, które zmieniasz, użyj czasownika HTTP PATCH. Semantyka poprawki opisana w tym dokumencie różni się (i jest) łatwiejsza niż w przypadku starszej implementacji GData częściowej aktualizacji.

Krótki przykład poniżej pokazuje, jak dzięki poprawce zminimalizujesz ilość danych potrzebnych do wysłania niewielkiej aktualizacji.

Przykład

Ten przykład przedstawia proste żądanie poprawki, które aktualizuje tylko nazwę zasobu ogólnego (fikcyjnego) interfejsu API „Demo”. Zasób ma też komentarz, zbiór cech, stan i wiele innych pól, ale to żądanie wysyła tylko pole title, ponieważ tylko ono zostało zmienione:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

Odpowiedź:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

Serwer zwraca kod stanu 200 OK i pełną reprezentację zaktualizowanego zasobu. Żądanie poprawki dotyczy tylko pola title, dlatego jest to jedyna wartość inna niż we wcześniejszym przykładzie.

Uwaga: jeśli użyjesz parametru fields odpowiedzi częściowej w połączeniu z poprawką, możesz jeszcze bardziej zwiększyć skuteczność żądań aktualizacji. Żądanie poprawki zmniejsza tylko rozmiar żądania. Odpowiedź częściowa zmniejsza rozmiar odpowiedzi. Aby zmniejszyć ilość danych wysyłanych w obie strony, użyj żądania poprawki z parametrem fields.

Semantyka żądania poprawki

Treść żądania poprawki zawiera tylko pola zasobów, które chcesz zmodyfikować. Jeśli podajesz pole, musisz dodać wszystkie obiekty nadrzędne, tak jak obiekty nadrzędne zwracane w odpowiedzi częściowej. Zmienione dane, które przesyłasz, są scalane z danymi obiektu nadrzędnego (jeśli istnieje).

Dodawanie: aby dodać pole, które jeszcze nie istnieje, określ nowe pole i jego wartość.
Zmiana: aby zmienić wartość dotychczasowego pola, podaj jego nazwę i ustaw je na nową wartość.
Usuwanie: aby usunąć pole, wskaż je i ustaw na null. Na przykład: "comment": null. Możesz też usunąć cały obiekt (jeśli jest zmienny), ustawiając go na null. Jeśli używasz biblioteki klienta interfejsu Java API, użyj Data.NULL_STRING. Szczegóły znajdziesz na stronie dotyczącej pustej wartości JSON.

Uwaga na temat tablic: żądania poprawek z tablicami zastępują dotychczasową tablicę tą podaną przez Ciebie. Nie możesz zmieniać, dodawać ani usuwać elementów tablicy stopniowo.

Używanie poprawki w cyklu odczytu, zmiany i zapisu

Warto najpierw pobrać odpowiedź częściową z danymi, które chcesz zmodyfikować. Jest to szczególnie ważne w przypadku zasobów korzystających z tagów ETag, ponieważ w nagłówku HTTP If-Match musisz podać bieżącą wartość. Po otrzymaniu danych możesz zmodyfikować wartości, które chcesz zmienić, i odesłać zmodyfikowaną częściową reprezentację z żądaniem poprawki. Oto przykład, w którym założono, że zasób demonstracyjny używa znaczników ETag:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

Oto odpowiedź częściowa:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

Poniższe żądanie poprawki jest oparte na tej odpowiedzi. Jak widzisz, użyliśmy też parametru fields, aby ograniczyć ilość danych zwracanych w odpowiedzi poprawki:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

Serwer w odpowiedzi wysyła kod stanu HTTP 200 OK i częściową reprezentację zaktualizowanego zasobu:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

Bezpośrednie tworzenie żądania poprawki

W przypadku niektórych żądań poprawki musisz je ustalić na podstawie danych, które zostały pobrane wcześniej. Jeśli na przykład chcesz dodać element do tablicy i nie chcesz utracić żadnego z istniejących elementów tablicy, musisz najpierw pobrać istniejące dane. I podobnie, jeśli interfejs API używa znaczników ETag, razem z żądaniem musisz wysłać poprzednią wartość ETag, aby zaktualizować zasób.

Uwaga: aby wymusić zastosowanie poprawki, gdy są używane znaczniki ETag, możesz użyć nagłówka HTTP "If-Match: *". Nie musisz wtedy wykonywać tych czynności przed zapisem.

Jednak w innych przypadkach możesz utworzyć żądanie poprawki bezpośrednio bez wcześniejszego pobrania istniejących danych. Możesz na przykład łatwo skonfigurować żądanie poprawki, które zaktualizuje pole do nowej wartości lub doda nowe pole. Oto przykład:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

Jeśli pole komentarza ma już wartość, zostanie ona zastąpiona przez nową. W przeciwnym razie zostanie ustawiona na nową wartość. Analogicznie, jeśli wystąpiła cecha woluminu, jej wartość zostanie zastąpiona. W przeciwnym razie zostanie utworzona. Pole dokładności zostanie usunięte (jeśli jest ustawione).

Obsługa odpowiedzi do zastosowania poprawki

Po przetworzeniu prawidłowego żądania poprawki interfejs API zwraca kod odpowiedzi HTTP 200 OK i pełną reprezentację zmodyfikowanego zasobu. Jeśli interfejs API używa znaczników ETag, serwer aktualizuje wartości ETag po przetworzeniu żądania poprawki, tak samo jak w przypadku PUT.

Żądanie poprawki zwraca reprezentację całego zasobu, chyba że używasz parametru fields, aby zmniejszyć ilość zwracanych danych.

Jeśli żądanie poprawki powoduje nowy stan zasobu, który jest składniowo lub semantycznie nieprawidłowy, serwer zwraca kod stanu HTTP 400 Bad Request lub 422 Unprocessable Entity, a stan zasobu pozostaje bez zmian. Jeśli na przykład spróbujesz usunąć wartość wymaganego pola, serwer zwróci błąd.

Tekst alternatywny, gdy czasownik HTTP PATCH nie jest obsługiwany

Jeśli zapora sieciowa nie zezwala na żądania HTTP PATCH, wykonaj żądanie HTTP POST i ustaw nagłówek zastępowania na PATCH, jak pokazano poniżej:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

Różnica między poprawką a aktualizacją

W praktyce, gdy wysyłasz dane żądania aktualizacji używającego czasownika HTTP PUT, musisz wysłać tylko te pola, które są wymagane lub opcjonalne. Jeśli wyślesz wartości pól ustawionych przez serwer, zostaną one zignorowane. Może to wyglądać jak inna metoda wykonania częściowej aktualizacji, ale ta zasada ma pewne ograniczenia. W przypadku aktualizacji używających czasownika HTTP PUT żądanie nie powiedzie się, jeśli nie podasz wymaganych parametrów, i wyczyści wcześniej ustawione dane, jeśli nie podasz parametrów opcjonalnych.

Dlatego zdecydowanie zalecamy korzystanie z poprawki. Podajesz tylko dane pól, które chcesz zmienić. Pominięte pola nie są opróżniane. Jedynym wyjątkiem od tej reguły są powtarzające się elementy lub tablice. Jeśli pominiesz wszystkie te elementy, pozostaną bez zmian. Jeśli podasz któreś z nich, cały zestaw zostanie zastąpiony podanym przez Ciebie zestawem.