Interfejs API JSON Bloggera: wskazówki dotyczące skuteczności

W tym dokumencie opisujemy kilka metod, które możesz wykorzystać, by poprawić wydajność aplikacji. W niektórych przypadkach ilustrowane są przykłady z innych interfejsów API lub ogólnych interfejsów API. Jednak te same pojęcia dotyczą interfejsów API Bloggera.

Kompresja za pomocą gzip

Prosty i wygodny sposób na zmniejszenie przepustowości sieci dla każdego żądania to włączenie kompresji gzip. Chociaż zdekompresowanie wyników wymaga dodatkowego czasu na procesory, kompromis między kosztami sieci jest zwykle bardzo wartościowy.

Aby otrzymać odpowiedź zakodowaną w formacie gzip, ustaw nagłówek Accept-Encoding i zmień klienta użytkownika, tak aby zawierał ciąg gzip. Oto przykład poprawnych nagłówków HTTP, które pomogą Ci włączyć kompresję gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)

Praca z częściowymi zasobami

Innym sposobem na zwiększenie wydajności wywołań interfejsu API jest wysyłanie i odbieranie tylko części danych, które Cię interesują. Dzięki temu aplikacja nie musi przenosić, analizować ani przechowywać niepotrzebnych pól. Dzięki temu może lepiej wykorzystać zasoby, takie jak sieć, procesor i pamięć.

Są 2 rodzaje żądań częściowych:

• Odpowiedź częściowa: żądanie, w którym określasz pola, które chcesz uwzględnić w odpowiedzi (użyj parametru żądania fields).
• Poprawka: żądanie aktualizacji, w którym wysyłasz tylko pola, które chcesz zmienić (użyj czasownika HTTP PATCH).

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

Odpowiedź częściowa

Domyślnie po przetworzeniu żądań serwer zwraca pełną reprezentację zasobu. Aby uzyskać lepszą wydajność, możesz poprosić serwer o wysłanie tylko tych pól, których potrzebujesz, a otrzymać częściową odpowiedź.

Aby wysłać częściową odpowiedź, użyj parametru żądania fields, aby określić pola, które chcesz zwrócić. Tego parametru możesz używać z każdym żądaniem zwracającym dane odpowiedzi.

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

Przykład

Poniższy przykład przedstawia użycie parametru fields w ogólnym (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ź zasobu: pełne dane zasobu obejmują poniższe pola oraz 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 znacząco zmniejszyć ilość zwracanych danych.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Częściowa odpowiedź: w odpowiedzi na żądanie powyżej serwer wysyła odpowiedź zawierającą tylko informacje o rodzaju elementu wraz z uproszczoną tabelą elementów, która zawiera tylko informacje o tytule HTML i długości informacji w każdym elemencie.

200 OK

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

Pamiętaj, że odpowiedź to obiekt JSON zawierający tylko wybrane pola i obiekty nadrzędne.

Poniżej opisujemy szczegółowo, jak sformatować parametr fields, a także szczegóły dotyczące tego, co dokładnie zwraca się w odpowiedzi.

Podsumowanie składni parametru pól

Format wartości parametru żądania fields jest luźno oparty na składni XPath. Podsumowanie obsługiwanej składni znajdziesz poniżej, a dodatkowe przykłady znajdziesz w kolejnej 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: w przypadku odpowiedzi interfejsu API korzystających z parametru "data" opakowania, których odpowiedź jest zagnieżdżona w obiekcie data, który wygląda jak data: { ... }, nie uwzględniaj &"data" w specyfikacji fields. Dodanie obiektu danych ze specyfikacją pól, np. data/a/b, powoduje błąd. Wystarczy, że użyjesz specyfikacji fields, np. a/b.

• Użyj selektora podrzędnego, aby zażądać zbioru konkretnych pól podrzędnych tablic lub obiektów. W tym celu umieść wyrażenia w nawiasach i ( ).

  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ż określić jedno pole podrzędne, gdzie fields=items(id) jest odpowiednikiem fields=items/id.

• W razie potrzeby w odpowiednich polach użyj symboli wieloznacznych.

  Na przykład: fields=items/pagemap/* wybiera wszystkie obiekty w mapie strony.

Więcej przykładów użycia parametru pola

Poniższe przykłady pokazują, jak wartość parametru fields wpływa na odpowiedź.

Uwaga: tak jak wszystkie wartości parametrów zapytania, wartość parametru fields musi być zakodowana na potrzeby adresu URL. W przypadku przykładów w tym dokumencie pominięto kodowanie.

Znajdź pola, które chcesz zwrócić, lub wybierz pola.

Wartość parametru żądania fields to lista pól rozdzielonych przecinkami, a każde pole jest określane względem katalogu głównego odpowiedzi. Jeśli więc wykonujesz operację na liście, w odpowiedzi otrzymasz kolekcję, która zwykle zawiera tablicę zasobów. Jeśli wykonujesz operację, która zwraca pojedynczy zasób, pola są określane względem tego zasobu. Jeśli wybrane pole jest (lub stanowi część) tablicy, serwer zwraca wybrany fragment wszystkich elementów tablicy.

Oto kilka przykładów na poziomie kolekcji:

Przykłady	Efekt
items	Zwraca wszystkie elementy tablicy, w tym wszystkie pola każdego elementu, ale nie wszystkie pola.
etag,items	Zwraca zarówno pole etag, jak i wszystkie elementy w tablicy elementów.
items/title	Zwraca tylko pole title wszystkich elementów tablicy. Gdy jest zwracane zagnieżdżone pole, odpowiedź zawiera otaczające obiekty nadrzędne. Pola nadrzędne nie zawierają żadnych innych pól podrzędnych, chyba że również zostaną wybrane w inny sposób.
context/facets/label	Zwraca tylko pole label wszystkich elementów tablicy facets, które są zagnieżdżone w obiekcie context.
items/pagemap/*/title	Każdy element w tablicy elementów zwraca tylko pole title (jeśli jest obecne) wszystkich obiektów podrzędnych elementów 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 elementu links.

Aby żądać tylko części pól, użyj selektorów podrzędnych.

Jeśli żądanie określa określone pola, domyślnie serwer zwraca całe obiekty lub elementy tablicy. Możesz określić odpowiedź zawierającą tylko określone pola podrzędne. W tym celu użyj składni wyboru podrzędnego( )&quot, jak w poniższym przykładzie.

Przykład	Efekt
items(title,author/uri)	Zwraca tylko wartości pól title i autor uri dla każdego elementu w tablicy elementów.

Obsługa odpowiedzi częściowych

Gdy serwer przetworzy prawidłowe żądanie z parametrem zapytania fields, wraz 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 wraz z komunikatem o błędzie informującym użytkownika, co było nie tak z wyborem pól (na przykład "Invalid field selection a/b").

Oto przykładowa odpowiedź częściowa przedstawiona powyżej w sekcji wprowadzającej. Żądanie wykorzystuje parametr fields do określenia, które pola zwrócić.

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), używaj tych parametrów, by zmniejszyć liczbę wyników każdego zapytania do rozmiaru, który można by zmienić. W przeciwnym razie wzrost skuteczności przy użyciu odpowiedzi częściowej może być nieosiągalny.

Poprawka (częściowa aktualizacja)

Możesz też uniknąć wysyłania zbędnych danych podczas modyfikowania zasobów. Aby wysyłać zaktualizowane dane tylko dla konkretnych pól, które zmieniasz, użyj czasownika HTTP PATCH. Semantyka poprawki opisana w tym dokumencie różni się (i łatwiej) niż w starszej, częściowej implementacji GData.

Krótki przykład poniżej pokazuje, jak zastosowanie poprawki minimalizuje dane niezbędne do wysłania niewielkiej aktualizacji.

Przykład

Ten przykład pokazuje proste żądanie poprawki, które aktualizuje tylko tytuł zasobu fikcyjnego (fikcyjnego) ogólnego interfejsu API. 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 jest modyfikowane:

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ło tylko pola title, więc jest to jedyna wartość inna niż we wcześniejszym okresie.

Uwaga: jeśli używasz parametru częściowej odpowiedzi fields w połączeniu z poprawką, możesz jeszcze bardziej zwiększyć wydajność żądań aktualizacji. Żądanie poprawki ogranicza 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ć. Gdy podajesz pole, musisz uwzględnić wszystkie obiekty nadrzędne, tak jak obiekty nadrzędne są zwracane z odpowiedzią częściową. Zmienione dane są scalane z danymi obiektu nadrzędnego (jeśli taki istnieje).

• Dodawanie: aby dodać pole, które jeszcze nie istnieje, wskaż nowe pole i jego wartość.
• Zmiana: aby zmienić wartość dotychczasowego pola, podaj jego nazwę i ustaw ją na nową wartość.
  
• Usuń: aby usunąć pole, określ 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 Java API, użyj Data.NULL_STRING. Szczegółowe informacje znajdziesz w artykule Brak wartości JSON.

Uwaga o tablicach: żądania poprawek zawierające tablice zastępują istniejącą tablicę tą podaną przez Ciebie. Nie możesz modyfikować, dodawać ani usuwać elementów tablicy.

zastosowanie poprawki w trybie odczytu, modyfikacji i zapisu.

Warto zacząć od pobrania częściowej odpowiedzi z danymi, które chcesz zmodyfikować. Jest to szczególnie ważne w przypadku zasobów, które korzystają z tagów ETag, ponieważ w nagłówku HTTP If-Match musisz podać bieżącą wartość. Po uzyskaniu danych możesz zmodyfikować wartości, które chcesz zmienić, i wysłać zmodyfikowaną częściową reprezentację z prośbą o poprawkę. W tym przykładzie założono, że zasób do wersji demonstracyjnej korzysta z tagó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"],
  }
}

Żądanie poprawki poprawki bazuje na tej odpowiedzi. Jak pokazano poniżej, wykorzystuje się też parametr fields, aby ograniczyć dane zwracane 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. */
  },
}

W odpowiedzi serwer przesył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ń poprawek trzeba je stosować na podstawie pobranych wcześniej danych. Jeśli na przykład chcesz dodać element do tablicy, ale nie chcesz stracić żadnych istniejących elementów tablicy, musisz najpierw pobrać dane. I podobnie, jeśli interfejs API używa znaczników ETag, musisz przesłać poprzednią wartość ETag z żądaniem, by zaktualizować zasób.

Uwaga: aby wymusić zastosowanie poprawki, gdy są używane tagi ETag, możesz użyć nagłówka HTTP "If-Match: *". W takim przypadku nie musisz czytać informacji przed zapisaniem.

W innych przypadkach możesz utworzyć żądanie poprawki bezpośrednio, bez wcześniejszego pobierania istniejących danych. Możesz na przykład łatwo skonfigurować żądanie poprawki, które aktualizuje pole do nowej wartości lub dodaje 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 zawiera już wartość, nowa wartość ją zastąpi. W przeciwnym razie zostanie ustawiona na nową wartość. Analogicznie, jeśli wystąpi 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 na poprawkę

Po przetworzeniu prawidłowego żądania poprawki interfejs API zwraca kod odpowiedzi HTTP 200 OK wraz z pełną reprezentacją zmodyfikowanego zasobu. Jeśli interfejs API korzysta z tagów ETag, serwer aktualizuje wartości ETag po przetworzeniu żądania poprawki, tak jak w przypadku atrybutu PUT.

Żądanie poprawki zwraca całe przedstawienie 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.

Alternatywne zapisy, 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ąpienia na PATCH, jak pokazano poniżej:

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

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

W ramach wysyłania danych o żądaniu aktualizacji, które używa czasownika HTTP PUT, musisz wysłać tylko pola wymagane lub opcjonalne. Jeśli wyślesz wartości w polach ustawionych przez serwer, zostaną one zignorowane. Choć może się to wydawać w inny sposób, może to wynikać z pewnych ograniczeń. W przypadku aktualizacji, które używają czasownika HTTP PUT, żądanie nie powiedzie się, jeśli nie podasz wymaganych parametrów, i wyczyści dane ustawione wcześniej, jeśli nie podasz parametrów opcjonalnych.

Z tego względu użycie poprawki jest o wiele bezpieczniejsze. Podajesz tylko pola, które chcesz zmienić. Pominięte pola nie są usuwane. Jedynym wyjątkiem od tej reguły są powtarzające się elementy lub tablice: jeśli pominiesz je wszystkie, pozostaną bez zmian. Jeśli podasz te informacje, cały zestaw zostanie zastąpiony przesłanym przez Ciebie zestawem.