Podstawowe informacje o zadaniach w raportach

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

Zasób zadania raportu wygenerowany na podstawie tego żądania może służyć do uzyskiwania dostępu do raportów niestandardowych przez wszystkich użytkowników, którzy mają uprawnienia do odczytu Twojej usługi w Google Analytics.

Raport niestandardowy będzie dostępny przez 72 godziny od momentu jego przygotowania. Po upływie tego okresu zasób zadania raportu i jego zawartość zostaną automatycznie usunięte.

Tworzenie zadania raportu

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

Możesz też użyć metody reportTasks.get, aby pobrać metadane konfiguracji dotyczące konkretnego zadania raportu, oraz metody reportTasks.list, aby wyświetlić listę wszystkich zadań raportu w usłudze.

Wybierz podmiot raportujący

Wszystkie metody interfejsu Data API w wersji 1 wymagają podania identyfikatora usługi w Google Analytics w ścieżce żądania adresu URL w formacie 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 formacie properties/GA_PROPERTY_ID. Przykłady użycia bibliotek klienta znajdziesz w krótkim przewodniku.

Poproś o utworzenie zadania raportu

Aby utworzyć zadanie raportu, wywołaj metodę reportTasks.create, używając obiektu ReportTask w żądaniu. Wymagane są te parametry:

Przykładowe żądanie utworzenia zadania raportu:

Żą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 raportu w polu name (np. properties/1234567/reportTasks/123), którą można wykorzystać w kolejnych zapytaniach, aby uzyskać stan zadania raportu i pobrać wynikowy raport.

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 raportu

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

Aby określić zadanie raportu, użyj nazwy zadania raportu (np. properties/1234567/reportTasks/123) otrzymanej w odpowiedzi reportTasks.create.

Przykład:

Żądanie HTTP

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

Stan gotowości zadania raportu jest zwracany w polu state odpowiedzi. Po zakończeniu generowania raportu stan zadania raportu zmienia się z CREATING na ACTIVE.

Pole reportMetadata zawiera ogólne informacje o wygenerowanym raporcie, takie jak liczba wierszy i liczba obciążonych 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ń raportu możesz uzyskać, wywołując metodę reportTasks.list.

Pobieranie wygenerowanego raportu

Po wygenerowaniu zadania raportu utworzonego za pomocą metody reportTasks.create wywołaj metodę reportTasks.query i podaj nazwę zadania raportu (np. properties/1234567/reportTasks/123).

Żądanie HTTP

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

Jeśli zadanie 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"
  }
}

Dalsze kroki