Leistung steigern

In diesem Dokument werden einige Techniken beschrieben, mit denen du die Leistung deiner Anwendung verbessern kannst. In einigen Fällen werden Beispiele aus anderen implementierten APIs verwendet, um die vorgestellten Ideen zu erläutern. Dieselben Konzepte gelten jedoch auch für die Display & Video 360 API.

Mit Teilressourcen arbeiten

Eine andere Möglichkeit zur Verbesserung der Leistung Ihrer API-Aufrufe besteht darin, nur den Teil der Daten anzufordern, der für Sie relevant ist. Dadurch entfallen das Übertragen, Parsen und Speichern nicht benötigter Felder, sodass die Ressourcen wie das Netzwerk, die CPU und der Speicher effizient eingesetzt werden.

Teilantwort

Standardmäßig wird nach der Verarbeitung einer Anfrage die komplette Darstellung einer Ressource vom Server zurückgeliefert. Du kannst den Server zwecks Leistungsverbesserung aber auch anweisen, nur die Felder zu senden, die du wirklich benötigst, und erhältst dann eine Teilantwort.

Verwende zum Anfragen einer Teilantwort den Anfrageparameter fields. Damit kannst du angeben, welche Felder zurückgegeben werden sollen. Du kannst diesen Parameter mit jeder beliebigen Anfrage verwenden, die Antwortdaten zurückgibt.

Beispiel

Das folgende Beispiel zeigt die Verwendung des fields-Parameters mit der Display & Video 360 API.

Einfache Anfrage:Bei dieser HTTP-GET-Anfrage wird der Parameter fields weggelassen und die vollständige Ressource zurückgegeben.

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

Antwort mit vollständiger Ressource:Die vollständigen Ressourcendaten umfassen folgende Felder sowie zahlreiche weitere Felder, die der Übersichtlichkeit halber ausgelassen wurden.

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": "..."
}

Anfrage für eine Teilantwort:In der folgenden Anfrage für dieselbe Ressource wird der Parameter fields verwendet, um die zurückgegebene Datenmenge erheblich zu verringern.

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

Teilantwort: Als Antwort auf die obige Anfrage sendet der Server eine Antwort zurück, die ein reduziertes Array von Werbetreibenden enthält, das nur die Werbetreibenden-ID, den Anzeigenamen und die Partner-ID der einzelnen Werbetreibenden enthält, sofern vorhanden.

200 OK

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

Die Antwort ist ein JSON-Objekt, das nur die ausgewählten Felder und deren einschließende übergeordnete Objekte enthält.

Details zur Formatierung des fields-Parameters werden als Nächstes beschrieben, gefolgt von weiteren Informationen zum genauen Inhalt, der in der Antwort zurückgegeben wird.

Parameter "Fields" – Syntaxzusammenfassung

Das Format des fields-Anfrageparameters basiert grob auf der XPath-Syntax. Die unterstützte Syntax wird unten zusammengefasst. Zusätzliche Beispiele findest du im darauffolgenden Abschnitt.

  • Zur Auswahl mehrerer Felder verwenden Sie eine durch Kommas getrennte Liste.

  • Verwenden Sie a/b, um ein Feld b auszuwählen, das im Feld a verschachtelt ist; verwenden Sie a/b/c, um ein Feld c auszuwählen, das in b verschachtelt ist.

  • Verwenden Sie ein untergeordnetes Auswahlzeichen, um eine Reihe von untergeordneten Feldern von Arrays oder Objekten anzufordern. Setzen Sie dazu Ausdrücke in Klammern: „( )“.

    Beispiel: fields=advertisers(advertiserId,generalConfig/domainUrl) gibt nur die Werbetreibenden-ID und die Domain-URL für jedes Element im Array „advertisers“ zurück. Du kannst auch ein einzelnes Teilfeld angeben, in dem fields=advertisers(advertiserId) fields=advertisers/advertiserId entspricht.

Weitere Beispiele zur Verwendung des Parameters "Fields"

In diesen Beispielen wird auch beschrieben, wie sich der Wert des Parameters fields auf die Antwort auswirkt.

Identifizieren Sie die Felder, die zurückgegeben werden sollen, oder treffen Sie eine Feldauswahl.

Der Wert des Anfrageparameters fields besteht aus einer durch Kommas getrennten Liste mit Feldern. Jedes Feld muss relativ zum Stamm der Antwort angegeben werden. Wenn du also einen list-Vorgang ausführst, besteht die Antwort aus einer Sammlung und enthält im Allgemeinen ein Ressourcen-Array. Bei einem Vorgang, der eine einzelne Ressource zurückgibt, werden die Felder bezogen auf diese Ressource angegeben. Wenn das ausgewählte Feld ein Array (oder ein Teil eines Arrays) ist, gibt der Server den ausgewählten Teil aller Elemente in dem Array zurück.

Hier einige Beispiele für die Sammlungsebene:

Beispiel Effekt
advertisers Gibt alle Elemente im advertisers-Array zurück, einschließlich aller Felder in jedem Element, jedoch keine anderen Felder.
advertisers,nextPageToken Gibt sowohl das nextPageToken-Feld als auch alle Elemente im advertisers-Array zurück.
advertisers/advertiserId Gibt nur das advertiserId für alle Elemente im advertisers-Array zurück.

Wenn ein verschachteltes Feld zurückgegeben wird, umfasst die Antwort die einschließenden übergeordneten Objekte. Die übergeordneten Felder enthalten nur dann andere untergeordnete Felder, wenn diese ausdrücklich ausgewählt wurden.
advertisers/generalConfig/domainUrl Gibt das Feld domainUrl für das generalConfig-Objekt zurück, das selbst im Array advertisers verschachtelt ist.

Hier einige Beispiele für die Ressourcenebene:

Beispiel Effekt
advertiserId Gibt das Feld advertiserId der angeforderten Ressource zurück.
generalConfig/domainUrl Gibt das Feld domainUrl für das generalConfig-Objekt in der angeforderten Ressource zurück.
Mit der untergeordneten Auswahl fordern Sie nur Teile bestimmter Felder an.

Wenn in deiner Anfrage bestimmte Felder spezifiziert werden, gibt der Server standardmäßig die Objekte oder Array-Elemente in ihrer Gesamtheit zurück. Du kannst eine Antwort angeben, die nur bestimmte untergeordnete Felder enthält. Dazu verwendest du die Syntax „( )“ für die untergeordnete Auswahl wie im folgenden Beispiel dargestellt.

Beispiel Effekt
advertisers(advertiserId,generalConfig/domainUrl) Gibt nur die Werte von advertiserId und generalConfigdomainUrl für jedes Element im advertisers-Array zurück.
Umgang mit Teilantworten

Nachdem ein Server eine gültige Anfrage verarbeitet hat, die den fields-Abfrageparameter enthält, sendet er einen 200 OK-HTTP-Statuscode zusammen mit den angeforderten Daten zurück. Wenn der fields-Abfrageparameter einen Fehler enthält oder ungültig ist, gibt der Server den HTTP-Statuscode 400 Bad Request zusammen mit einer Fehlermeldung zurück, die Sie darüber informiert, was bei der Feldauswahl falsch war (Beispiel: "Invalid field selection a/b").