Refresh tokeny Amazon Ads: limit 365 dni i skuteczne monitorowanie ważności

Refresh tokeny Amazon Ads: limit 365 dni i skuteczne monitorowanie ważności

Od 30 lipca 2026 r. nowo wydane refresh tokeny dla uprawnień reklamowych Amazon Ads mają stały okres ważności: 365 dni od zgody reklamodawcy. Wymiana na nowe access tokeny nie rozpoczyna tego okresu od nowa. Lokalny rejestr umożliwia wcześniejsze ostrzeganie, a monitoring błędów wykrywa cofnięte lub unieważnione dane dostępowe także przed planowanym terminem.

Access token uwierzytelnia żądania API i zwykle jest ważny przez 60 minut. Refresh token pozwala uzyskać kolejne access tokeny bez ponawiania dialogu zgody przy każdej wymianie.

1. Zakres reguły 365 dni

Amazon stosuje regułę do tokenów wydanych od 30 lipca 2026 r. dla advertising::campaign_management i advertising::audiences. Wcześniejsze tokeny nie otrzymują wskutek tej zmiany stałej daty wygaśnięcia, ale nadal mogą zostać cofnięte lub unieważnione z innych powodów. Decyduje wydanie tokena, a nie sam dzień podłączenia konta reklamowego do integracji.

Stały okres zaczyna się od zgody. Wymiana refresh tokena zwraca nowy access token oraz ten sam refresh token; nowa zgoda jest osobną operacją. Dostawcy OAuth stosują różne zasady, więc przesuwanie ważności nie jest ogólną cechą refresh tokenów. Reguł Amazon Ads nie należy też utożsamiać z zasadami autoryzacji Selling Partner API.

Aktualny przewodnik Amazon Ads zaleca monitorowanie wieku tokenów i ponowną autoryzację z wyprzedzeniem. Przewodnik nie potwierdza ogólnego twierdzenia, że Amazon nigdy nie wysyła e-maili, ostrzeżeń w konsoli ani innych przypomnień. Monitoring operacyjny powinien działać niezależnie od założonego powiadomienia dostawcy.

2. Rejestr autoryzacji zamiast wartości tokenów

Przykład PostgreSQL przechowuje jeden wiersz na niezależnie zarządzaną autoryzację. authorization_id jest wewnętrznym stałym identyfikatorem, a client_id oznacza aplikację. Kilka aplikacji lub niezależnych autoryzacji tego samego reklamodawcy wymaga osobnych wierszy. Sama nazwa konta nie identyfikuje jednoznacznie autoryzacji. Właściwe refresh tokeny i client secrets należą do chronionego magazynu sekretów, poza tą tabelą i treścią alertów.

Pole policy rozróżnia fixed_365, legacy i unknown. Wiersze legacy nie otrzymują wyliczonego terminu. Brak dowodów oznacza unknown i powoduje ostrzeżenie, zamiast tworzyć fikcyjną datę zgody. Dla fixed_365 pole consent_date zawiera kalendarzową datę UTC zarejestrowanej zgody, a token_issued_at rzeczywisty czas wydania. Klasyfikacja w pobliżu daty granicznej wymaga wiarygodnego dziennika autoryzacji.

CREATE TABLE amazon_ads_token_ledger (
    authorization_id text PRIMARY KEY,
    client_id        text NOT NULL,
    account_name     text NOT NULL,
    policy           text NOT NULL
                     CHECK (policy IN ('fixed_365', 'legacy', 'unknown')),
    consent_date     date,
    token_issued_at  timestamptz,
    expires_on       date GENERATED ALWAYS AS (
        CASE WHEN policy = 'fixed_365' THEN consent_date + 365 END
    ) STORED,
    last_refresh_ok  timestamptz,
    owner_email      text NOT NULL,
    status           text NOT NULL DEFAULT 'active'
                     CHECK (status IN ('active', 'revoked')),
    CHECK (policy <> 'fixed_365' OR
           (consent_date IS NOT NULL AND token_issued_at IS NOT NULL)),
    CHECK (policy <> 'fixed_365' OR
           (token_issued_at AT TIME ZONE 'UTC')::date >= DATE '2026-07-30'),
    CHECK (policy <> 'legacy' OR
           (token_issued_at IS NOT NULL AND
            (token_issued_at AT TIME ZONE 'UTC')::date < DATE '2026-07-30'))
);

CREATE INDEX ON amazon_ads_token_ledger (expires_on)
WHERE status = 'active';

expires_on jest zachowawczym terminem planowania: data zgody plus 365 dni. Sama data nie określa dokładnej sekundy wygaśnięcia na serwerach Amazona. Skrypt traktuje początek tego dnia UTC jako krytyczną granicę planowania, dlatego odnowienie powinno nastąpić wcześniej. Kolumna generowana zapewnia zgodność obliczenia z zapisanymi danymi; błędne daty wejściowe nadal dają błędne terminy.

3. Skrypt z jednoznacznymi stanami błędu

Przykład dla Python 3 wymaga Psycopg 3. Rola bazy potrzebuje wyłącznie SELECT dla rejestru. Parametry połączenia pochodzą z ADS_LEDGER_DSN; dane dostępowe mogą korzystać z chronionego pliku haseł PostgreSQL lub odpowiedniej konfiguracji usługi. Przykład ogranicza czas połączenia i zapytania oraz nie wypisuje DSN ani wartości tokenów przy błędach.

#!/usr/bin/env python3
import os
import sys
import psycopg

WARN_DAYS = 60
QUERY = """
SELECT authorization_id, account_name, policy, expires_on,
       expires_on - CURRENT_DATE AS days_left, owner_email
FROM amazon_ads_token_ledger
WHERE status = 'active'
  AND (policy = 'unknown' OR expires_on <= CURRENT_DATE + %s)
ORDER BY expires_on NULLS FIRST, authorization_id
"""

def render(rows):
    result = 0
    for aid, name, policy, expires, days, owner in rows:
        if policy == 'unknown':
            state = 'UNKNOWN: authorization metadata needs review'
            result = 2
        elif days <= 0:
            state = 'DUE: planning deadline reached; check authorization'
            result = max(result, 1)
        else:
            state = f'WARNING: {days} days to planning deadline'
        print(f'{aid} | {name} | {state} | deadline={expires} | owner={owner}')
    return result

def main():
    dsn = os.environ.get('ADS_LEDGER_DSN')
    if not dsn:
        print('CHECK FAILED: ADS_LEDGER_DSN is missing', file=sys.stderr)
        return 2
    try:
        with psycopg.connect(dsn, connect_timeout=5,
                options='-c timezone=UTC -c statement_timeout=5000') as conn:
            rows = conn.execute(QUERY, (WARN_DAYS,)).fetchall()
    except psycopg.Error as exc:
        # No DSN, credentials or token contents in diagnostic output.
        print(f'CHECK FAILED: {type(exc).__name__}', file=sys.stderr)
        return 2
    return render(rows)

if __name__ == '__main__':
    sys.exit(main())

Kod zakończenia 0 oznacza brak stanu krytycznego; wcześniejsze ostrzeżenia nadal generują tekst. Kod 1 sygnalizuje osiągnięcie terminu planowania. Kod 2 oznacza nieznane dane autoryzacji albo nieudaną kontrolę. Warstwa monitoringu musi faktycznie odbierać te kody. Próg 60 dni jest regulowanym buforem organizacyjnym, a nie wymogiem Amazona ani uniwersalnym zmierzonym czasem akceptacji.

4. Harmonogram i dostarczenie powiadomień

# Service-user crontab; working local mail transport required.
MAILTO=ads-ops@example.com
ADS_LEDGER_DSN="dbname=ops user=ads_ledger_reader"
17 6 * * * /opt/ads/venv/bin/python /opt/ads/token_ledger_check.py

Ścieżki i rola bazy są przykładami wdrożenia. Prywatne środowisko Pythona musi zawierać Psycopg, a lokalne uwierzytelnianie pozwalać na użycie roli tylko do odczytu. Cron uruchamia zadanie o 06:17 w skonfigurowanej strefie harmonogramu; obliczenia dat w SQL używają jawnie UTC. MAILTO wymaga działającego lokalnego transportu poczty i sprawdzonego odbiorcy. Sam skrypt nie wysyła e-maili, a owner_email opisuje odpowiedzialność i nie jest automatycznym adresem dostarczenia.

Utrzymujący się stan może powodować codzienne przypomnienie. Eskalacja, potwierdzenie odbioru i ograniczanie liczby wiadomości należą do otaczającego monitoringu. Potrzebny jest niezależny sygnał działania albo kontrola pominiętych uruchomień, ponieważ zatrzymany harmonogram nie zgłosi własnej awarii. Pole last_refresh_ok pomaga tylko wtedy, gdy proces odświeżania aktualizuje wartość, a osobna kontrola sprawdza aktualność.

5. Odnowienie i obsługa błędów

Według Amazona nieważny refresh token powoduje HTTP 400 z invalid_grant. Zadanie raportowe powinno zgłosić błąd, zamiast zastępować prawidłowe raporty pustymi danymi. Błędy sieci mogą uzasadniać ograniczone ponowienia; powtarzanie żądania nie naprawia nieważnego grantu. Odzyskanie dostępu wymaga nowego authorization grant przez procedurę zgody. Udane odnowienie obejmuje spójną aktualizację sekretu i rejestru, a następnie rzeczywistą wymianę na access token oraz minimalne dozwolone sprawdzenie API.