Tutorial: Zapytanie do GA4 Analytics Advisor przez API i weryfikacja odpowiedzi w runReport

Przydatny asystent analityczny potrzebuje odpowiedzi, które można sprawdzić. Ten tutorial pyta Analytics Advisor o sesje według kanałów, dodaje okres porównawczy i kontroluje liczby przez jednoznaczne zapytanie Data API. Wynikiem jest mała analiza z zapisanymi wejściami i wynikami, a nie bezkrytycznie przyjęte wyjaśnienie.

Dokumentacja sprawdzona: 25 września 2026 r. Metoda chat należy do wczesnej wersji v1alpha. Dostępność i uprawnienia wymagają sprawdzenia dla konkretnej usługi GA4. 27 września 2026 r. trzy udokumentowane zapytania API wykonano z wiersza poleceń dla autoryzowanej usługi GA4. Strukturalna tabela dla okresu 1–7 września była dokładnie zgodna ze wszystkimi czterema wierszami grup kanałów z runReport; wartości usługi nie są tutaj publikowane. [1]

1. Zdefiniowanie ograniczonego pytania

Przykład porównuje 1–7 września 2026 r. z 25–31 sierpnia 2026 r. Oba okresy mają siedem dni i taki sam układ dni tygodnia. Metryka to sessions, a grupowanie to sessionDefaultChannelGroup. Nazwy pochodzą ze schematu API. [4] Konkretne daty eliminują zmienny sens określenia „ostatni tydzień”.

Kanał to grupa atrybucyjna, nie osoba ani budżet kampanii. Pierwsze pytanie celowo dotyczy liczby, a nie przyczyny. Niższy wynik może uzasadniać analizę, ale sam nie dowodzi wpływu określonego działania marketingowego.

2. Autoryzacja i zapis pierwszej odpowiedzi

Przykład działa w Bash z zainstalowanymi gcloud, curl i jq. Projekt Cloud wymaga włączonego Analytics Data API. Zalogowane konto potrzebuje dostępu do usługi GA4 i uprawnienia do korzystania z projektu rozliczającego limity. Identyfikator projektu Cloud i numeryczny identyfikator usługi Analytics to różne wartości.

Chat wymaga analytics.chatbot.read, a późniejsza kontrola raportu analytics.readonly. Przykład prosi o oba zakresy. Dane uwierzytelniające pozostają w lokalnym procesie logowania gcloud; nie należą do kodu artykułu ani publicznej strony. [1][3]

Aktualne wersje Cloud CLI mogą blokować te zakresy Analytics dla wbudowanego klienta OAuth. W docelowym projekcie Cloud należy utworzyć klienta OAuth typu aplikacja komputerowa, pobrać plik JSON i przekazać go przez --client-id-file. Google dokumentuje ten parametr dla zakresów spoza domyślnego zestawu Cloud. [6]

# Bash; gcloud, curl and jq required
set -euo pipefail
export PROJECT_ID='REPLACE_WITH_CLOUD_PROJECT'
export PROPERTY_ID='REPLACE_WITH_NUMERIC_PROPERTY_ID'
export OAUTH_CLIENT_FILE='REPLACE_WITH_DOWNLOADED_DESKTOP_CLIENT_JSON'
gcloud auth application-default login --client-id-file="$OAUTH_CLIENT_FILE" --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read,https://www.googleapis.com/auth/analytics.readonly"
gcloud auth application-default set-quota-project "$PROJECT_ID"

cat > question.json <<'JSON'
{
  "userQuery": "For 2026-09-01 through 2026-09-07, report sessions by sessionDefaultChannelGroup. Use these exact dates and API field names. State any limitation and do not infer causes.",
  "returnPropertyQuota": true
}
JSON
curl --fail-with-body --silent --show-error \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  --data-binary @question.json -o answer.json
jq '{sessionId, blocks, propertyQuota}' answer.json

Poprawna odpowiedź może zawierać bloki tekstu i tabel. Zapis całej odpowiedzi zachowuje kontekst. Brak tabeli nie oznacza tabeli z zerami. Symboli walut, procentów i sformatowanych wartości nie należy bez wyjaśnienia zamieniać w same liczby. Struktura odpowiedzi i pola sesji mają osobną dokumentację. [2]

3. Kolejne pytanie w zwróconej sesji

Następne polecenie odczytuje identyfikator sesji z odpowiedzi; jego brak zatrzymuje skrypt. Potem następuje pytanie o wcześniejszy okres. Przy kolejnych krokach źródłem identyfikatora jest najnowsza odpowiedź. Różne usługi, klienci i konteksty uprawnień wymagają oddzielnego przechowywania sesji.

SESSION_ID=$(jq -er '.sessionId | strings | select(length > 0)' answer.json)
jq -n --arg sid "$SESSION_ID" '{
  sessionId: $sid,
  userQuery: "Compare those sessions by sessionDefaultChannelGroup with 2026-08-25 through 2026-08-31. Show both totals and absolute differences. Separate observations from hypotheses.",
  returnPropertyQuota: true
}' > followup.json
curl --fail-with-body --silent --show-error \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  --data-binary @followup.json -o followup-answer.json
jq '{sessionId, blocks, propertyQuota}' followup-answer.json

Kontekst sesji łączy pytania, ale nie zastępuje jednoznacznych dat i definicji. „Organic Search spadł” opisuje wynik. „Nowa strona docelowa spowodowała spadek” wymaga dodatkowych dowodów. Zachowanie obu pytań pozwala sprawdzić tę różnicę.

4. Odtworzenie liczby przez runReport

Drugie zapytanie API pobiera bezpośrednio oba okresy, ten sam wymiar i tę samą metrykę. Powstaje niezależny raport zamiast prośby, aby asystent potwierdził własną odpowiedź. API raportowe opisuje zakresy dat, nagłówki, liczbę wierszy i metadane. [3]

cat > report-request.json <<'JSON'
{
  "dateRanges": [
    {"startDate":"2026-09-01","endDate":"2026-09-07","name":"current"},
    {"startDate":"2026-08-25","endDate":"2026-08-31","name":"previous"}
  ],
  "dimensions": [{"name":"sessionDefaultChannelGroup"}],
  "metrics": [{"name":"sessions"}],
  "limit": "1000",
  "returnPropertyQuota": true
}
JSON
curl --fail-with-body --silent --show-error \
  "https://analyticsdata.googleapis.com/v1beta/properties/${PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  --data-binary @report-request.json -o report-response.json
jq '{dimensionHeaders,metricHeaders,rows,rowCount,metadata,propertyQuota}' report-response.json

Kolejność nagłówków określa interpretację wartości w wierszach. Przy wielu zakresach dodatkowy wymiar okresu rozróżnia przedziały. Porównanie wyłącznie według pozycji wiersza jest niewłaściwe: kanały mogą mieć inną kolejność lub nie występować. Różnica dla kanału to wartość bieżąca minus poprzednia. Zmiana procentowa wymaga poprzedniej wartości różnej od zera; brak wiersza nie jest zmierzoną wartością zerową.

5. Kontrola ograniczeń przed wykorzystaniem wyniku

Inspektor odpowiedzi GA4 API przyjmuje zapisany report-response.json do kontroli metadanych i limitów. Nie obsługuje odpowiedzi chat. Wynik asystenta jest porównywany z raportem oddzielnie. Informacje o progach, próbkowaniu lub niepełnej paginacji muszą pozostać widoczne w analizie.

returnPropertyQuota prosi o stan limitów chat, ale nie rezerwuje pojemności. Brak obiektu limitów oznacza niewiadomą, a nie brak ograniczeń. Błędy logowania, uprawnień i limitów wymagają zanotowania przed ponowieniem. Automatyczne powtarzanie pytań może zużywać dodatkowy limit i przynosić inne odpowiedzi. [1]

6. Zapis wyniku możliwego do sprawdzenia

Dokumentacja analizy obejmuje dwa pytania, dwie odpowiedzi chat, żądanie raportu, odpowiedź raportową i czas pobrania. Dostęp powinien odpowiadać poufności danych usługi. Informacja Google o prywatności wskazuje możliwość przetwarzania rozmów przez ludzi w celu ulepszania produktu. Nazwy klientów i poufne plany kampanii nie powinny trafiać do pytania dotyczącego samych liczb. [5]

Końcowym wynikiem jest udokumentowana liczba z wyjaśnieniem rozbieżności. Wynik może też brzmieć „nie udało się odtworzyć”. Obie możliwości są bardziej użyteczne niż niepoparta dowodami rekomendacja zmiany budżetu reklamowego.