Automatyzacja skrzynek Sophos Email przez API

Sophos Email Management API obsługuje cały cykl życia skrzynki: przeszukiwanie inwentarza, tworzenie pojedyncze i zbiorcze, zmianę nazw i relacji oraz usuwanie. Bezpieczna kolejność to zawsze odczyt, porównanie stanu oczekiwanego z faktycznym, celowana zmiana i ponowny odczyt. Sam poprawny status HTTP nie wystarcza dla operacji zbiorczych i relacji.

Potwierdzenie wymagań i własności

Artykuł zakłada znajomość wprowadzenia do Sophos Email Management API. Uwierzytelnianie, ważność tokenu, rozpoznanie tenantu i host regionalny opisano w Uwierzytelnianie Sophos Email API i routing do tenantu. Wszystkie ścieżki wymagają regionalnego URL ${SOPHOS_API_HOST%/}/email/v1, Authorization: Bearer <access-token>, X-Tenant-ID: <tenant-uuid>, dla JSON Content-Type: application/json, oraz UUID w miejscu {id}. Zweryfikowane schematy pochodzą z Email Management API v1.4.0; zawsze sprawdź bieżący kontrakt.

Przed zapisem ustal system będący właścicielem inwentarza. Synchronizacja katalogu pozostaje źródłem nadrzędnym dla obiektów synchronizowanych. API nie przejmuje tej roli; zmiana może zostać nadpisana lub odrzucona. Specyfikacja dokumentuje 409 przy zmianie nazwy, pojedynczym usunięciu oraz zmianie aliasów lub delegatów skrzynki synchronizowanej. Zmień wtedy katalog źródłowy, zamiast wymuszać warianty lub ponowienia API.

Inwentaryzacja i wyszukiwanie wszystkich skrzynek

GET /mailboxes zwraca items i pages z polami fromKey, nextKey, size, maxSize. pageSize obsługuje maksymalnie 50 rekordów. Zakoduj URL-owo pages.nextKey jako kolejne pageFromKey; brak nextKey oznacza koniec. Ogranicz powtarzające się klucze, liczbę stron i łączny czas.

W jednym żądaniu wolno użyć tylko jednego parametru wyszukiwania: name, nameStartsWith, email, emailStartsWith, createdAfter, createdBefore, type, bulkSenderPrivilegeStatus, blocked, distributionListOwnedBy, alias, aliasesStartWith lub delegate. Typy to user, distributionList, publicFolder, sharedMailbox; statusy to neverRequested, approvalPending, approved, rejected, revoked. Nie łącz filtrów dokładnych z prefiksowymi.

Zachowaj co najmniej id, type, email, name, createdAt, blocked. Mogą wystąpić także aliases, delegates, distributionListOwners, bulkSenderPrivilege, policies. Nie zapisuj pełnych danych osobowych w logach.

Tworzenie, odczyt i zmiana nazw

Przy tworzeniu email ma format e-mail i 4–320 znaków, a name 1–256; type przyjmuje jeden z czterech typów. Pojedyncze tworzenie zwraca 201; 409 oznacza, że skrzynka lub alias używa już adresu. Znajdź istniejący obiekt i wyjaśnij własność, zamiast zmieniać adres obejściowo.

Operacja zbiorcza zwraca 201 również przy częściowym sukcesie. Uzgodnij items i errors z każdym żądanym adresem, zachowaj poprawne UUID i napraw tylko elementy nieudane. Następnie sprawdź każdy obiekt przez GET /mailboxes/{id} pod kątem type, email, name. Po zmianie nazwy odpowiedź 201 musi być potwierdzona GET-em z oczekiwanym name.

Zmiana aliasów, delegatów i właścicieli list

Relacje używają tablic JSON add i remove, także razem. Najpierw wykonaj odczyt, aby nie wysyłać pustej lub już spełnionej różnicy.

Ostatnia operacja dotyczy typu distributionList. 200 może oznaczać częściowy sukces. Oceń added, removed, errors.failedToAdd, errors.failedToRemove, a potem sprawdź dokładną zmianę przez GET w aliases, delegates lub distributionListOwners. Ponawiaj tylko nieudane wartości po usunięciu przyczyny, nigdy całe żądanie w ciemno. Typowe błędy to zajęty lub nieistniejący alias oraz delegat bez skrzynki. 400 oznacza żądanie/schemat, 404 ID/kontekst tenantu, a udokumentowane 409 własność synchronizacji.

Wniosek o uprawnienie nadawcy masowego

POST /mailboxes/{id}/bulksender-privilege-request wymaga całkowitego count, period równego daily, weekly lub monthly oraz purpose o długości 2–2048 znaków. Opisz rzeczywisty przypadek. Kontrakt nie określa górnej granicy count, więc jej nie wymyślaj. Odpowiedź 200 zawiera accepted; accepted: true potwierdza przyjęcie wniosku, nie zgodę. Śledź bulkSenderPrivilege.bulkSenderPrivilegeStatus przez GET i ponawiaj wniosek dopiero po sprawdzeniu statusu i przyczyny biznesowej.

Usuwanie bez ślepych ponowień

Pojedyncze usunięcie to DELETE /mailboxes/{id}. Odpowiedź 200 zawiera deleted; ta sama klasa jest dokumentowana także, gdy nie znaleziono skrzynki. Sprawdź wartość logiczną i stan po operacji.

POST /mailboxes/delete usuwa do 20 UUID w wymaganym items; odpowiedź 200 rozdziela udane items i errors według id. Przed usunięciem wyeksportuj UUID z adresem i porównaj ze świeżym inwentarzem. Obiekty synchronizowane usuwaj u źródła.

Nigdy nie ponawiaj w ciemno: po timeout lub nieoczekiwanym błędzie część albo wszystkie skrzynki mogły już zniknąć. Sprawdź każdy UUID przez GET lub Sophos Fusion (dawniej Sophos Central), ponownie zbuduj wyniki per element i po nowej akceptacji wyślij tylko cele, które nadal istnieją.

Limity, błędy i odbiór produkcyjny

Sophos dokumentuje dziennie 10 000 żądań Create, Update i Delete oraz 20 000 Get; przewodnik podaje, że limit godzinowy jest równy dziennemu. Zmiany nazw, aliasów, delegatów i właścicieli liczą się jako Update. Po 429 wstrzymaj pracę w ustalonych granicach; nie zwiększaj współbieżności i nie powtarzaj automatycznie mutacji. Większą kwotę uzgadnia Sophos Support.

Przed produkcją przetestuj: pełną paginację i jeden filtr na żądanie; walidację limitów typu, adresu, nazwy i tablic; uzgadnianie odpowiedzi bulk i relacji per element; GET lub inwentarz po każdym zapisie; osobną obsługę 400, 404, 409, 429, 5xx; brak automatycznych ponowień Delete i innych nieidempotentnych operacji po niepewnym wyniku. Dzięki temu API pozostaje narzędziem automatyzacji, a nie konkurencyjnym źródłem prawdy.