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

Ile sesji pochodziło z wyszukiwarki, płatnych reklam lub innych kanałów? Przykład kieruje to pytanie do Analytics Advisor, a następnie dodaje drugi tydzień do porównania. Osobne zapytanie runReport sprawdza liczby bezpośrednio w raporcie GA4. Pytania i odpowiedzi pozostają zapisane w plikach.

Dokumentacja sprawdzona: 25 października 2026 r. Aktualny przewodnik Google używa nazwy Ask Advisor. Dostęp przez API zapewnia properties.chat w wersji v1alpha. Potrzebne są dostęp i uprawnienia do wybranej usługi GA4. [1] Zachowany protokół z 27 września 2026 r. dokumentuje trzy rzeczywiste zapytania: wszystkie cztery grupy kanałów z okresu 1–7 września były zgodne między tabelą czatu a runReport. To pojedynczy wcześniejszy test, bez gwarancji poprawności kolejnych odpowiedzi. Poufne wyniki pomiarów pozostają nieopublikowane.

1. Zdefiniowanie ograniczonego pytania

Przykład porównuje 1–7 września 2026 r. z 25–31 sierpnia 2026 r. Oba tygodnie zaczynają się we wtorek i kończą w poniedziałek. Pierwszy i ostatni dzień wchodzą do wyniku. Obowiązuje strefa czasowa raportowania usługi GA4. sessions oznacza liczbę sesji, a sessionDefaultChannelGroup dzieli tę liczbę według standardowych grup kanałów przypisanych do sesji. API wymaga dokładnie takich nazw pól. [4] [7]

Kanał łączy źródła ruchu, na przykład bezpłatne wyniki wyszukiwania w grupie Organic Search. Sesje oznaczają wizyty zgodnie z regułami GA4, a nie liczbę różnych osób. Mniejsza liczba sesji pokazuje spadek w tym raporcie. Sama liczba nie rozstrzyga, czy przyczyną była nowa strona docelowa albo zmiana kampanii.

2. Autoryzacja i zapis pierwszej odpowiedzi

Trzy bloki kodu działają kolejno w tej samej sesji Bash. Potrzebne są gcloud do logowania, curl do żądań HTTP i jq do odczytu oraz tworzenia plików JSON. Nowy prywatny katalog roboczy zapobiega nadpisaniu plików z wcześniejszej próby. W pierwszym bloku trzeba zastąpić symbole zastępcze identyfikatorem projektu, numerycznym identyfikatorem usługi i ścieżką pliku klienta. Projekt Cloud zapewnia dostęp do API; identyfikator usługi wybiera dane GA4. Projekt wymaga włączonego Analytics Data API. Zalogowane konto potrzebuje dostępu do usługi oraz uprawnienia serviceusage.services.use w projekcie przypisanym do wykorzystania API.

Uprawnienia OAuth określają dozwolone funkcje API. Czat wymaga analytics.chatbot.read, a późniejszy raport analytics.readonly. Przykład prosi o oba zakresy. gcloud zapisuje dane logowania lokalnie; nowe logowanie może zastąpić wcześniejsze Application Default Credentials. Dane logowania i tokeny dostępu nie mogą trafić na publiczną stronę. [1][3][6]

Przykład korzysta z osobnego klienta OAuth typu aplikacja komputerowa. Pobrany plik JSON jest przekazywany przez --client-id-file. Google opisuje ten sposób dla uprawnień spoza standardowego zestawu Cloud. [6] Przed każdym żądaniem HTTP skrypt pobiera token dostępu. Nieudane pobranie lub pusty token zatrzymuje skrypt przed wysłaniem żądania. Błąd HTTP także kończy wykonanie. Przykład nie ponawia żądań automatycznie.

# 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
ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
[[ -n "$ACCESS_TOKEN" ]] || { echo "Empty access token" >&2; exit 1; }
curl --fail-with-body --silent --show-error \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer ${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

Odpowiedź może zawierać tekst i tabele. answer.json zapisuje całą odpowiedź, a jq wyświetla wybrane pola. Brak tabeli nie dowodzi wartości zerowych. Komórki mogą zawierać na przykład symbole walut lub procentów. Przed porównaniem liczb potrzebne są jednostka i znaczenie każdej kolumny. [2]

3. Kolejne pytanie w zwróconej sesji

Pole sessionId łączy kolejne pytanie z dotychczasową rozmową. Ten identyfikator rozmowy nie jest powiązany z metryką sessions. Brak niepustego identyfikatora zatrzymuje następny blok. Dalsze pytania wymagają identyfikatora z najnowszej odpowiedzi. Rozmowy dotyczące różnych usług GA4 lub klientów muszą pozostać rozdzielone.

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
ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
[[ -n "$ACCESS_TOKEN" ]] || { echo "Empty access token" >&2; exit 1; }
curl --fail-with-body --silent --show-error \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer ${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

Kolejne pytanie podaje wcześniejszy okres wprost. „Organic Search spadł” opisuje obserwację. „Nowa strona docelowa spowodowała spadek” pozostaje hipotezą bez dodatkowych dowodów. Zapisane pytania pokazują później, czego dotyczyło zapytanie.

4. Odtworzenie liczby przez runReport

Po dwóch zapytaniach do czatu następuje trzecie: runReport pobiera tę samą metrykę według tych samych kanałów dla obu tygodni. Porównanie korzysta z raportu o jawnie określonych parametrach. Oba wyniki nadal pochodzą z GA4. Zgodność nie dowodzi ani kompletnego zbierania danych, ani przyczyny zmiany. [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
ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
[[ -n "$ACCESS_TOKEN" ]] || { echo "Empty access token" >&2; exit 1; }
curl --fail-with-body --silent --show-error \
  "https://analyticsdata.googleapis.com/v1beta/properties/${PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${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

Nazwy kolumn znajdują się w dimensionHeaders i metricHeaders. Wartości w wierszach zachowują tę kolejność. Dodatkowa kolumna dateRange zawiera tutaj current albo previous. Porównanie wymaga więc pary kanał–okres, a nie pozycji wiersza. Przykład: 100 sesji zamiast 80 oznacza 20 dodatkowych sesji i wzrost o 25 procent. Przy wcześniejszej wartości zerowej takie obliczenie procentowe nie jest zdefiniowane. Brakującego wiersza nie należy bez dodatkowego sprawdzenia traktować jako zmierzonego zera.

5. Kontrola ograniczeń przed wykorzystaniem wyniku

Inspektor odpowiedzi GA4 API jest dodatkowym narzędziem do zapisanych odpowiedzi raportowych. Porównanie liczb z czatu pozostaje osobnym krokiem. W pliku report-response.json wymagają sprawdzenia również informacje metadata: progi mogą ukrywać małe grupy, a próbkowanie może opierać obliczenia tylko na części zdarzeń. Jeśli rowCount przekracza liczbę otrzymanych wierszy, brakuje dalszych wyników. Przykład pobiera najwyżej 1000 wierszy i nie pobiera kolejnych stron automatycznie. [8]

returnPropertyQuota prosi o informacje o limitach korzystania z API. Ustawienie nie rezerwuje kolejnych wywołań. Brak danych o limitach pozostawia dostępny zapas nieznany. Przed ponowieniem potrzebne jest ustalenie przyczyny: błąd logowania, brak uprawnienia albo przekroczony limit. Kolejne zapytania do czatu mogą zużywać dalszy limit i zwracać inne odpowiedzi. [1]

6. Zapis wyniku możliwego do sprawdzenia

Protokół obejmuje dwa pytania, dwie odpowiedzi czatu, żądanie raportu, odpowiedź raportową i czas pobrania. Dostęp do plików powinny mieć wyłącznie uprawnione osoby. 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 są potrzebne do opisanego pytania o liczby. [5]

Wynik zapisuje dla każdego kanału, czy liczba z czatu jest zgodna z raportem. Przy rozbieżności pozostają obie wartości i nierozstrzygnięte pytania. „Nie udało się odtworzyć” także jest użytecznym wynikiem kontroli. Samo porównanie tygodni nie uzasadnia rekomendacji zmiany budżetu reklamowego.