Grundlagen von Berichtsaufgaben

Mit Berichtsaufgaben können Sie eine lang andauernde 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 der Erstellung 72 Stunden lang verfügbar. Nach diesem Zeitraum werden die entsprechende Berichtsaufgabe und ihr Inhalt automatisch gelöscht.

Berichtsaufgabe erstellen

Die Google Analytics Data API v1 verwendet einen asynchronen Ansatz, um Berichtsaufgaben zu erstellen. Zuerst ist eine Anfrage an die Methode reportTasks.create erforderlich, um eine Berichtsaufgabe zu erstellen. Anschließend wird die Methode reportTasks.query 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.

Berichtsentität auswählen

Bei allen Methoden der Data API v1 muss die Google Analytics-Property-ID in einem URL-Anfragepfad 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 wurden.

Wenn Sie eine der Data API-Clientbibliotheken verwenden, müssen Sie den Anfrage-URL-Pfad nicht manuell bearbeiten. Die meisten API-Clients stellen einen property-Parameter bereit, 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 Berichtsaufgabe die Methode reportTasks.create mit dem Objekt ReportTask in einer Anfrage auf. Folgende Parameter sind erforderlich:

  • reportDefinition-Feld, das die Definition eines benutzerdefinierten Berichts beschreibt. 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 aus 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 Anzahl der Zeilen und die Anzahl der berechneten Kontingenttokens.

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

Nächste Schritte