Leistungstipps

Mit den in diesem Dokument beschriebenen Verfahren kann die Funktionsweise Ihrer Anwendung verbessert werden. In einigen Fällen werden Beispiele aus anderen APIs oder generischen APIs verwendet, um die vorgestellten Ideen zu illustrieren. Die gleichen Konzepte können jedoch auch auf die Google Cloud Deployment Manager V2 API angewendet werden.

Gzip verwenden

Sie können die für die einzelnen Anforderungen erforderliche Bandbreite einfach und bequem reduzieren, indem Sie Komprimierung mit Gzip aktivieren. Obwohl hierfür weitere CPU-Zeit zur Dekomprimierung der Ergebnisse erforderlich ist, ist sie im Verhältnis zu den Netzwerkkosten normalerweise von großem Vorteil.

Zwei Dinge sind notwendig, um eine Gzip-kodierte Antwort zu erhalten: Legen Sie eine Accept-Encoding-Kopfzeile fest und nehmen Sie die Zeichenfolge gzip in Ihren User-Agent auf. Hier ein Beispiel für korrekt formulierte HTTP-Kopfzeilen für die Aktivierung von Gzip-Komprimierung:

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

Mit Teilressourcen arbeiten

Eine andere Möglichkeit zur Verbesserung Ihrer API-Anrufe besteht darin, nur den Teil der Daten zu senden und zu empfangen, der für Sie interessant ist. Hiermit kann Ihre Anwendung die Übertragung, Analyse und Speicherung nicht benötigter Felder vermeiden, damit sie Ressourcen wie Netzwerke, CPU und Speicher effizienter nutzen kann.

Es gibt zwei Arten von Teil-Requests:

Teilantwort: Ein Request, in dem Sie angeben können, welche Felder in der Antwort enthalten sein sollen (verwenden Sie den Request-Parameter fields).
Patch: Ein Aktualisierungs-Request, bei dem Sie nur die Felder senden, die Sie ändern möchten (mit dem PATCH HTTP-Verb).

Die folgenden Abschnitte enthalten weitere Details zu Teil-Requests.

Teilantwort

Standardmäßig gibt der Server die komplette Darstellung einer Ressource nach der Verarbeitung der Requests zurück. Um die Wirkung zu erhöhen, können Sie den Server anweisen, nur die Dateien zu senden, die Sie wirklich brauchen, und stattdessen eine Teilantwort zu erhalten.

Verwenden Sie zum Anfragen einer Teilantwort den Request-Parameter fields, um die zurückzugebenden Felder anzugeben. Sie können diesen Parameter mit einem beliebigen Request verwenden, durch den Antwortdaten zurückgegeben werden.

Beachten Sie, dass sich der Parameter fields nur auf die Antwortdaten auswirkt; er wird nicht auf zu sendende Daten angewendet. Mit dem Request patch kann die Datenmenge reduziert werden, die beim Ändern von Ressourcen gesendet wird.

Beispiel

Das folgende Beispiel zeigt die Verwendung des Parameters fields mit einer generischen (fiktiven) "Demo"-API.

Einfacher Request: Bei dieser HTTP-GET-Anfrage wird der fields-Parameter weggelassen und die komplette Ressource zurückgegeben.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY

Vollständige Ressourcenantwort: Zu den kompletten Ressourcendaten gehören außer vielen anderen, die wegen der Übersichtlichkeit weggelassen werden, die folgenden Felder.

{
  "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",
    ...
  },
  ...
  ]
}

Request einer Teilantwort: Im folgenden Request dieser Ressource wird der Parameter fields verwendet, um die zurückgegebene Datenmenge zu verringern.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)

Teilantwort: Als Antwort auf den obigen Request sendet der Server eine Antwort zurück, die zusammen mit einem einfachen Array nur die Art von Informationen enthält, die ausschließlich HTML-Titel und Längeneigenschaften in jedem Element umfassen.

200 OK

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

Bei der Antwort handelt es sich um ein JSON-Objekt, das nur die ausgewählten Felder und deren einschließende übergeordnete Objekte enthält.

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

Parameter "fields" – Syntaxzusammenfassung

Das Format des Request-Parameters fields basiert lose auf der XPath-Syntax. Die unterstützte Syntax wird unten zusammengefasst. Zusätzliche Beispiele werden im darauffolgenden Abschnitt aufgeführt.

Mit einer durch Kommas abgetrennten Liste können Sie mehrere Felder auswählen.
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.

Ausnahme: Bei API-Antworten, in denen "Data" Wrapper verwendet werden, bei denen die Antwort in einem data-Objekt verschachtelt ist, das wie data: { ... }, aussieht, nehmen Sie "data" nicht in die fields-Spezifikation auf. Die Aufnahme eines Datenobjekts in einer Feldspezifikation wie data/a/b führt zu einem Fehler. Verwenden Sie stattdessen eine fields-Angabe wie a/b.
Verwenden Sie einen untergeordneten Selektor, um eine Reihe von untergeordneten Feldern von Arrays oder Objekten anzufordern, indem Sie Ausdrücke in Klammern "( )" setzen.
Zum Beispiel: fields=items(id,author/email) gibt nur die Element-ID und die E-Mail-Adresse des Autors für jedes Element im Array zurück. Sie können Sie einen einzelnes Teilfeld angeben, in dem fields=items(id) mit fields=items/id übereinstimmt.
Verwenden Sie bei Bedarf Wildcards in Feldauswahlen.
Zum Beispiel: Mit fields=items/pagemap/* werden alle Objekte in einer Pagemap ausgewählt.

Weitere Beispiele zur Verwendung des Parameters "fields"

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

Hinweis: Wie bei allen Abfrageparameterwerten muss der Wert des Parameters fields URL-codiert sein. Die Beispiele in diesem Dokument enthalten keine Codierung für eine bessere Lesbarkeit.

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

Der Wert des Request-Parameters fields besteht aus einer durch Komma getrennten Liste mit Feldern. Jedes Feld wird bezogen auf die Root der Antwort angegeben. Wenn Sie also einen list-Vorgang ausführen, besteht die Antwort aus einer Sammlung und enthält im Allgemeinen ein Ressourcenarray. 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:

Beispiele	Effekt
`items`	Gibt alle Elemente im Elementarray zurück, einschließlich aller Felder in jedem Element, jedoch keine anderen Felder.
`etag,items`	Gibt sowohl das `etag`-Feld als auch alle Elemente im Elementarray zurück.
`items/title`	Gibt nur das `title`-Feld für alle Elemente im Elementarray 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.
`context/facets/label`	Gibt nur das Feld `label` für alle Mitglieder des Arrays `facets` zurück, das selbst unter dem Objekt `context` verschachtelt ist.
`items/pagemap/*/title`	Gibt für jedes Element im Elementarray nur das Feld `title` (sofern vorhanden) aller Objekte zurück, die untergeordnete Objekte von `pagemap` sind.

Hier einige Beispiele für die Ressourcenebene:

Beispiele	Effekt
`title`	Gibt das Feld `title` der angeforderten Ressource zurück.
`author/uri`	Gibt das untergeordnete Feld `uri` des Objekts `author` in der angeforderten Ressource zurück.
`links/*/href`	Gibt das Feld `href` aller Objekte zurück, die untergeordnete Objekte von `links` sind.

Mit der untergeordneten Auswahl fordern Sie nur Teile bestimmter Felder an.

Wenn in dem Request bestimmte Felder angegeben werden, gibt der Server standardmäßig die Objekte oder Arrayelemente in ihrer Gesamtheit zurück. Sie können eine Antwort angeben, die nur bestimmte untergeordnete Felder enthält. Dazu verwenden Sie die Syntax "( )" für die untergeordnete Auswahl, wie im folgenden Beispiel dargestellt.

Beispiel	Effekt
`items(title,author/uri)`	Gibt nur die Werte von `title` und den `uri` des Autors für jedes Element im Elementarray zurück.

Umgang mit Teilantworten

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

Hier ein Beispiel für eine Teilantwort, die im einführenden Abschnitt oben dargestellt wurde. Mit dem Parameter fields gibt der Request an, welche Felder zurückgegeben werden sollen.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)

Die Teilantwort sieht folgendermaßen aus:

200 OK

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

Hinweis: Bei APIs, die Abfrageparameter für die Datenpaginierung (zum Beispiel maxResults und nextPageToken) unterstützen, verwenden Sie diese Parameter, um die Ergebnisse jeder Abfrage auf eine überschaubare Größe zu reduzieren. Andernfalls wären Leistungsgewinne mit einer Teilantwort eventuell nicht realisierbar.

Patch (Teilaktualisierung)

Sie können auch das Senden von unnötigen Daten vermeiden, wenn Sie Ressourcen ändern. Um nur aktualisierte Daten für die Felder zu senden, die Sie ändern, verwenden Sie das HTTP-Verb PATCH. Die Patch-Semantik, die in diesem Dokument beschrieben wird, ist anders (und einfacher) als die der älteren GData-Implementierung von Teilaktualisierungen.

Das kurze Beispiel unten zeigt, wie mit Patch die Datenmenge, die Sie benötigen, um ein kleines Update durchzuführen, minimiert wird.

Beispiel

Dieses Beispiel zeigt einen einfachen Patch-Request, mit dem nur der Titel einer allgemeinen (fiktiven) "Demo"-API-Ressource aktualisiert werden soll. Die Ressource enthält auch einen Kommentar, eine Reihe von Eigenschaften, Status- und viele andere Felder, dieser Request sendet jedoch nur das Feld title, da dieses Feld als einziges geändert wird:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

Antwort

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

Der Server gibt einen 200 OK-Statuscode zusammen mit der vollständigen Darstellung der aktualisierten Ressource zurück. Da nur das Feld title in dem Patch-Request enthalten war, ist dies der einzige Wert, der sich von den vorherigen Werten unterscheidet.

Hinweis: Wenn Sie den Teilantwort-Parameter fields in Verbindung mit "patch" verwenden, können Sie die Effizienz der Aktualisierungs-Requests noch weiter verbessern. Ein Patch-Request reduziert nur die Größe des Requests. Eine Teilantwort reduziert die Größe der Antwort. Um also die in beiden Richtungen gesendete Datenmenge zu reduzieren, verwenden Sie einen Patch-Request mit dem fields-Parameter.

Semantik eines Patch-Requests

Der Text des Patch-Requests umfasst nur die Ressourcenfelder, die Sie ändern möchten. Bei der Angabe eines Feldes müssen Sie einschließende übergeordnete Objekte einbeziehen, weil die einschließenden übergeordneten Objekte mit einer Teilantwort zurückgegeben. Die geänderten Daten, die Sie senden, werden mit den Daten für das übergeordnete Objekt zusammengeführt, sofern vorhanden.

Hinzufügen: Um ein Feld hinzuzufügen, das noch nicht vorhanden ist, geben Sie das neue Feld und dessen Wert an.
Ändern: Um den Wert eines vorhandenen Feldes zu ändern, geben Sie das Feld an und legen es auf den neuen Wert fest.
Löschen: Um ein Feld zu löschen, geben Sie das Feld an und setzen es auf null. Zum Beispiel "comment": null. Sie können auch ein ganzes Objekt löschen (wenn es änderbar ist), indem Sie es auf null setzen. Wenn Sie die Java API-Clientbibliothek nutzen, verwenden Sie Data..NULL_STRING. Einzelheiten finden Sie unter JSON null.

Hinweis zu Arrays: Patch-Requests, die Arrays enthalten, ersetzen das vorhandene Array durch das Array, das Sie angeben. Sie können ein Array nicht stückweise ändern, hinzufügen oder löschen.

Patch in einem Read-Modify-Write-Zyklus verwenden

Es kann in der Praxis sinnvoll sein, wenn Sie als erstes eine Teilantwort mit den Daten abrufen, die Sie ändern möchten. Dies ist besonders wichtig bei Ressourcen, die ETags verwenden, weil Sie den aktuellen ETag-Wert im HTTP-Header If-Match angeben müssen, um die Ressource erfolgreich zu aktualisieren. Nachdem Sie die Daten abgerufen haben, können Sie die zu ändernden Werte modifizieren und die modifizierte Teildarstellung mit einem Patch-Request zurücksenden. Hier ein Beispiel, bei dem davon ausgegangen wird, dass die Demo-Ressource ETags verwendet:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

Dies ist die Teilantwort:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

Der folgende Patch-Request basiert auf dieser Antwort. Wie unten dargestellt, verwendet der Request auch den Parameter fields, um die in der Patch-Antwort zurückgegebenen Daten zu begrenzen:

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. */
  },
}

Der Server antwortet mit einem HTTP-Statuscode "200 OK" und der Teildarstellung der aktualisierten Ressource:

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. */
  }
}

Patch-Request direkt erstellen

Einige Patch-Requests müssen auf den Daten aufbauen, die Sie vorher abgerufen haben. Wenn Sie zum Beispiel ein Element einem Array hinzufügen und keines der vorhandenen Arrayelemente verlieren möchten, müssen Sie zuerst die vorhandenen Daten abrufen. Wenn eine API ETags verwendet, müssen Sie den vorherigen ETag-Wert mit dem Request senden, damit die Ressource erfolgreich aktualisiert werden kann.

Hinweis: Sie können einen HTTP-Header "If-Match: *" verwenden, um die Ausführung eines Patch zu erzwingen, wenn ETags verwendet werden. In diesem Fall müssen Sie den Lesevorgang nicht vor dem Schreibvorgang ausführen.

In anderen Fällen können Sie den Patch-Request direkt erstellen, ohne zuvor die vorhandenen Daten abzurufen. Beispiel: Sie können jederzeit einen Patch-Request einrichten, der ein Feld mit einem neuen Wert aktualisiert oder ein neues Feld hinzufügt. Hier ein Beispiel:

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
  }
}

Wenn das Kommentarfeld bei diesem Request einen vorhandenen Wert hat, überschreibt der neue Wert diesen. Sonst wird er auf den neuen Wert festgelegt. Wenn eine Volumeneigenschaft vorhanden war, wird ihr Wert ebenfalls überschrieben; wenn nicht, wird sie erstellt. Das Genauigkeitsfeld wird entfernt, falls festgelegt.

Umgang mit der Antwort auf ein Patch

Nachdem ein gültiger Patch-Request verarbeitet wurde, gibt die API einen HTTP-Antwortcode 200 OK zusammen mit der vollständigen Darstellung der geänderten Ressource zurück. Wenn ETags von der API verwendet werden, aktualisiert der Server ETag-Werte, wenn ein Patch-Request erfolgreich verarbeitet wird, wie bei PUT.

Der Patch-Request gibt die vollständige Ressourcendarstellung zurück, es sei denn, Sie verwenden den fields-Parameter, um die zurückgegebene Datenmenge zu reduzieren.

Wenn ein Patch-Request zu einem neuen Ressourcenstatus führt, der syntaktisch oder semantisch ungültig ist, gibt der Server einen HTTP-Statuscode 400 Bad Request oder 422 Unprocessable Entity zurück, und der Ressourcenstatus bleibt unverändert. Beispiel: Wenn Sie versuchen, den Wert für ein Pflichtfeld zu löschen, gibt der Server einen Fehler zurück.

Alternative Schreibweise, wenn das PATCH-HTTP-Verb nicht unterstützt wird

Wenn Ihre Firewall keine HTTP-PATCH-Requests unterstützt, führen Sie einen HTTP-POST-Request aus und setzen den Override-Header auf PATCH, wie unten dargestellt:

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

Unterschied zwischen Patch und Update

Wenn Sie in der Praxis Daten für einen Update-Request senden, der das HTTP-Verb PUT verwendet, müssen Sie nur die Felder senden, die erforderlich oder optional sind. Wenn Sie Werte für Felder senden, die vom Server festgelegt werden, werden diese ignoriert. Obwohl dies wie eine andere Möglichkeit für eine Teilaktualisierung aussieht, hat dieser Ansatz einige Einschränkungen. Mit Aktualisierungen, die das HTTP-Verb PUT verwenden, schlägt der Request fehl, wenn Sie erforderliche Parameter nicht angeben. Vorher festgelegten Daten werden gelöscht, wenn Sie keine optionalen Parameter angeben.

Aus diesem Grund ist die Verwendung eines Patch wesentlich sicherer. Sie geben nur Daten für die Felder an, die Sie ändern möchten; Felder, die Sie weglassen, werden nicht entfernt. Sich wiederholende Elemente oder Arrays sind die einzige Ausnahme zu dieser Regel. Wenn Sie diese alle weglassen, bleiben sie unverändert. Wenn Sie ein Element oder Array angeben, wird das ganze Set durch das Set ersetzt, das Sie angeben.