Grundlagen zu Berichtsaufgaben

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

Die aus dieser Anfrage generierte Ressource „Berichtsaufgabe“ kann von allen Nutzern mit Lesezugriff auf Ihre Google Analytics-Property verwendet werden, um auf benutzerdefinierte Berichte zuzugreifen.

Ein benutzerdefinierter Bericht ist nach seiner Fertigstellung 72 Stunden lang verfügbar. Nach Ablauf dieses Zeitraums werden die entsprechende Ressource für die Berichtsaufgabe und ihre Inhalte 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 reportTasks.get verwenden, um Konfigurationsmetadaten zu einer bestimmten Berichtsaufgabe abzurufen, und reportTasks.list, um alle Berichtsaufgaben für eine Property aufzulisten.

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 anhand 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.

Erstellung der Berichtsaufgabe anfordern

Rufen Sie zum Erstellen einer Report Task 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.

Beispielanfrage 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 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 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. Wenn die Berichterstellung abgeschlossen ist, ändert sich der Status einer Berichtsaufgabe von CREATING in 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

Nachdem die mit der Methode reportTasks.create erstellte Report Task generiert wurde, rufen Sie die Methode reportTasks.query auf und geben Sie den Namen der Report Task 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"
  }
}