Nagłówek Idempotency-Key

Użyj Idempotency-Key, aby ponownie spróbować wysłać żądanie bez tworzenia zduplikowanej operacji. Gwarancją jest akceptacja dokładnie raz: w 3-godzinnym oknie retencji ponowne próby z tym samym kluczem i identycznym żądaniem muszą prowadzić do oryginalnej operacji, nawet jeśli utracono jej odpowiedź. Strategię ponownych prób opisano w sekcji Idempotencja.

Nagłówek żądania

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.

Semantyka odpowiedzi

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, ponowna próba bez zmian zwraca je ponownie, a zmienione żądanie zwraca 409 E01005 IdempotencyKeyReuse.

Po przekroczeniu limitu czasu lub otrzymaniu 5xx spróbuj ponownie z ograniczonym wycofywaniem, używając tego samego klucza i identycznego żądania w ciągu trzech godzin. Gwarancja akceptacji dokładnie raz obowiązuje nawet wtedy, gdy oryginalna odpowiedź została utracona. E01033 IdempotencyUnavailable oznacza, że ta próba nie została wykonana; nie opisuje wyniku wcześniejszej próby. Zachowaj klucz przy każdej ponownej próbie.

W przypadku wysyłki wiadomości akceptacja dokładnie raz oznacza jedną zaakceptowaną wysyłkę dla wszystkich pasujących ponownych prób. Sprawdź status wiadomości, aby potwierdzić dostarczenie. Po trzech godzinach sprawdź wynik oryginalnej operacji, zanim ponownie wyślesz żądanie: wygasły klucz lub nowy klucz może utworzyć kolejną operację.

Zachowanie SDK

Oficjalne SDK dołączają automatycznie wygenerowany UUID Idempotency-Key do każdego modyfikującego żądania. UUID jest generowany raz na wywołanie logiczne i ponownie używany we wszystkich ponownych próbach 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, new RequestOptions(idempotencyKey: ...) w PHP), 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.

Powiązane

• Koncepcje idempotentności: strategia ponownych prób, projektowanie kluczy i limity powtórek
• Odpowiedzi z błędami: odpowiedź z błędem opakowująca E01004 i E01005
• Wiadomości e-mail: endpoint wysyłania, najczęstsze miejsce użycia klucza
• Koncepcje SDK: automatyczne generowanie kluczy i ponowne próby