Sign inGet Started

Idempotentność

Sieć zawodzi w najgorszych momentach: wysyłasz POST, połączenie się zrywa i nie wiesz, czy e-mail został wysłany. Idempotentność pozwala bezpiecznie ponowić to żądanie. Wyślij ten sam nagłówek Idempotency-Key jeszcze raz, a Bird odtworzy oryginalną odpowiedź zamiast przetwarzać żądanie po raz drugi.

Jak to działa

Idempotencja jest funkcją opt-in. Dodaj nagłówek Idempotency-Key do obsługiwanego żądania POST, PATCH, PUT lub DELETE. Żądania bez niego są przetwarzane normalnie, bez deduplikacji. Żądania GET ignorują ten nagłówek.
W API klienta mutacje o zasięgu obszaru roboczego i organizacji obsługują opisane poniżej odtwarzanie odpowiedzi. Operacje dostępne wyłącznie dla użytkownika, nieuwierzytelnione operacje bez zakresu oraz strumienie pomijają ten mechanizm. Operacje z osobnym kontraktem odtwarzania definiują swoje zachowanie na swojej stronie referencyjnej. Na przykład Utwórz połączenie głosowe zachowuje oryginalny snapshot akceptacji dla pasujących ponownych prób, gdy podasz klucz.
SDK generują klucz dla każdego wywołania mutującego i używają go ponownie przy automatycznych ponownych próbach, w tym przy tworzeniu połączeń. Nie musisz podawać własnego klucza dla automatycznych ponownych prób SDK. Podaj własny, gdy jedna zamierzona operacja obejmuje osobne wywołania SDK, na przykład ponowną próbę po restarcie aplikacji. Poniższe przykłady pokazują ten przypadek.
await bird.email.send(
  {
    from: "hello@yourdomain.com",
    to: ["delivered@messagebird.dev"],
    subject: "Welcome!",
    html: "<p>Thanks for signing up.</p>",
  },
  { idempotencyKey: "welcome-user/usr_abc123" },
);
Klucz to dowolny niepusty ciąg znaków o długości do 255 znaków. Pusta wartość nagłówka pomija deduplikację. Zalecanym formatem jest klucz deterministyczny wyprowadzony z własnych encji, <event-type>/<entity-id> (na przykład welcome-user/usr_abc123), dzięki czemu ponowne próby po restartach procesów współdzielą klucz; losowy UUID na operację logiczną też działa. SDK Bird generują klucz UUID automatycznie dla każdego żądania mutującego i używają go ponownie w swoich wewnętrznych ponownych próbach.
Klucze mają zakres ograniczony do obszaru roboczego lub do organizacji w przypadku endpointów na poziomie organizacji. Ukończona odpowiedź jest przechowywana przez 3 godziny; ponowienie po tym oknie jest przetwarzane jako nowe żądanie. Okno pokrywa typowe harmonogramy ponawiania. Po jego wygaśnięciu nie pozostaje żaden rekord deduplikacji.

Odtwarzanie odpowiedzi

Gdy Bird widzi klucz, dla którego przetwarzanie już się zakończyło, zwraca zapisaną odpowiedź: ten sam kod statusu, to samo ciało, bez ponownego uruchamiania żądania. Odtworzone odpowiedzi zawierają dodatkowy nagłówek, dzięki któremu odróżnisz je od świeżego przetwarzania:
Przykład kodu
HTTP/1.1 202 Accepted
Idempotency-Replay: true
Zachowane odpowiedzi mogą zawierać odrzucenia 4xx. Użyj nowego klucza, poprawiając żądanie: jeśli odrzucenie zostało zachowane, niezmieniona ponowna próba je odtworzy, a zmienione żądanie zwróci 409 E01005 IdempotencyKeyReuse. Odpowiedzi 5xx nie są zachowywane, więc ponawiaj je z tym samym kluczem i żądaniem.

Tryby awarii

ScenariuszOdpowiedź
Ten sam klucz, to samo żądanie, oryginał zakończonyZapisana odpowiedź odtworzona z Idempotency-Replay: true
Ten sam klucz, inne ciało żądania lub endpoint409, E01005 IdempotencyKeyReuse
Ten sam klucz, oryginalne żądanie wciąż w trakcie409, E01004 RequestInProgress
Klucz dłuższy niż 255 znaków na endpoincie deklarującym nagłówek422, E01001 ValidationError
Ochrona idempotentności niedostępna przed wykonaniem503, E01033 IdempotencyUnavailable; ta próba nie jest wykonywana
Ponowne użycie zakończonego klucza z innym żądaniem jest traktowane jako błąd klienta: Bird natychmiast zwraca 409, zamiast po cichu oddawać odpowiedź, która nie pasuje do tego, co wysłałeś. Wygeneruj nowy klucz dla nowego żądania. Porównanie obejmuje metodę, endpoint, ścieżkę i parametry zapytania oraz surowe ciało żądania, łącznie z JSON białymi znakami. Przesyłanie wieloczęściowe (multipart) porównuje nazwy części, nazwy plików i zawartość; granice i kolejność części nie wpływają na odtworzenie.
RequestInProgress oznacza, że równoległe żądanie z tym samym kluczem jeszcze się nie zakończyło. Zwykle przyczyną jest agresywny timeout po stronie klienta, który ponawia żądanie, gdy pierwsza próba wciąż trwa. Blokada w trakcie przetwarzania wygasa w ciągu 30 sekund, więc odczekaj chwilę i spróbuj ponownie. Opis formatu tych odpowiedzi znajdziesz w sekcji Błędy.

Co nie jest zapisywane w cache

Odpowiedzi 5xx nigdy nie są zapisywane w cache. Klucz zostaje odblokowany i Bird może przetworzyć ponowienie jako nową próbę. Ponawiaj odpowiedzi 5xx i timeouty z wycofywaniem wykładniczym, używając tego samego klucza i żądania. Operacja może zostać wykonana, zanim jej odpowiedź zostanie zachowana; jeśli ta odpowiedź zostanie utracona lub blokada w trakcie przetwarzania wygaśnie, ponowienie może wykonać operację ponownie.
Jeśli ochrona idempotentności jest niedostępna przed wykonaniem, API zwraca 503 E01033 IdempotencyUnavailable bez wykonywania tej próby. Zachowaj klucz przy każdym ponowieniu. Ten błąd nie opisuje wyniku wcześniejszej próby z tym samym kluczem.

Wskazówki praktyczne

  • Generuj jeden klucz na operację logiczną i używaj go ponownie przy każdej próbie HTTP tej operacji.
  • Ponawiaj przy błędach sieciowych, timeoutach i 5xx z wycofywaniem wykładniczym, za każdym razem używając tego samego klucza.
  • Traktuj 409 IdempotencyKeyReuse jako błąd w generowaniu kluczy. Nie ponawiaj tego żądania.
  • Klucze są opcjonalne dla mutacji. Używaj ich, gdy potrzebujesz ochrony przy ponownych próbach; pomijaj je w żądaniach GET.

Następne kroki

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.