Grundlagen zu Berichtsaufgaben

Mit Berichtsaufgaben können Sie eine asynchrone Anfrage mit langer Laufzeit 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 Erstellung 72 Stunden lang verfügbar. Nach diesem Zeitraum werden die entsprechende Ressource „Berichtsaufgabe“ und ihre Inhalte 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 reportTasks.create Methode erforderlich, um eine Berichtsaufgabe zu erstellen. Anschließend wird die reportTasks.query Methode verwendet, um den generierten benutzerdefinierten Bericht abzurufen.

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.

Berichtseinheit auswählen

Für alle Methoden der Data API v1 muss die Google Analytics-Property-ID in einem URL-Anfragepfad im Format properties/GA_PROPERTY_IDangegeben 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 wurden.

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 die reportTasks.create Methode mit dem ReportTask Objekt in einer Anfrage auf, um eine Berichtsaufgabe zu erstellen. Folgende Parameter sind erforderlich:

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

Beispiel für eine Anfrage zur Erstellung 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 einer Berichtsaufgabe abrufen, indem Sie die reportTasks.get Methode aufrufen.

Geben Sie die Berichtsaufgabe mit dem Namen an, den Sie in einer reportTasks.create-Antwort erhalten haben (z. B. properties/1234567/reportTasks/123).

Beispiel:

HTTP-Anfrage

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

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

Das reportMetadata Feld enthält allgemeine Informationen zum generierten Bericht, z. B. die Anzahl der Zeilen und die Anzahl der in Rechnung gestellten 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 reportTasks.list Methode aufrufen.

Generierten Bericht abrufen

Sobald die mit der reportTasks.create Methode erstellte Berichtsaufgabe generiert wurde, rufen Sie die reportTasks.query Methode 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 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"
  }
}