Grundlagen von Berichtsaufgaben

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

Die aus dieser Anfrage generierte Berichtsaufgabenressource 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 diesem Zeitraum werden die entsprechende Berichtsaufgabenressource 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 in der angegebenen Google Analytics-Property erfassten Google Analytics-Ereignisdaten generiert.

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.

Beispielanfrage zur Erstellung einer Berichtsaufgabe:

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.

{
  "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

Nach dem Aufruf von reportTasks.create kann es einige Minuten dauern, bis ein Bericht generiert wird. Sie können den Bereitschaftsstatus für eine 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:

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

Der Bereitschaftsstatus für eine Berichtsaufgabe wird im state Feld einer Antwort zurückgegeben. Sobald die Berichterstellung abgeschlossen ist, ändert sich der Status einer Berichtsaufgabe von CREATING zu 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.

{
  "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

Wenn 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).

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:

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}