Grundlagen zu Berichtsaufgaben

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

Über die aus dieser Anfrage generierte Berichtsaufgabenressource können alle Nutzer mit Lesezugriff auf Ihre Google Analytics-Property auf benutzerdefinierte Berichte zugreifen.

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

Berichtsaufgabe erstellen

Bei der Google Analytics Data API v1 wird ein asynchroner Ansatz verwendet, um Berichtsaufgaben zu erstellen. Um eine Berichtsaufgabe zu erstellen, ist zuerst eine Anfrage an die Methode reportTasks.create erforderlich. 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.

Berichtseinheit auswählen

Bei allen Methoden der Data API v1 muss die Google Analytics-Property-ID in einem URL-Anfragepfad in Form von 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 generiert, die in der angegebenen Google Analytics-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, für den ein String in Form von properties/GA_PROPERTY_ID erwartet wird. In der Kurzanleitung finden Sie Beispiele für die Verwendung der Clientbibliotheken.

Erstellung der Aufgabe „Bericht“ anfordern

Wenn Sie eine Berichtsaufgabe erstellen möchten, rufen Sie die Methode reportTasks.create mit dem Objekt ReportTask in einer Anfrage auf. Folgende Parameter sind erforderlich:

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 reportTasks.create-Methode 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"
    }
  }
}

Status der Berichterstellung abrufen

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

Das Feld reportMetadata enthält allgemeine Informationen zum generierten Bericht, z. B. die Zeilenanzahl 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 Methode reportTasks.list aufrufen.

Generierten Bericht abrufen

Nachdem die Berichtsaufgabe, die mit der Methode reportTasks.create erstellt wurde, generiert wurde, 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 fertig 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"
  }
}