Wyjaśnij zadanie i decyzję
Ten przewodnik zmienia przewodnik Szybki Start dotyczący interfejsu API w możliwy do przejrzenia przepływ pracy. Łączy decyzje dotyczące domeny, własność, dowody i akceptację, dzięki czemu wynik nadal sprawdza się w produkcji.
Zacznij od jednego uwierzytelnionego żądania, zatwierdź kontrakt odpowiedzi i dodaj obsługę awarii przed podłączeniem CMS.
Praktyczny proces
- 1
Typy źródeł zasobów reklamowych, identyfikatory, pola, ustawienia regionalne, właściciele i stany publikacji.
- 2
Wybierz wzorzec dostarczania spośród objętości, opóźnienia, kontroli redakcyjnej i tolerancji na awarie.
- 3
Zamapuj rekord źródłowy na osobny rekord wersji językowej z trwałym powiązaniem.
- 4
Dodaj uwierzytelnianie, idempotencję, ponawianie prób, unieważnianie pamięci podręcznej, rejestrowanie i kontrolę dostępu.
- 5
Publikacja testowa, zmiany w źródle, niedostępne wyniki, wycofywanie zmian, obsługa klawiatury i monitorowanie przed wydaniem.
Przykład lub narzędzie
Kompletna para żądania i odpowiedzi obejmuje uwierzytelnianie, ustawienia regionalne, tryb, idempotencję i obsługę błędów. W narzędziu zapisz także punkt odniesienia, właściciela, decyzję, dowody, otwartą kwestię i datę zatwierdzenia. Użyj prawdziwej strony lub transakcji, aby zespół mógł zobaczyć zależności, wyjątki i prace konserwacyjne następujące po wydaniu.
| Punkt decyzji | Nagrywać | Kryterium akceptacji |
|---|---|---|
| Linia bazowa | Zaobserwowany stan obecny | Źródło i data zapisu |
| Decyzja | Wybrana opcja i uzasadnienie | Uwzględniono ryzyko i odbiorców |
| Dowód | Testuj, dokumentuj lub mierz | Możliwość przeglądu i specyficzna dla wersji |
| Aprobata | Imię i nazwisko, rola i data | Wszystkie obowiązkowe kryteria spełnione |
Wyślij jedno żądanie w formie produkcyjnej
Utwórz klienta integracji po stronie serwera i zapisz jego poświadczenia w menedżerze tajnych wpisów wdrażania. Wyślij kod JSON w formacie UTF-8 przez HTTPS ze stabilnym identyfikatorem źródła, wersją źródła, żądanymi ustawieniami regionalnymi, trybem języka i treścią. Dodaj klucz idempotencji, który pozostaje taki sam, gdy zostanie ponowiona próba wykonania identycznego zadania. Nie ujawniaj danych uwierzytelniających w kodzie przeglądarki, plikach repozytorium, polach CMS, zrzutach ekranu ani odpowiedziach na błędy widoczne dla klienta.
Zacznij od reprezentatywnej, ale niewrażliwej strony usługi. Dołącz nagłówki, listy, linki oraz warunek prawny lub operacyjny, aby odpowiedź odzwierciedlała rzeczywistą treść umowy. Odrzuć pusty identyfikator źródła, nieobsługiwane ustawienia regionalne, nieznany tryb, zbyt dużą treść lub zniekształconą strukturę przed wywołaniem API. Ustaw jawny limit czasu połączenia i odpowiedzi oraz propaguj identyfikator korelacji do dzienników aplikacji.
| Pole żądania | Zamiar | Walidacja |
|---|---|---|
| identyfikator źródła | Trwałe łącze do rekordu CMS | Wymagane, stabilne, nieosobowe |
| wersja źródłowa | Wykrywa nieaktualne wyniki | Wymagane i niezmienne dla żądania |
| ustawienia regionalne i tryb | Wybiera reguły językowe | Musi to być włączona kombinacja |
| idempotencyKey | Sprawia, że ponowne próby są bezpieczne | Ta sama operacja wykorzystuje ten sam klucz |
Zatwierdź pełną umowę odpowiedzi
Traktuj pomyślny status HTTP jako tylko pierwszą kontrolę. Sprawdź schemat odpowiedzi, identyfikator wyniku, identyfikator źródła i wersję, ustawienia regionalne, tryb językowy, stan przetwarzania, bloki treści, ostrzeżenia oraz wersję modelu lub zestawu reguł, jeśli zostały dostarczone. Nieznane wartości wyliczeniowe i brakujące wymagane pola powinny zakończyć się niepowodzeniem i spowodować możliwy do sprawdzenia błąd integracji. Zachowaj ostrzeżenia obok wersji roboczej, ponieważ mogą one identyfikować terminologię, jakość źródła lub wymagania dotyczące ręcznej recenzji.
Przechowuj wygenerowane dane wyjściowe jako oddzielną wersję roboczą, zamiast nadpisywać zatwierdzone źródło. Zapisz identyfikatory żądań i wyników, ustawienia transformacji, znaczniki czasu i skrót integralności wersji źródłowej. Renderuj różnicę dla recenzentów i unikaj wszystkich wyników zgodnie z ich przeznaczeniem. Wygenerowane znaczniki stanowią niezaufane dane wejściowe do czasu zakończenia walidacji schematu, oczyszczenia, kontroli dostępności i zatwierdzenia przez człowieka.
- 1
Sprawdź ładunek wychodzący względem schematu lokalnego.
- 2
Wyślij żądanie z nagłówkami uwierzytelniania, limitu czasu, idempotencji i korelacji.
- 3
Sprawdź stan, nagłówki i treść odpowiedzi pod kątem przypiętej umowy.
- 4
Utwórz osobną wersję roboczą CMS powiązaną z dokładną wersją źródłową.
- 5
Kieruj ostrzeżenia i różnice do właściwej kolejki recenzji redakcyjnych.
Radź sobie z błędami bez powielania i utraty pracy
Limity czasu ponownych prób, awarie połączeń i limity szybkości tylko wtedy, gdy operacja jest idempotentna. Używaj ograniczonego wykładniczego wycofywania z jitterem i przestrzegaj opóźnienia ponownej próby zapewnianego przez serwer. Nie należy ponawiać prób błędów sprawdzania poprawności, błędów uwierzytelniania lub nieobsługiwanych opcji, dopóki konfiguracja nie zostanie zmieniona. Umieść wyczerpane operacje w kolejce utraconych wiadomości, podając odwołanie do źródła, kategorię bezpiecznego błędu, liczbę prób i następny odpowiedzialny zespół.
Oddziel stan widoczny dla użytkownika od szczegółów diagnostycznych. Redaktorzy potrzebują jasnych stanów, takich jak kolejka, przetwarzanie, wersja robocza gotowa, wymagane działanie i niepowodzenie w bezpiecznym następnym kroku. Operacje wymagają identyfikatorów żądań, czasu trwania, kategorii stanu i historii ponownych prób, ale nie pełnego tekstu źródłowego w zwykłych dziennikach. Powiadamiaj o utrzymującym się poziomie błędów, rosnącym wieku kolejek, błędach uwierzytelniania, niezgodnościach schematów i wersjach roboczych, których wersja źródłowa zmieniła się podczas przetwarzania.
Każda operacja, którą można ponowić, ma stabilny klucz idempotencji.
Backoff jest ograniczony i uwzględnia instrukcje dotyczące limitów stawek.
Dzienniki nie obejmują poświadczeń i niepotrzebnych treści.
Elementy niedostarczone mają właściciela i procedurę odtwarzania.
Nieaktualny wynik nie może po cichu zastąpić nowszej wersji źródła.
Udowodnij integrację przed wydaniem
Testuj prawidłowe żądania, każdy udokumentowany błąd walidacji, wygasłe i unieważnione poświadczenia, przekroczenia limitu czasu, limity szybkości, zduplikowane przesyłanie, zakończenie poza kolejnością, ewolucję schematu, oczyszczanie i zmiany źródeł podczas przetwarzania. Potwierdź, że monitorowanie identyfikuje każdą awarię i że przeszkolony operator może odtworzyć lub zamknąć element bez edytowania bazy danych. Przeprowadź kontrolę dostępności i redakcję wyrenderowanej wersji roboczej, a nie tylko surowej odpowiedzi.
Wersja z ograniczonymi danymi uwierzytelniającymi, zdefiniowanymi limitami stawek i wydatków, pulpitami nawigacyjnymi, własnością alertów i przełącznikiem wycofywania, który zatrzymuje nową generację bez wpływu na publikowane treści. Przypnij obsługiwaną wersję umowy i zaplanuj przegląd aktualizacji. Zapis odbioru produkcji powinien zawierać dowody testów, zatwierdzenie bezpieczeństwa, dokumentację przepływu danych, podpis recenzenta, instrukcje obsługi oraz pomyślne przywrócenie jednego celowo nieudanego zadania.
Role, dowody i zatwierdzenie
Trzymaj generowanie oddzielnie od publikacji. Pomyślna odpowiedź to projekt, a nie zatwierdzenie. Przechowuj identyfikator źródła i wersję, ustawienia transformacji, identyfikator wyniku, stan recenzji, osobę zatwierdzającą i godzinę publikacji. Gdy zmieni się źródło, zaznacz wersję językową do sprawdzenia, zamiast po cichu zastępować zatwierdzoną treść. Dzięki temu możliwe jest wycofywanie zmian i inspekcja na różnych platformach.
Eksploatacja i konserwacja
Praca nie kończy się w momencie publikacji. Połącz wersję językową lub konfigurację ze źródłem, monitoruj jakość i miary usług oraz zdefiniuj konkretne wyzwalacze przeglądu. Wyzwalacze obejmują zmiany źródła, zmiany prawne, nowe potrzeby odbiorców, powtarzające się pytania dotyczące pomocy, zmiany techniczne i incydenty. Nazwany właściciel ocenia wyzwalacz, w razie potrzeby otwiera nową wersję i rejestruje ponowne zatwierdzenie.
Lista kontrolna przed publikacją
Integracja wykorzystuje trwałe identyfikatory źródła.
Poświadczenia są przechowywane po stronie serwera i podlegają rotacji.
Zdefiniowano limit czasu, ponowną próbę i zachowanie limitu szybkości.
Powtarzające się żądania są idempotentne.
Wygenerowana treść przechodzi w stan recenzji.
Zmiany źródła unieważniają lub ponownie otwierają wersję.
Nawigacja językowa działa za pomocą klawiatury i technologii wspomagających.
Monitorowanie obejmuje awarie, kolejki, opóźnienia i nieaktualne treści.