Idempotentność

Użyj Idempotency-Key, gdy po nieudanym połączeniu nie wiesz, czy żądanie się powiodło. Gwarancją jest akceptacja dokładnie raz: ponowne próby z tym samym kluczem i identycznym żądaniem muszą prowadzić do jednej zaakceptowanej operacji w ciągu 3-godzinnego okna przechowywania, nawet jeśli utracisz oryginalną odpowiedź.

Jak to działa

Idempotentność 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" },
);

client.email.send(
    from_="hello@yourdomain.com",
    to=["delivered@messagebird.dev"],
    subject="Welcome!",
    html="<p>Thanks for signing up.</p>",
    options={"idempotency_key": "welcome-user/usr_abc123"},
)

_, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:    "hello@yourdomain.com",
	To:      []string{"delivered@messagebird.dev"},
	Subject: "Welcome!",
	HTML:    "<p>Thanks for signing up.</p>",
}, option.WithIdempotencyKey("welcome-user/usr_abc123"))

$bird->email->send(
    from: 'hello@yourdomain.com',
    to: ['delivered@messagebird.dev'],
    subject: 'Welcome!',
    html: '<p>Thanks for signing up.</p>',
    options: new RequestOptions(idempotencyKey: 'welcome-user/usr_abc123'),
);

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-user/usr_abc123" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Welcome!",
    "html": "<p>Thanks for signing up.</p>"
  }'

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; ponowna próba po tym oknie może zostać przetworzona jako nowe żądanie. Jeśli po wygaśnięciu okna wynik pierwotnej operacji jest nieznany, pozostaw ją nierozstrzygniętą i uzgodnij jej stan przed ponownym wysłaniem.

Odtwarzanie odpowiedzi

Pasująca ponowna próba w ciągu trzech godzin musi prowadzić do oryginalnej operacji. Gdy odpowiedź tej operacji jest zachowana, API zwraca ten sam kod statusu i to samo ciało bez akceptowania kolejnej operacji. Odtworzone odpowiedzi zawierają dodatkowy nagłówek, dzięki któremu odróżnisz je od świeżego przetwarzania:

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 jako ukończone odpowiedzi. Gwarancja akceptacji dokładnie raz obejmuje także ponowne próby po tych błędach.

Tryby awarii

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ąż jest przetwarzana. Odczekaj chwilę i spróbuj ponownie z tym samym kluczem i żądaniem. Opis odpowiedzi z błędem, w której są zwracane te błędy, znajdziesz w sekcji Błędy.

Co nie jest zapisywane w cache

Odpowiedzi 5xx nie są zachowywane jako ukończone odpowiedzi. Spróbuj ponownie w ciągu trzech godzin z ograniczonym wycofywaniem, tym samym kluczem i identycznym żądaniem. Gwarancja jednokrotnej akceptacji obowiązuje nawet wtedy, gdy oryginalna odpowiedź została utracona.

Jeśli ochrona idempotentności jest niedostępna przed wykonaniem, API zwraca 503 E01033 IdempotencyUnavailable bez wykonywania tej próby. Zachowaj klucz przy każdej ponownej próbie. 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.
• Przy błędach sieciowych, timeoutach i 5xx spróbuj ponownie w ciągu trzech godzin z ograniczonym wycofywaniem wykładniczym, zachowując klucz i identyczne żądanie.
• Gdy wyczerpiesz ponowne próby lub okno przechowywania wygaśnie, pozostaw nieznany wynik jako nierozstrzygnięty. Uzgodnij go, zanim wyślesz kolejną operację ze starym lub nowym kluczem.
• W przypadku wysyłki wiadomości sprawdź status wiadomości, aby po akceptacji potwierdzić doręczenie.
• Traktuj 409 IdempotencyKeyReuse jako błąd w generowaniu kluczy. Nie próbuj ponownie wysyłać 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

• Dokumentacja idempotentności API: schematy nagłówka i nagłówka odpowiedzi
• Koncepcje SDK: automatyczne generowanie kluczy i zachowanie ponownych prób w SDK
• Błędy: odpowiedź z błędem i katalog kodów
• Wysyłanie e-maili: endpointy wysyłki pojedynczej i zbiorczej