Google Analytics API-Anfragen im Batch verarbeiten

In diesem Dokument erfahren Sie, wie API-Aufrufe in einem Batch zusammengefasst werden, um die Anzahl von HTTP-Verbindungen für den Client zu reduzieren.

In diesem Dokument geht es speziell um das Erstellen einer Batchanfrage durch Senden einer HTTP-Anfrage. Wenn Sie stattdessen eine Google-Clientbibliothek für die Batchanfrage verwenden, finden Sie entsprechende Informationen in der Dokumentation der Clientbibliothek.

Überblick

Jede HTTP-Verbindung, die der Client erstellt, führt zu einem bestimmten Overhead. Die Google Analytics API unterstützt die Batchverarbeitung, damit Ihr Client mehrere API-Aufrufe in einer einzelnen HTTP-Anfrage zusammenfassen kann.

Fallbeispiele für den Einsatz von Batchanfragen:

In jedem Fall können Sie die Aufrufe in einer einzigen HTTP-Anfrage gruppieren, anstatt jeden Aufruf einzeln zu senden. Alle inneren Anfragen müssen an dieselbe Google API gesendet werden.

Pro Batchanfrage sind maximal 1.000 Aufrufe möglich. Wenn Sie mehr Aufrufe ausführen müssen, verwenden Sie mehrere Batchanfragen.

Hinweis: Das Batchsystem der Google Analytics API verwendet dieselbe Syntax wie das Batchverarbeitungssystem OData, aber mit einer anderen Semantik.

Batchdetails

Eine Batchanfrage besteht aus mehreren, in einer HTTP-Anfrage zusammengefassten API-Aufrufen. Sie kann an den im Discovery-Dokument der API angegebenen batchPath gesendet werden. Der Standardpfad ist /batch/api_name/api_version. In diesem Abschnitt wird die Batchsyntax im Detail beschrieben. Anschließend finden Sie ein Beispiel.

Hinweis: Wenn n Anfragen in Batches zusammengefasst sind, werden sie als n-Anfragen und nicht als eine Anfrage auf Ihr Nutzungslimit angerechnet. Die Batchanfrage wird vor der Verarbeitung in eine Reihe von Anfragen aufgeteilt.

Format einer Batchanfrage

Eine Batchanfrage ist eine einzelne Standard-HTTP-Anfrage mit mehreren Google Analytics API-Aufrufen. Dabei wird der Inhaltstyp multipart/mixed verwendet. Jeder Teil der HTTP-Hauptanfrage enthält eine verschachtelte HTTP-Anfrage.

Jeder Teil beginnt mit seinem eigenen HTTP-Header Content-Type: application/http. Er kann auch einen optionalen Content-ID-Header haben. Die Header der einzelnen Teile sollen jedoch nur den Anfang des Teils markieren. Sie sind von der verschachtelten Anfrage getrennt. Nachdem der Server die Batchanfrage in separate Anfragen aufgeteilt hat, werden die Header der einzelnen Teile ignoriert.

Der Text jedes Teils ist an sich eine vollständige HTTP-Anfrage mit eigenem Verb, eigener URL, eigenen Headern und eigenem Text. Die HTTP-Anfrage darf nur den Pfadteil der URL enthalten; vollständige URLs sind in Batchanfragen nicht zulässig.

Die HTTP-Header für die äußere Batchanfrage gelten für jede Anfrage in dem Batch, ausgenommen Content--Header wie Content-Type. Wenn Sie einen bestimmten HTTP-Header sowohl in der äußeren Anfrage als auch in einem individuellen Aufruf verwenden, überschreibt der Wert des individuellen Aufrufheaders den Wert des Headers der äußeren Stapelanfrage. Die Header für einen individuellen Aufruf gelten nur für diesen Aufruf.

Beispiel: Wenn Sie einen Autorisierungsheader für einen bestimmten Aufruf angeben, gilt dieser Header nur für diesen Aufruf. Wenn Sie einen Autorisierungsheader für die äußere Anfrage angeben, gilt dieser Header für alle einzelnen Aufrufe, es sei denn, diese überschreiben ihn mit eigenen Autorisierungsheadern.

Wenn der Server die Stapelanfrage empfängt, wendet er (nach Bedarf) die Abfrageparameter und Header der äußeren Anfrage für jeden Teil an, und behandelt jeden Teil dann so, als wäre er eine separate HTTP-Anfrage.

Antwort auf eine Batchanfrage

Die Antwort des Servers ist eine einzelne Standard-HTTP-Antwort mit einem Inhaltstyp multipart/mixed. Jeder Teil ist die Antwort auf eine der Anfragen in der Batchanfrage in derselben Reihenfolge wie die einzelnen Anfragen.

Wie die Teile in der Anfrage enthält jeder Antwortteil eine vollständige HTTP-Antwort, einschließlich Statuscode, Headern und Text. Wie auch bei den Teilen in der Anfrage ist jedem Antwortteil ein Content-Type-Header vorangestellt, der den Beginn des Teils markiert.

Wenn ein bestimmter Teil einer Anfrage einen Content-ID-Header enthielt, enthält der entsprechende Teil der Antwort einen übereinstimmenden Content-ID-Header, wobei dem ursprünglichen Wert der String response- vorangestellt ist, wie im folgenden Beispiel dargestellt.

Hinweis: Der Server kann die Aufrufe in beliebiger Reihenfolge ausführen. Die Aufrufe werden nicht unbedingt in der Reihenfolge ausgeführt, in der Sie sie angegeben haben. Wenn Sie sicherstellen möchten, dass zwei Aufrufe in einer bestimmten Reihenfolge ausgeführt werden, können Sie sie nicht in einer einzelnen Anfrage senden. Senden Sie stattdessen den ersten Aufruf für sich alleine und warten Sie auf die Antwort auf den ersten Aufruf, bevor Sie den zweiten Aufruf senden.

Beispiel

Das folgende Beispiel zeigt die Verwendung von Batchanfragen mit der Google Analytics API.

Beispiel-Batchanfrage

POST /batch/analytics/v3 HTTP/1.1
Host: www.googleapis.com
Content-length: 731
Content-type: multipart/mixed; boundary=batch_0123456789
Authorization: Bearer ya29.5gFZooleNoSpGqYOOF0eFciUGz1x26k9GagZoW7HJCogWlCoNOotxlZPo7bDbwo1ykDq
--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 68


{
 "name": "Campaign Group",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 67


{
 "name": "Campaign Type",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789--

Beispiel für eine Stapelantwort

Dies ist die Antwort auf die Beispielanfrage im vorherigen Abschnitt.

HTTP/1.1 200 OK
Content-length: 1876
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Vary: Origin,X-Origin
Server: GSE
Cache-control: private, max-age=0
Date: Wed, 02 Sep 2015 21:36:35 GMT
X-frame-options: SAMEORIGIN
Content-type: multipart/mixed; boundary=batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/L-Y_3uM9BpST8Sea-SJDRQ7N7vE"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 548

{"kind":"analytics#customDimension","id":"ga:dimension18","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Group","index":18,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:34.143Z","updated":"2015-09-02T21:36:34.143Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension18","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/VN-21fLS1T0Qko3pHEB5fi8vYJ8"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 547

{"kind":"analytics#customDimension","id":"ga:dimension19","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Type","index":19,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:35.099Z","updated":"2015-09-02T21:36:35.099Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension19","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q--

Clientbibliotheken

In den folgenden Leitfäden zu Clientbibliotheken erfahren Sie, wie Sie Batching in Ihrer Sprache implementieren:

Batch-Verarbeitung und Google Analytics-Kontingent

Mit Batchanfragen sparen Sie sich den Aufwand, viele HTTP-Anfragen zu erstellen. Jede Google Analytics API-Anfrage wird dabei auf Ihr tägliches Projektkontingent angerechnet. Standardmäßig kann ein Projekt bis zu 50.000 Anfragen pro Tag stellen. Die Batchverarbeitung trägt nicht dazu bei,dieses Kontingent nicht zu überschreiten.

Mit Ausnahme von aufeinanderfolgenden Anfragen zum Schreiben (Löschen, Einfügen, Aktualisieren) von Nutzerberechtigungen gelten weiterhin alle Ratenbegrenzungen. Beispielsweise ist die Core Reporting API auf 10 gleichzeitige Anfragen pro Datenansicht (Profil) beschränkt. Die Batchverarbeitung hilft Ihnen nicht, unter diesem Limit zu bleiben.

Das Limit von 1,5 Abfragen pro Sekunde pro Konto-ID gilt für Schreibanfragen für die Management API und Schreibanfragen für die Provisioning API. Die Leistung dieser Schreibanfragen in Batches wird daher möglicherweise nicht verbessert.