Zwiększ skuteczność

W tym dokumencie omówiono niektóre techniki, które można wykorzystać do poprawy skuteczności Twojej aplikacji. W niektórych przypadkach używane są przykłady z innych wdrożonych interfejsów API aby zilustrować przedstawiane koncepcje. Mają jednak zastosowanie te same koncepcje do reklam displayowych Interfejs Video 360 API.

Praca z częściowymi zasobami

Innym sposobem na poprawę skuteczności wywołań interfejsu API jest używanie tylko żądań fragment danych, który Cię interesuje. Dzięki temu aplikacja unikaj przesyłania, analizowania i przechowywania niepotrzebnych pól, dzięki czemu będzie można korzystać z zasobów takich jak sieć, procesor i pamięć.

Odpowiedź częściowa

Domyślnie serwer odsyła pełną reprezentację zasobu po przetwarzania żądań. Aby uzyskać lepszą wydajność, możesz poprosić serwer o wysyłanie tylko te pola, których potrzebujesz, a zamiast nich otrzymasz odpowiedź częściową.

Aby wysłać żądanie odpowiedzi częściowej, użyj parametru żądania fields do określenia które pola chcesz zwrócić. Tego parametru możesz użyć w każdym żądaniu który zwraca dane odpowiedzi.

Przykład

W przykładzie poniżej widać, jak wykorzystać parametr fields z parametrem Reklamy displayowe i Interfejs Video 360 API.

Proste żądanie: to żądanie HTTP GET pomija parametr fields i zwraca pełny zasób.

GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1

Odpowiedź z pełnym zasobem: pełne dane zasobu obejmują: wraz z wieloma innymi pominiętymi wcześniej ze względu na zwięzłość.

200 OK

{
 "advertisers": [
  {
   "name": "advertisers/1",
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  {
   "name": "advertisers/2",
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  ...
 ],
 "nextPageToken": "..."
}

Żądanie odpowiedzi częściowej: poniższe żądanie tego samego zasobu. używa parametru fields, aby znacznie zmniejszyć ilość zwracanych danych.

GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)

Odpowiedź częściowa: w odpowiedzi na powyższe żądanie serwer odsyła odpowiedzi, która zawiera skróconą tablicę reklamodawców zawierającą tylko identyfikator reklamodawcy, nazwę wyświetlaną i identyfikator partnera każdego reklamodawcy, jeśli obecnie.

200 OK

{
 "advertisers": [
  {
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1"
  },
  {
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2"
  },
  ...
 ]
}

Pamiętaj, że odpowiedź jest obiektem JSON, który zawiera tylko wybrane pola i otaczających je obiektów nadrzędnych.

Szczegółowe informacje o formatowaniu parametru fields znajdziesz poniżej. .

Podsumowanie składni parametru pól

Format wartości parametru żądania fields jest oparty na XPath składni. Podsumowanie obsługiwanej składni znajdziesz poniżej. podane w następnej sekcji.

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

• Użyj selektora podrzędnego, aby zażądać zbioru konkretnych podrzędnych pól tablic lub , umieszczając wyrażenia w nawiasach „( )”.

  Przykład: fields=advertisers(advertiserId,generalConfig/domainUrl) zwraca tylko identyfikator reklamodawcy i URL domeny z każdego elementu reklamodawcom. Możesz również określić jedno pole podrzędne, gdzie fields=advertisers(advertiserId) jest odpowiednikiem funkcji fields=advertisers/advertiserId

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 w przypadku wszystkich wartości parametrów zapytania, wartość parametru fields musi wynosić Zakodowany URL. Aby ułatwić czytelność, w przykładach w tym dokumencie pominięto przy kodowaniu.

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

Wartość parametru żądania fields ma postać listy pól rozdzielonych przecinkami. każde pole jest określane względem elementu głównego odpowiedzi. Jeśli więc wykonując operację list, odpowiedź jest kolekcją, a zwykle obejmuje tablicę zasobów. Jeśli wykonujesz operację zwracającego jeden 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 w tablicy.

Oto kilka przykładów na poziomie kolekcji:

Przykład	Efekt
advertisers	Zwraca wszystkie elementy w Tablica advertisers, w tym wszystkich pól w każdym elemencie, ale żadnych innych pól.
advertisers,nextPageToken	Zwraca zarówno nextPageToken, oraz wszystkich elementów w argumencie tablica advertisers.
advertisers/advertiserId	Zwraca tylko wartość advertiserId dla wszystkich elementów w tablica advertisers. Za każdym razem, gdy zagnieżdżone pole jest , odpowiedź zawiera otaczających go obiektów nadrzędnych. Pola nadrzędne nie zawierają wszystkich innych pól podrzędnych, chyba że są one również wybrane bezpośrednio.
advertisers/generalConfig/domainUrl	Zwraca pole domainUrl dla obiektu generalConfig, który jest umieszczony w tagu Tablica advertisers.

Oto kilka przykładów na poziomie zasobu:

Przykład	Efekt
advertiserId	Zwraca pole advertiserId żądanego zasobu.
generalConfig/domainUrl	Zwraca pole domainUrl dla obiektu generalConfig w żądanym zasobie.

Aby żądać tylko fragmentów pól, dokonaj wyborów podrzędnych.

Jeśli żądanie określa określone pola, domyślnie serwer zwraca w całości obiekty lub elementy tablicy. Możesz podać odpowiedź które obejmuje tylko niektóre pola podrzędne. W tym celu użyj polecenia „( )” jak w poniższym przykładzie.

Przykład	Efekt
advertisers(advertiserId,generalConfig/domainUrl)	Zwraca tylko wartości advertiserId i generalConfig domainUrl dla każdy element w argumencie advertisers .

Obsługa odpowiedzi częściowych

Gdy serwer przetworzy prawidłowe żądanie, które zawiera zapytanie fields , wysyła on kod stanu HTTP 200 OK oraz żądanie i skalowalnych danych. Jeśli parametr zapytania fields zawiera błąd lub jest nieprawidłowy z innego powodu, parametr serwer zwraca kod stanu HTTP 400 Bad Request wraz z błędem z informacją o problemach z wybranymi polami (np. "Invalid field selection a/b").

Uwaga: interfejsy API, które obsługują parametry zapytania do podziału danych na strony (maxResults i np. nextPageToken), użyj tych parametrów, aby zmniejszyć liczbę wyników do zwiększania rozmiaru poszczególnych zapytań. W przeciwnym razie wydajność z odpowiedzią częściową mogą nie zostać zrealizowane.