Grundlagen zu Berichtsaufgaben

Mithilfe von Berichtsaufgaben können Sie eine lang andauernde asynchrone Anfrage starten, um einen benutzerdefinierten Bericht mit Ihren Google Analytics-Ereignisdaten

Über die in dieser Anfrage generierte Berichtsaufgaben-Ressource kann auf benutzerdefinierte Berichte von allen Nutzern mit Lesezugriff auf Ihr Google Analytics-Konto Property.

Ein benutzerdefinierter Bericht ist dann 72 Stunden lang verfügbar. Danach werden die entsprechende Ressource für die Berichtaufgabe und ihr Inhalt automatisch gelöscht.

Berichtaufgabe erstellen

Das Google Analytics Data API v1 nutzt einen asynchronen Ansatz zur Berichtsaufgaben erstellen. Zunächst muss eine Anfrage an den reportTasks.create ist erforderlich, um eine Berichtaufgabe zu erstellen. Das Feld reportTasks.query wird verwendet, um den generierten benutzerdefinierten Bericht abzurufen.

Darüber hinaus können Sie reportTasks.get zum Abrufen von Konfigurationsmetadaten zu einer bestimmten Berichtaufgabe und reportTasks.list um alle Berichtsaufgaben für eine Property aufzulisten.

Berichtseinheit auswählen

Alle Methoden des Data API v1 erfordern die Google Analytics-Property-ID in einem URL-Anfragepfad in der Form properties/GA_PROPERTY_ID, z. B.:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

Der Bericht wird auf Grundlage des Google Analytics-Ereignisses erstellt. Daten, die in der angegebenen Google Analytics-Property erhoben wurden.

Wenn Sie eine der Data API-Clientbibliotheken verwenden, muss der Anforderungs-URL-Pfad nicht manuell bearbeitet werden. Die meisten API-Clients stellen einen property-Parameter bereit, der eine im Format properties/GA_PROPERTY_ID. Beispiele finden Sie in der Kurzanleitung. der Client-Bibliotheken.

Erstellen der Berichtsaufgabe anfordern

Rufen Sie zum Erstellen einer Berichtaufgabe die Methode reportTasks.create mit der Methode ReportTask -Objekt in einer Anfrage. 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 Methode reportTasks.create enthält den Bericht Aufgabenname im Feld name (z. B. properties/1234567/reportTasks/123), die in können Sie nachfolgende Abfragen ausführen, um den Status einer Berichtaufgabe zu ermitteln und den damit der Bericht erstellt wird.

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 für Berichtsaufgaben abrufen

Es kann einige Minuten dauern, bis ein Bericht reportTasks.create aufrufen. Sie können den Bereitschaftsstatus für eine Berichtaufgabe abrufen, indem Sie die Methode reportTasks.get .

Verwenden Sie den Namen der Berichtsaufgabe (z. B. properties/1234567/reportTasks/123). die Sie von einer reportTasks.create-Antwort erhalten haben, Aufgabe melden.

Beispiel:

HTTP-Anfrage

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

Der Bereitschaftsstatus für eine Berichtaufgabe wird im state einer Antwort. Sobald der Bericht erstellt ist, Der Status einer Berichtaufgabe ändert sich von CREATING in ACTIVE.

Die reportMetadata enthält allgemeine Informationen über den generierten Bericht, wie 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 .

Generierten Bericht abrufen

Nachdem die Berichtaufgabe mit der Methode reportTasks.create generiert wird, rufen Sie die Methode reportTasks.query und geben Sie den Namen der Berichtaufgabe an. (z. B. properties/1234567/reportTasks/123).

HTTP-Anfrage

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

Wenn die Berichtaufgabe 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"
  }
}