Podstawy raportowania zadań

Za pomocą zadań raportu możesz rozpocząć długotrwałe żądanie asynchroniczne, aby utworzyć niestandardowy raport z danymi zdarzeń Google Analytics.

Zasób zadania dotyczącego raportu wygenerowany na podstawie tego żądania może być używany przez wszystkich użytkowników z dostępem tylko do odczytu do usługi w Google Analytics w celu uzyskiwania dostępu do raportów dostosowanych.

Niestandardowy raport będzie dostępny przez 72 godziny od momentu jego utworzenia. Po upływie tego czasu odpowiedni zasób zadania raportu i jego zawartość zostaną automatycznie usunięte.

Tworzenie zadania dotyczącego raportu

Interfejs Google Analytics Data API w wersji 1 używa podejścia asynchronicznego do tworzenia zadań raportowania. Po pierwsze, aby utworzyć zadanie raportowania, musisz wysłać żądanie do metody reportTasks.create. Następnie metoda reportTasks.query służy do pobrania wygenerowanego raportu niestandardowego.

Dodatkowo możesz użyć parametru reportTasks.get, aby pobrać metadane konfiguracji dotyczące konkretnego zadania raportowania, oraz parametru reportTasks.list, aby wyświetlić listę wszystkich zadań raportowania w usłudze.

Wybierz podmiot raportowania

Wszystkie metody interfejsu Data API w wersji 1 wymagają podania identyfikatora usługi w Google Analytics w ścieżce żądania w adresie URL w formie properties/GA_PROPERTY_ID, np.:

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

Raport jest generowany na podstawie danych zdarzeń Google Analytics zebranych w określonej usłudze w Google Analytics.

Jeśli używasz jednej z bibliotek klienta interfejsu Data API, nie musisz ręcznie manipulować ścieżką adresu URL żądania. Większość klientów interfejsu API udostępnia parametr property, który oczekuje ciągu znaków w formie properties/GA_PROPERTY_ID. Przykłady korzystania z bibliotek klienta znajdziesz w przewodniku dla początkujących.

Prośba o utworzenie zadania dotyczącego raportu

Aby utworzyć zadanie raportowania, wywołaj metodę reportTasks.create za pomocą obiektu ReportTask w prośbie. Wymagane są te parametry:

Przykład żądania utworzenia zadania związanego z raportowaniem:

Żądanie HTTP

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

Odpowiedź metody reportTasks.create zawiera nazwę zadania dotyczącego raportu w polu name (np. properties/1234567/reportTasks/123), która może być używana w kolejnych zapytaniach do uzyskiwania stanu zadania dotyczącego raportu i pobierania powstałego raportu.

Odpowiedź HTTP

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

Pobieranie stanu gotowości zadania związanego z raportowaniem

Wygenerowanie raportu po wywołaniu może potrwać kilka minut. reportTasks.create Stan gotowości zadania raportowania możesz uzyskać, wywołując metodę reportTasks.get.

Aby określić zadanie raportowania, użyj nazwy zadania raportowania (np. properties/1234567/reportTasks/123), która została podana w odpowiedzi na zapytanie reportTasks.create.

Przykład:

Żądanie HTTP

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

Stan gotowości zadania związanego z raportowaniem jest zwracany w polu state odpowiedzi. Po zakończeniu generowania raportu stan zadania związanego z raportami zmieni się z CREATING na ACTIVE.

Pole reportMetadata zawiera ogólne informacje o wygenerowanym raporcie, np. liczbę wierszy i wysokość wykorzystanych tokenów limitu.

Odpowiedź HTTP

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

Stan wszystkich zadań związanych z raportami możesz uzyskać, wywołując metodę reportTasks.list.

Pobieranie wygenerowanego raportu

Po wygenerowaniu zadania związanego z raportowaniem utworzonego za pomocą metody reportTasks.create wywołaj metodę reportTasks.query i wskaż nazwę zadania związanego z raportowaniem (np. properties/1234567/reportTasks/123).

Żądanie HTTP

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

Jeśli zadanie polegające na utworzeniu raportu jest gotowe, zwracana jest odpowiedź zawierająca wygenerowany raport:

Odpowiedź HTTP

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

...

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