Blog

Projekt w Google Cloud i aktywacja API

Proces konfiguracji rozpoczyna się od projektu w konsoli Google Cloud. Projekt pełni rolę kontenera dla wszystkich ustawień i usług związanych z API. Jeśli w koncie Google Cloud istnieje już projekt, można z niego skorzystać. Warto jednak upewnić się, że w górnym pasku nawigacyjnym wybrany jest właściwy projekt — w przeciwnym razie konfiguracja zostanie zapisana w niewłaściwym miejscu.

Po przygotowaniu projektu konieczne jest włączenie usługi Google Analytics Data API. Aby to zrobić, należy otworzyć menu nawigacyjne w lewym górnym rogu konsoli Google Cloud, a następnie przejść do sekcji Interfejsy API i usługi → Biblioteka. Wyszukanie interfejsu i kliknięcie przycisku Enable aktywuje usługę. Jeśli ten krok zostanie pominięty, każda próba wywołania API zakończy się błędem, dlatego aktywacja jest absolutnie niezbędna.

Konto serwisowe i dane uwierzytelniające

Kolejnym elementem konfiguracji jest konto serwisowe. To specjalny typ użytkownika technicznego, który działa w imieniu aplikacji i umożliwia komunikację z API bez konieczności logowania się zwykłym kontem Google. Aby je utworzyć, należy w konsoli Google Cloud otworzyć menu w lewym górnym rogu (hamburger menu), przejść do sekcji Administracja → Konta usługi i dodać nowe konto. Podczas konfiguracji trzeba nadać mu unikalny identyfikator, np. ga4-api-client.

Po utworzeniu konta serwisowego warto przejść do zakładki Uprawnienia i dodać rolę Właściciel. Dzięki temu konto będzie miało pełny dostęp do niezbędnych zasobów w ramach projektu, co zapobiega problemom z brakiem autoryzacji podczas korzystania z API.

Po utworzeniu konta serwisowego trzeba wygenerować dla niego klucz w formacie JSON. W tym celu należy w konsoli Google Cloud przejść do sekcji Administracja → Konta usługi, a następnie kliknąć adres e-mail konta, dla którego chcemy utworzyć klucz. Po otwarciu szczegółów konta dostępna jest zakładka Klucze. W niej wybiera się opcję Dodaj klucz → Utwórz nowy klucz, a następnie jako format należy wskazać JSON.

Na dysk zostanie pobrany plik zawierający dane uwierzytelniające potrzebne do komunikacji z API. Plik pełni funkcję hasła technicznego i musi być przechowywany w bezpiecznym miejscu – nie wolno go publikować ani umieszczać w repozytoriach kodu. W przypadku utraty lub wycieku klucza można go unieważnić w konsoli Google Cloud i wygenerować nowy.

Nadanie dostępu w GA4

Samo konto serwisowe nie ma jeszcze dostępu do danych Google Analytics, dopóki nie zostanie dodane jako użytkownik w GA4. W tym celu należy zalogować się do analytics.google.com, a następnie w lewym dolnym rogu kliknąć ikonę zębatki, która otwiera sekcję Administracja. W panelu administracyjnym trzeba przejść do Ustawienia konta → Konto → Zarządzanie dostępem do konta.

W tym miejscu można dodać nowego użytkownika, podając adres e-mail konta serwisowego (generowany automatycznie w formacie nazwa-konta@project-id.iam.gserviceaccount.com). Należy upewnić się, że w danym projekcie Google Analytics posiadamy odpowiednie uprawnienia administracyjne — w przeciwnym razie dodanie użytkownika będzie niemożliwe.

Podczas dodawania konta serwisowego można nadać mu różne role. W moim przypadku przypisałem rolę Administratora, ponieważ jest to najszybsze i najprostsze rozwiązanie gwarantujące pełny dostęp. W praktyce jednak do poprawnego działania API wystarczy rola Viewer, która umożliwia sam odczyt danych. Warto mieć to na uwadze, ponieważ nadanie zbyt szerokich uprawnień nie jest konieczne. Jeśli konto serwisowe nie zostanie w ogóle dodane do GA4 lub dostanie niewłaściwe uprawnienia, każda próba wywołania API zakończy się błędem 403: insufficient permissions

Właściwy identyfikator usługi

Google udostępnia w GA4 kilka różnych identyfikatorów, ale w przypadku korzystania z Reporting API interesuje nas Property ID. Ten numer można znaleźć w panelu analytics.google.com – po kliknięciu ikony zębatki w lewym dolnym rogu, czyli w sekcji Administracja. Następnie należy przejść do Ustawienia usługi → Usługa → Szczegóły usługi. W tym miejscu wyświetla się pole Identyfikator usługi (Property ID).

To właśnie ten identyfikator wykorzystujemy w zapytaniach do API. Użycie innego, np. Measurement ID w formacie G-XXXXXXX, spowoduje błędy lub puste wyniki.

Przykładowe zapytanie w Pythonie

Do weryfikacji połączenia można wykorzystać oficjalny przykład z dokumentacji Google. Kod korzysta z biblioteki google-analytics-data, a uwierzytelnianie odbywa się poprzez zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS, która musi wskazywać na plik .json pobrany wcześniej przy generowaniu klucza konta serwisowego.

import os
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    DateRange,
    Dimension,
    Metric,
    RunReportRequest,
)

# Ścieżka do pliku JSON z kluczem konta serwisowego
os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = 'google-key-file.json'

def sample_run_report(property_id="YOUR-GA4-PROPERTY-ID"):
    """Uruchamia proste zapytanie na właściwości GA4."""
    client = BetaAnalyticsDataClient()

    request = RunReportRequest(
        property=f"properties/{property_id}",
        dimensions=[Dimension(name="city")],
        metrics=[Metric(name="activeUsers")],
        date_ranges=[DateRange(start_date="2020-03-31", end_date="today")],
    )

    response = client.run_report(request)

    print("Report result:")
    for row in response.rows:
        print(row.dimension_values[0].value, row.metric_values[0].value)