Nagłówek Idempotency-Key

API Bird obsługuje opcjonalną deduplikację żądań za pomocą nagłówka Idempotency-Key. Ta strona definiuje kontrakt HTTP; strategię ponawiania opisano w sekcji Idempotencja.

Operacje modyfikujące o zakresie obszaru roboczego lub organizacji obsługują opisane poniżej ponowne zwracanie odpowiedzi. Operacje dotyczące wyłącznie użytkownika, nieuwierzytelnione operacje bez określonego zakresu i strumienie go nie używają. Operacje z odrębnym kontraktem ponownego zwracania odpowiedzi definiują swoje zachowanie na własnej stronie dokumentacji referencyjnej.

Pominięcie nagłówka lub wysłanie pustej wartości powoduje normalne przetworzenie żądania bez deduplikacji. W endpointach deklarujących ten nagłówek klucz dłuższy niż 255 znaków zwraca 422 z kodem E01001 ValidationError.

Klucze mają zakres Twojego obszaru roboczego lub Twojej organizacji w endpointach na poziomie organizacji i są przechowywane przez około 3 godziny. Po tym czasie żądanie ponownie używające klucza jest przetwarzane jako nowe żądanie.

Odtworzona odpowiedź jest bajt po bajcie identyczna z oryginałem (ten sam kod statusu, ta sama treść) i różni się tylko dodatkowym nagłówkiem:

HTTP/1.1 202 Accepted
Idempotency-Replay: true

"Identical request" obejmuje metodę, endpoint, parametry ścieżki i zapytania oraz surową treść żądania. Różnica w tych wartościach, w tym w białych znakach w JSON, powoduje E01005. Przy przesyłaniu multipart porównywane są nazwy części, nazwy plików i zawartość; granice i kolejność części nie wpływają na ponowne zwracanie odpowiedzi. Oba błędy 409 są zwracane w standardowej odpowiedzi z błędem.

Zachowane odpowiedzi mogą obejmować odrzucenia 4xx. Podczas poprawiania żądania użyj nowego klucza: jeśli odrzucenie zostało zachowane, ponowienie bez zmian zwraca je ponownie, a zmienione żądanie zwraca 409 E01005 IdempotencyKeyReuse.

Odpowiedzi 5xx nigdy nie są zapisywane w pamięci podręcznej. Spróbuj ponownie z wycofywaniem, używając tego samego klucza i żądania. E01033 IdempotencyUnavailable oznacza, że ta próba nie została wykonana; nie opisuje wyniku wcześniejszej próby. Zachowaj klucz przy każdym ponowieniu.

Operacja może zostać wykonana, zanim jej odpowiedź zostanie zachowana. Jeśli ta odpowiedź zostanie utracona lub blokada na żądanie w trakcie realizacji wygaśnie, ponowna próba może wykonać operację ponownie. Timeout lub kolejna odpowiedź 5xx nie dowodzi więc, że operacja nie miała żadnego efektu.

Oficjalne SDK dołączają automatycznie wygenerowany UUID Idempotency-Key do każdego mutującego żądania. UUID jest generowany raz na wywołanie logiczne i ponownie używany we wszystkich ponowieniach tego wywołania. Możesz podać własny klucz dla każdego wywołania (idempotencyKey w TypeScript, option.WithIdempotencyKey w Go, idempotency_key w Pythonie), gdy jedna operacja logiczna obejmuje wiele wywołań SDK. Aby wykryć powtórkę, odczytaj nagłówek odpowiedzi Idempotency-Replay przez akcesor metadanych transportu każdego SDK: .withResponse() w TypeScript, option.WithResponseInto w Go i with_raw_response w Pythonie.