Diese Seite wurde von der Cloud Translation API übersetzt.

Leistungstipps

In diesem Dokument werden einige Techniken beschrieben, mit denen Sie die Leistung Ihrer Anwendung verbessern können. In einigen Fällen werden Beispiele aus anderen APIs oder generischen APIs verwendet, um die vorgestellten Ideen zu erläutern. Die gleichen Konzepte gelten jedoch auch für die Custom Search JSON API.

Komprimierung mit gzip

Durch Aktivierung der gzip-Komprimierung kann die für jede Anfrage benötigte Bandbreite einfach und bequem reduziert werden. Auch wenn die Dekomprimierung der Ergebnisse zusätzliche CPU-Zeit kostet, lohnt sie sich verglichen mit den Netzwerkkosten durchaus.

Sie müssen zwei Schritte ausführen, um eine mit gzip codierte Antwort zu erhalten: Legen Sie einen Header Accept-Encoding fest und ändern Sie den User-Agent so, dass er den String gzip enthält. Hier ein Beispiel für HTTP-Header im korrekten Format zur Aktivierung der gzip-Komprimierung:

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

Mit Teilressourcen arbeiten

Eine andere Möglichkeit zur Verbesserung Ihrer API-Aufrufe besteht darin, nur den Teil der Daten anzufordern, der für Sie relevant ist. Auf diese Weise können Sie verhindern, dass Ihre Anwendung unnötige Felder überträgt, analysiert und speichert. Dadurch können Ressourcen wie Netzwerk, CPU und Speicher effizienter genutzt werden.

Teilantwort

Standardmäßig wird vom Server nach der Verarbeitung einer Anfrage die komplette Darstellung einer Ressource zurückgeliefert. Sie können den Server zwecks Leistungsverbesserung aber auch anweisen, nur die Felder zu senden, die Sie wirklich benötigen, und erhalten dann eine Teilantwort.

Verwenden Sie zum Anfragen einer Teilantwort den Anfrageparameter fields, um anzugeben, welche Felder zurückgegeben werden sollen. Sie können diesen Parameter mit jeder beliebigen Anfrage verwenden, die Antwortdaten zurückgibt.

Beispiel

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

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

https://www.googleapis.com/demo/v1

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

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

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.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Teilantwort: Als Antwort auf die obige Anfrage 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 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 finden Sie 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.
Ausnahme: Bei API-Antworten mit "data"-Wrappern, bei denen die Antwort in einem Objekt vom Typ data in der Form data: { ... } verschachtelt ist, darf "data" nicht in die Spezifikation von fields aufgenommen werden. 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 ein untergeordnetes Auswahlzeichen, um eine Reihe von untergeordneten Feldern von Arrays oder Objekten anzufordern, indem Sie Ausdrücke in Klammern "( )" setzen.
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 auch ein einzelnes Teilfeld angeben, in dem fields=items(id) fields=items/id entspricht.
Verwenden Sie gegebenenfalls Platzhalter bei der Feldauswahl.
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 für eine bessere Lesbarkeit keine Codierung.

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 Sie also einen list-Vorgang ausführen, 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:

Beispiele	Effekt
`items`	Gibt alle Elemente im Element-Array 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 Element-Array zurück.
`items/title`	Gibt nur das `title`-Feld für alle Elemente im Element-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.
`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 Element-Array nur das `title`-Feld (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 Unterfeld `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 Ihrer Anfrage bestimmte Felder spezifiziert werden, gibt der Server standardmäßig die Objekte oder Array-Elemente 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 Element-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 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 die Anfrage an, welche Felder zurückgegeben werden sollen.

https://www.googleapis.com/demo/v1?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 (wie beispielsweise maxResults und nextPageToken) unterstützen, können Sie mit diesen Parametern die Ergebnisse der einzelnen Abfragen auf eine überschaubare Größe reduzieren. Andernfalls wären Leistungssteigerungen mit einer Teilantwort eventuell nicht realisierbar.