Grundlagen von Berichtsaufgaben

Mit Berichtsaufgaben können Sie eine asynchrone Langzeit-Anfrage starten, um einen benutzerdefinierten Bericht Ihrer Google Analytics-Ereignisdaten zu erstellen.

Mit der aus dieser Anfrage generierten Berichtaufgabenressource können alle Nutzer mit Lesezugriff auf Ihre Google Analytics-Property auf benutzerdefinierte Berichte zugreifen.

Ein benutzerdefinierter Bericht ist nach seiner Fertigstellung 72 Stunden lang verfügbar. Nach Ablauf dieses Zeitraums werden die entsprechende Berichtaufgabenressource und ihr Inhalt automatisch gelöscht.

Berichtsaufgabe erstellen

In der Google Analytics Data API v1 wird ein asynchroner Ansatz zum Erstellen von Berichtsaufgaben verwendet. Zuerst ist eine Anfrage an die Methode reportTasks.create erforderlich, um eine Berichtsaufgabe zu erstellen. Anschließend wird mit der Methode reportTasks.query der generierte benutzerdefinierte Bericht abgerufen.

Außerdem können Sie mit reportTasks.get Konfigurationsmetadaten zu einer bestimmten Berichtsaufgabe abrufen und mit reportTasks.list alle Berichtsaufgaben für eine Property auflisten.

Berichtsentität auswählen

Für alle Methoden der Data API v1 muss die Google Analytics-Property-ID in einem URL-Anforderungspfad im Format properties/GA_PROPERTY_ID angegeben werden, z. B.:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

Der Bericht wird auf Grundlage der Google Analytics-Ereignisdaten erstellt, die in der angegebenen Google Analytics-Property erfasst werden.

Wenn Sie eine der Data API-Clientbibliotheken verwenden, müssen Sie den Anfrage-URL-Pfad nicht manuell bearbeiten. Die meisten API-Clients bieten einen property-Parameter, der einen String im Format properties/GA_PROPERTY_ID erwartet. Beispiele für die Verwendung der Clientbibliotheken finden Sie in der Kurzanleitung.

Berichtserstellung anfordern

Rufen Sie zum Erstellen einer Berichtsaufgabe die Methode reportTasks.create mit dem Objekt ReportTask in einer Anfrage auf. Folgende Parameter sind erforderlich:

  • Das Feld reportDefinition beschreibt die Definition eines benutzerdefinierten Berichts. Die Struktur dieses Parameters ähnelt der Berichtsdefinition, die von Core Reporting-Methoden verwendet wird.

Beispiel für eine Anfrage zum Erstellen einer Berichtsaufgabe:

HTTP-Anfrage

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). Dieser kann in nachfolgenden Abfragen verwendet werden, um den Status einer Berichtsaufgabe abzurufen und den resultierenden Bericht zu erhalten.

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 der Berichtsaufgabe abrufen

Es kann einige Minuten dauern, bis ein Bericht nach dem reportTasks.create-Aufruf generiert 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 in einer reportTasks.create-Antwort erhalten haben, um die Berichtsaufgabe anzugeben.

Beispiel:

HTTP-Anfrage

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

Der Bereitschaftsstatus für eine Berichtsaufgabe wird im Feld state einer Antwort zurückgegeben. Sobald die Berichterstellung abgeschlossen ist, ändert sich der Status einer Berichtsaufgabe von CREATING zu ACTIVE.

Das Feld reportMetadata enthält allgemeine Informationen zum generierten Bericht, z. B. die Anzahl der Zeilen und die Anzahl der abgerechneten Kontingent-Tokens.

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.

Generierten Bericht abrufen

Wenn die mit der Methode reportTasks.create erstellte Berichtsaufgabe generiert wird, rufen Sie die Methode reportTasks.query auf und geben Sie den Namen der Berichtsaufgabe an (z. B. properties/1234567/reportTasks/123).

HTTP-Anfrage

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

Wenn die Berichtsaufgabe abgeschlossen 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"
  }
}