Mithilfe von Berichtsaufgaben können Sie eine lange laufende asynchrone Anfrage zum Erstellen eines benutzerdefinierten Berichts Ihrer Google Analytics-Ereignisdaten starten.
Mit der Berichtaufgabenressource, die über diese Anfrage generiert wird, können alle Nutzer mit Lesezugriff auf Ihre Google Analytics-Property auf benutzerdefinierte Berichte zugreifen.
Ein benutzerdefinierter Bericht ist nach Erstellung 72 Stunden verfügbar. Nach diesem Zeitraum werden die entsprechende Berichtsaufgabe und ihr Inhalt automatisch gelöscht.
Berichtsaufgabe erstellen
Die Google Analytics Data API v1 verwendet einen asynchronen Ansatz zum Erstellen von Berichtsaufgaben. Zuerst ist eine Anfrage an die Methode reportTasks.create erforderlich, um eine Berichtsaufgabe zu erstellen. Anschließend wird die Methode reportTasks.query verwendet, um den generierten benutzerdefinierten Bericht abzurufen.
Darüber hinaus können Sie mit reportTasks.get Konfigurationsmetadaten zu einer bestimmten Berichtsaufgabe abrufen und mit reportTasks.list alle Berichtsaufgaben für eine Property auflisten.
Meldeentität auswählen
Bei allen Methoden der Data API Version 1 muss die Google Analytics 4-Property-ID in einem URL-Anfragepfad im Format properties/GA4_PROPERTY_ID angegeben werden. Beispiel:
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID/reportTasks
Der Bericht wird anhand der Google Analytics-Ereignisdaten erstellt, die in der angegebenen Google Analytics 4-Property erfasst wurden.
Wenn Sie eine der Data API-Clientbibliotheken verwenden, müssen Sie den URL-Pfad der Anfrage nicht manuell bearbeiten.
Die meisten API-Clients bieten einen property-Parameter, der einen String in Form von properties/GA4_PROPERTY_ID erwartet.
Beispiele zur Verwendung der Clientbibliotheken finden Sie in der Kurzanleitung.
Erstellen der Berichtsaufgabe anfordern
Rufen Sie zum Erstellen einer Berichtsaufgabe die Methode reportTasks.create mit dem Objekt ReportTask in einer Anfrage auf. Folgende Parameter sind erforderlich:
reportDefinition-Feld, das die Definition eines benutzerdefinierten Berichts beschreibt. Die Struktur dieses Parameters ähnelt der Berichtsdefinition, die von Methoden für Kernberichte verwendet wird.
Beispiel für eine Anfrage zum Erstellen einer Berichtsaufgabe:
HTTP-Request
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
"reportDefinition": {
"dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
}
Eine Antwort der Methode reportTasks.create enthält den Namen der Berichtsaufgabe im Feld name (z. B. properties/1234567/reportTasks/123), der in nachfolgenden Abfragen verwendet werden kann, um den Status einer Berichtsaufgabe und den daraus resultierenden Bericht abzurufen.
HTTP-Antwort
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
"name": "properties/1234567/reportTasks/123",
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "CREATING",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
}
}
}
Bereitschaftsstatus von Berichtsaufgaben abrufen
Nach dem reportTasks.create-Aufruf kann es einige Minuten dauern, bis ein Bericht erstellt wird. Sie können den Bereitschaftsstatus für eine Berichtsaufgabe abrufen, indem Sie die Methode reportTasks.get aufrufen.
Verwenden Sie den Namen der Berichtsaufgabe (z. B. properties/1234567/reportTasks/123), den Sie mit einer reportTasks.create-Antwort erhalten haben, um die Berichtsaufgabe anzugeben.
Beispiel:
HTTP-Request
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123
Der Bereitschaftsstatus einer Berichtsaufgabe wird im Feld state einer Antwort zurückgegeben. Sobald der Bericht erstellt wurde, ändert sich der Status einer Berichtsaufgabe von CREATING in ACTIVE.
Das Feld reportMetadata enthält allgemeine Informationen zum erstellten Bericht, z. B. die Anzahl der Zeilen und die Menge der berechneten Kontingenttokens.
HTTP-Antwort
{
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "ACTIVE",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
"creationQuotaTokensCharged": 6,
"taskRowCount": 167,
"errorMessage": "",
"totalRowCount": 167
}
}
Sie können den Status aller Berichtsaufgaben abrufen, indem Sie die Methode reportTasks.list aufrufen.
Erstellten Bericht abrufen
Nachdem die mit der Methode reportTasks.create erstellte Berichtsaufgabe generiert wurde, rufen Sie die Methode reportTasks.query auf und geben Sie den Namen der Berichtsaufgabe an (z. B. properties/1234567/reportTasks/123).
HTTP-Request
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query
Wenn die Berichtsaufgabe bereit ist, wird eine Antwort mit dem generierten Bericht zurückgegeben:
HTTP-Antwort
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
...
],
"rowCount": 167,
"metadata": {
"currencyCode": "USD",
"timeZone": "America/Los_Angeles"
}
}