Zwiększanie wydajnoś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ą interfejsu Google Ad Experience Report API.

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 żądanie 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ęć.

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.

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.