Zwiększ skuteczność

W tym dokumencie opisujemy techniki, które mogą poprawić wydajność Twojej aplikacji. Aby przedstawić niektóre rozwiązania, użyliśmy przykładów z innych interfejsów API. Jednak te same pojęcia są używane w interfejsie Display & Video 360 API.

Praca z częściowymi zasobami

Innym sposobem na poprawę wydajności wywołań interfejsu API jest żądanie tylko części danych, które Cię interesują. Dzięki temu aplikacja nie musi przesyłać, analizować i zapisywać niepotrzebnych pól, co pozwala wydajniej wykorzystywać zasoby, w tym sieć, procesor i pamięć.

Odpowiedź częściowa

Po przetworzeniu żądań serwer domyślnie odsyła pełną reprezentację zasobu. Aby uzyskać lepsze wyniki, możesz wysłać do serwera żądanie o odpowiedź częściową, czyli dostarczenie tylko tych pól, których potrzebujesz.

Aby wysłać takie żądanie, użyj parametru żądania fields, określając w nim pola, które chcesz odebrać w odpowiedzi. Tego parametru możesz użyć w dowolnym żądaniu, które zwraca dane odpowiedzi.

Przykład

Ten przykład przedstawia sposób użycia parametru fields w interfejsie Display & Video 360 API.

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

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

Odpowiedź z pełnym zasobem: pełne dane zasobu obejmują poniższe pola i wiele innych pól pominiętych ze względu na długość odpowiedzi.

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 znacząco zmniejszyć ilość zwracanych danych.

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

Odpowiedź częściowa: w odpowiedzi na to żądanie serwer wysyła uproszczoną tablicę reklamodawców, która zawiera tylko identyfikator reklamodawcy, nazwę wyświetlaną i właściwość partner_id każdego reklamodawcy (jeśli występuje).

200 OK

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

Odpowiedź jest wysyłana w formie obiektu JSON, który zawiera tylko wybrane pola i obiekty nadrzędne.

Szczegółowe informacje o formatowaniu parametru fields znajdziesz poniżej. Opisaliśmy też szczegółowo zawartość odpowiedzi.

Podsumowanie składni parametru fields

Format wartości parametru żądania fields jest oparty na składni XPath. Podsumowanie obsługiwanej składni znajdziesz poniżej. Więcej przykładów przedstawiliśmy w następnej 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.

  • 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 „( )”.

    Przykład: fields=advertisers(advertiserId,generalConfig/domainUrl) zwraca tylko identyfikator reklamodawcy i URL domeny każdego elementu w tablicy advertisers. Możesz też podać jedno pole podrzędne, gdzie fields=advertisers(advertiserId) jest równoważne z fields=advertisers/advertiserId.

Więcej przykładów zastosowania parametru fields

W poniższych przykładach opisano, jak wartość parametru fields wpływa na odpowiedź.

Wskaż pola, które chcesz otrzymać w odpowiedzi, lub wybierz odpowiednie pola.

Wartość parametru żądania fields ma postać listy pól oddzielonej przecinkami. Każde pole jest określane względem elementu głównego odpowiedzi. Oznacza to, że jeśli wykonujesz operację list, 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 jej częścią, serwer zwraca wybraną część wszystkich elementów tablicy.

Oto kilka przykładów na poziomie kolekcji:

Przykład Efekt
advertisers Zwraca wszystkie elementy tablicy advertisers, łącznie ze wszystkimi polami w każdym elemencie (nie zwraca żadnych innych pól).
advertisers,nextPageToken Zwraca zarówno pole nextPageToken, jak i wszystkie elementy tablicy advertisers.
advertisers/advertiserId Zwraca tylko pole advertiserId wszystkich elementów tablicy advertisers.

Gdy jest zwracane zagnieżdżone pole, odpowiedź zawiera obiekty nadrzędne. Pola nadrzędne nie zawierają żadnych innych pól podrzędnych, o ile nie wybrano ich wprost.
advertisers/generalConfig/domainUrl Zwraca pole domainUrl obiektu generalConfig, który jest zagnieżdżony w tablicy advertisers.

Oto kilka przykładów na poziomie zasobu:

Przykład Efekt
advertiserId Zwraca pole advertiserId żądanego zasobu.
generalConfig/domainUrl Zwraca pole domainUrl obiektu generalConfig w żądanym zasobie.
Aby żądać tylko fragmentów pól, dokonaj wyborów podrzędnych.

Jeśli żądanie dotyczy określonych pól, serwer zwraca domyślnie całe obiekty lub elementy tablicy. Możesz użyć odpowiedzi, która zawiera tylko pewne pola podrzędne. W tym celu użyj składni wyboru podrzędnego „( )”, jak pokazujemy w tym przykładzie.

Przykład Efekt
advertisers(advertiserId,generalConfig/domainUrl) Zwraca tylko wartości advertiserId i generalConfig domainUrl z każdego elementu tablicy advertisers.
Obsługa odpowiedzi częściowych

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").