Wprowadzenie do Sophos Email Management API

Email Management API jest interfejsem automatyzacji wybranych zadań Sophos Email w obrębie tenanta. Ten artykuł wyjaśnia, jak zweryfikować kontrakt API i wybrać właściwą rodzinę operacji. Szczegółowe procedury zapisu, kwarantanny i clawback pozostają w odpowiednich runbookach; artykuł przeglądowy nie upoważnia do zmian.

Przejęcie wymagań wstępnych

Przed pierwszym żądaniem Email należy ukończyć wspólny proces API Sophos Fusion: uwierzytelnić service principal przez OAuth2, wskazać docelowego tenanta i odkryć jego regionalny host API. Bezpieczne zarządzanie poświadczeniami API Sophos Fusion (dawniej Sophos Central) opisuje ochronę poświadczeń, pobranie tokenu, whoami, wybór tenanta Partner i Enterprise oraz wspólną diagnostykę.

Ten artykuł wykorzystuje dokładnie trzy zweryfikowane wartości:

• SOPHOS_ACCESS_TOKEN: krótkotrwały token bearer OAuth2;
• SOPHOS_TENANT_ID: UUID docelowego tenanta;
• SOPHOS_API_HOST: pełny regionalny host tego tenanta.

Host globalny służy wyłącznie do ustalenia tożsamości i tenanta. Operacje Email należy wysyłać do zwróconego hosta regionalnego. Nie wolno wyznaczać regionu ani tenanta na podstawie nazwy wyświetlanej. Tokeny, client secret i pełne odpowiedzi nie mogą trafić do kodu, logów ani zgłoszeń.

Wybór rodziny operacji

Sophos Fusion przedstawia również Message History przez zapytania XDR oraz zarządzanie certyfikatami S/MIME jako API Email. Mają one oddzielne kontrakty i uprawnienia. Nie należy przenosić do nich ścieżek, schematów ani założeń z czterech powyższych rodzin.

Przekazanie Message History do XDR Query API

Dla Message History należy przejść do aktualnego omówienia XDR Query API. Jest to oddzielna regionalna usługa chroniona przez OAuth2, której ścieżka bazowa to /xdr-query/v1, a nie operacja w /email/v1. Uprawnienia i błędy XDR należy oceniać niezależnie od założeń dotyczących Email Management API.

Cykl działania musi być ograniczony: za pomocą udokumentowanych operacji kategorii i definicji zapytań znaleźć aktualną definicję zapytania, uruchomić wykonanie przez POST, sprawdzić jego stan, po zakończeniu pobrać wyniki i w razie potrzeby anulować wykonanie. Nie należy kopiować ani wymyślać zapytania Email na podstawie tego artykułu. Przed implementacją trzeba sprawdzić w podlinkowanym aktualnym opisie API właściwe schematy operacji i odpowiedzi dla uruchomienia, kontroli, wyników i anulowania.

Przed zbudowaniem zapytania należy otworzyć oficjalną przeglądarkę schematu Email Message History. W panelu Table name trzeba wybrać tabelę, a następnie sprawdzić General info, Fields i Custom Types. Orientacyjnie bieżący schemat Email udostępnia dokładnie trzy wykrywalne tabele: xdr_xge_att_data, xdr_xge_url_data i xdr_xge_events. Źródłem prawdy o polach i typach pozostaje przeglądarka online; artykuł celowo nie powiela listy pól. Te tabele Data Lake nie są schematami odpowiedzi /email/v1.

Przed implementacją trzeba wybrać dokładną operację w aktualnym opisie API i sprawdzić metodę HTTP, ścieżkę, schemat żądania i odpowiedzi, uprawnienie oraz udokumentowane limity. Nie wolno zgadywać składni endpointu ani tworzyć operacji przez podmianę rzeczownika.

Ścieżka prowadzi od uwierzytelniania i routingu tenanta do skrzynek, clawback, kwarantanny, kwarantanny post-delivery i S/MIME.

Zbudowanie kontraktu żądania

Sprawdzona specyfikacja używa regionalnego bazowego URL zakończonego /email/v1. Każde żądanie tenantowe wymaga tokenu bearer i X-Tenant-ID; wywołania JSON używają Content-Type: application/json. Do zweryfikowanego hosta należy dodać wyłącznie udokumentowaną ścieżkę produktu:

EMAIL_API_HOST="${SOPHOS_API_HOST%/}/email/v1"

Przed zapisem produkcyjnym należy wykonać nieszkodliwy test odczytu. GET /mailboxes jest operacją listowania w sprawdzonej specyfikacji. pageSize=1 ogranicza tylko pierwszą odpowiedź i nie dowodzi braku kolejnych stron:

RESPONSE_FILE=$(mktemp) || exit 1
trap 'rm -f "$RESPONSE_FILE"' EXIT
HTTP_STATUS=$(
  printf 'header = "Authorization: Bearer %s"\n' "$SOPHOS_ACCESS_TOKEN" |
  curl --silent --show-error --config - \
    --output "$RESPONSE_FILE" \
    --write-out '%{http_code}' \
    --request GET \
    --header "X-Tenant-ID: $SOPHOS_TENANT_ID" \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    "$EMAIL_API_HOST/mailboxes?pageSize=1"
)

if [[ "$HTTP_STATUS" != "200" ]]; then
  printf 'Email API returned HTTP %s\n' "$HTTP_STATUS" >&2
  exit 1
fi

if ! jq -e '(.items | type) == "array" and (.pages | type) == "object"' \
  "$RESPONSE_FILE" >/dev/null; then
  printf 'Email API response failed schema validation\n' >&2
  exit 1
fi
rm -f "$RESPONSE_FILE"
trap - EXIT

Test przechodzi przy statusie 200 i obecności struktur items oraz pages. Nie należy bez filtrowania zapisywać treści odpowiedzi: nawet lista skrzynek zawiera dane osobowe tenanta.

Stronicowanie, ograniczanie ruchu i czas życia tokenu

Poprawna pierwsza strona nie jest pełną inwentaryzacją. Dla GET /mailboxes pole pages.nextKey zawiera klucz następnej strony; w kolejnym żądaniu przekazuje się go po zakodowaniu URL jako pageFromKey. Klient działa do braku nextKey, ogranicza liczbę stron i czas oraz wykrywa powtarzające się klucze. Dla każdej innej operacji obowiązuje wyłącznie jej aktualnie udokumentowany model stronicowania.

Ograniczanie ruchu nie jest błędem schematu. Przy 429 należy respektować udokumentowane nagłówki retry lub rate limit, stosować ograniczony backoff z jitterem oraz limit prób i całkowitego czasu. Nie wolno automatycznie ponawiać zapisu, usunięcia, zwolnienia ani clawback: timeout może nastąpić już po przyjęciu operacji przez serwer.

Wygasły token odnawia się przez OAuth2. Błędu 401 nie obchodzi się zmianą tenanta lub regionu. Przy 403 sprawdza się rolę, uprawnienie i przypisanie; przy 404 regionalny host, udokumentowaną ścieżkę i ID. Pozostałe 4xx oznaczają błąd żądania lub stanu. Obsługa 5xx musi być ograniczona; przed kontrolowaną próbą trzeba ustalić stan i możliwy skutek po stronie serwera.

Weryfikacja wersji i wdrożenia produkcyjnego

Specyfikację stanowiącą podstawę artykułu sprawdzono w wersji v1.4.0. Przed implementacją należy ponownie zweryfikować bieżącą wersję. Ścieżki lub schematy z v1.4.0 nie są gwarancją dla wersji późniejszych.

Przed wdrożeniem należy zapisać:

1. właściciela poświadczeń, minimalną rolę, ID tenanta i odkryty host regionalny;
2. wybraną rodzinę oraz aktualną metodę, ścieżkę i schemat;
3. nieszkodliwy test GET ze statusem HTTP i wynikiem schematu, bez tokenu i pełnego payloadu;
4. zakończenie stronicowania, obsługę 429, odnowienie tokenu i maksymalny czas ponowień;
5. dla każdej zmiany idempotencję, zatwierdzenie, oczekiwany efekt, kontrolę i sposób zatrzymania.

Operację biznesową wdraża się dopiero po zaliczeniu tych kontroli w testowym tenancie lub na kontrolowanym rekordzie. Wspólne OAuth2 i routing tenanta pozostają wymaganiami, a nie funkcjami Sophos Email.