Udostępnij za pośrednictwem

Weryfikowanie kodu stanu

  • Artykuł

DOTYCZY: Wszystkie warstwy usługi API Management

Zasady validate-status-code weryfikują kody stanu HTTP w odpowiedziach względem schematu interfejsu API. Te zasady mogą służyć do zapobiegania wyciekom błędów zaplecza, które mogą zawierać ślady stosu.

Uwaga

Maksymalny rozmiar schematu interfejsu API, który może być używany przez te zasady sprawdzania poprawności, wynosi 4 MB. Jeśli schemat przekroczy ten limit, zasady walidacji będą zwracać błędy w czasie wykonywania. Aby go zwiększyć, skontaktuj się z pomocą techniczną.

Uwaga

Ustaw elementy zasad i elementy podrzędne w kolejności podanej w instrukcji zasad. Aby ułatwić konfigurowanie tych zasad, portal udostępnia edytor oparty na formularzach z przewodnikiem. Dowiedz się więcej na temat ustawiania lub edytowania zasad usługi API Management.

Instrukcja zasad

<validate-status-code unspecified-status-code-action="ignore | prevent | detect" errors-variable-name="variable name">
    <status-code code="HTTP status code number" action="ignore | prevent | detect" />
</validate-status-code>

Atrybuty

Atrybut opis Wymagani Wartość domyślna
nieokreślone-status-code-action Akcja do wykonania dla kodów stanu HTTP w odpowiedziach, które nie są określone w schemacie interfejsu API. Wyrażenia zasad są dozwolone. Tak Nie dotyczy
errors-variable-name Nazwa zmiennej w pliku , context.Variables aby rejestrować błędy walidacji. Wyrażenia zasad nie są dozwolone. Nie. Nie dotyczy

Elementy

Nazwa/nazwisko opis Wymagania
kod stanu Dodaj co najmniej jeden element kodów stanu HTTP, aby zastąpić domyślną akcję walidacji kodów stanu w odpowiedziach. Nie.

atrybuty kodu stanu

Atrybut opis Wymagani Wartość domyślna
code Kod stanu HTTP, aby zastąpić akcję walidacji dla. Tak Nie dotyczy
action Akcja do wykonania dla zgodnego kodu stanu, który nie jest określony w schemacie interfejsu API. Jeśli kod stanu został określony w schemacie interfejsu API, to zastąpienie nie zostanie zastosowane. Tak Nie dotyczy

Akcje

Zasady sprawdzania poprawności zawartości obejmują co najmniej jeden atrybut określający akcję, która jest wykonywana przez usługę API Management podczas weryfikowania jednostki w żądaniu interfejsu API lub odpowiedzi względem schematu interfejsu API.

  • Można określić akcję dla elementów reprezentowanych w schemacie interfejsu API i, w zależności od zasad, dla elementów, które nie są reprezentowane w schemacie interfejsu API.

  • Akcja określona w elemecie podrzędnym zasad zastępuje akcję określoną dla jej elementu nadrzędnego.

Dostępne akcje:

Akcja opis
ignoruj Pomiń walidację.
zapobiegać Blokuj przetwarzanie żądania lub odpowiedzi, rejestruj pełny błąd weryfikacji i zwraca błąd. Przetwarzanie jest przerywane po wykryciu pierwszego zestawu błędów.
detect Błędy walidacji dziennika bez przerywania przetwarzania żądań lub odpowiedzi.

Użycie

  • Sekcje zasad: ruch wychodzący, błąd
  • Zakresy zasad: globalny, obszar roboczy, produkt, interfejs API, operacja
  • Bramy: klasyczne, v2, zużycie, self-hosted, obszar roboczy

Uwagi dotyczące użycia

  • Te zasady można użyć tylko raz w sekcji zasad.

Dzienniki

Szczegółowe informacje o błędach walidacji podczas wykonywania zasad są rejestrowane w zmiennej context.Variables określonej w atrybucie errors-variable-name w elemecie głównym zasad. Po skonfigurowaniu prevent w akcji błąd walidacji blokuje dalsze przetwarzanie żądań lub odpowiedzi, a także jest propagowany do context.LastError właściwości .

Aby zbadać błędy, użyj zasad śledzenia , aby rejestrować błędy ze zmiennych kontekstowych do usługi Application Insights.

Implikacje dotyczące wydajności

Dodanie zasad weryfikacji może mieć wpływ na przepływność interfejsu API. Obowiązują następujące ogólne zasady:

  • Im większy rozmiar schematu interfejsu API, tym niższa będzie przepływność.
  • Im większy ładunek w żądaniu lub odpowiedzi, tym niższa będzie przepływność.
  • Rozmiar schematu interfejsu API ma większy wpływ na wydajność niż rozmiar ładunku.
  • Walidacja względem schematu interfejsu API o rozmiarze kilku megabajtów może spowodować przekroczenie limitu czasu żądania lub odpowiedzi w niektórych warunkach. Efekt jest bardziej widoczny w warstwach Zużycie i Deweloper usługi.

Zalecamy przeprowadzenie testów obciążeniowych z oczekiwanymi obciążeniami produkcyjnymi, aby ocenić wpływ zasad walidacji na przepływność interfejsu API.

Przykład

<validate-status-code unspecified-status-code-action="prevent" errors-variable-name="responseStatusCodeValidation" />

Błędy walidacji

Usługa API Management generuje błędy walidacji zawartości w następującym formacie:

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

W poniższej tabeli wymieniono wszystkie możliwe błędy zasad walidacji.

  • Szczegóły: Może służyć do badania błędów. Nie ma być udostępniane publicznie.
  • Odpowiedź publiczna: błąd zwrócony do klienta. Nie wycieka szczegółów implementacji.

Gdy zasady weryfikacji określają prevent akcję i generują błąd, odpowiedź z usługi API Management zawiera kod stanu HTTP: 400, gdy zasady są stosowane w sekcji przychodzącej i 502, gdy zasady są stosowane w sekcji ruchu wychodzącego.

Nazwa/nazwisko Type Reguła walidacji Szczegóły Odpowiedź publiczna Akcja
validate-content
RequestBody RozmiarLimit Treść żądania ma długość {size} bajtów i przekracza skonfigurowany limit {maxSize} bajtów. Treść żądania ma długość {size} bajtów i przekracza limit {maxSize} bajtów. wykrywanie/zapobieganie
Treść odpowiedzi RozmiarLimit Treść odpowiedzi ma długość {size} bajtów i przekracza skonfigurowany limit {maxSize} bajtów. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
{messageContentType} RequestBody Nieokreślony Nieokreślony typ zawartości {messageContentType} jest niedozwolony. Nieokreślony typ zawartości {messageContentType} jest niedozwolony. wykrywanie/zapobieganie
{messageContentType} Treść odpowiedzi Nieokreślony Nieokreślony typ zawartości {messageContentType} jest niedozwolony. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
ApiSchema Schemat interfejsu API nie istnieje lub nie można go rozpoznać. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
ApiSchema Schemat interfejsu API nie określa definicji. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
{messageContentType} RequestBody /ResponseBody MissingDefinition (Brak definicji) Schemat interfejsu API nie zawiera definicji {definitionName}, która jest skojarzona z typem zawartości {messageContentType}. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
{messageContentType} RequestBody IncorrectMessage Treść żądania nie jest zgodna z definicją {definitionName}, która jest skojarzona z typem zawartości {messageContentType}.

{valError.Message} Wiersz: {valError.LineNumber}, pozycja: {valError.LinePosition}		 Treść żądania nie jest zgodna z definicją {definitionName}, która jest skojarzona z typem zawartości {messageContentType}.

{valError.Message} Wiersz: {valError.LineNumber}, pozycja: {valError.LinePosition}		 wykrywanie/zapobieganie
{messageContentType} Treść odpowiedzi IncorrectMessage Treść odpowiedzi nie jest zgodna z definicją {definitionName}, która jest skojarzona z typem zawartości {messageContentType}.

{valError.Message} Wiersz: {valError.LineNumber}, pozycja: {valError.LinePosition}		 Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
RequestBody ValidationException Nie można zweryfikować treści żądania dla typu zawartości {messageContentType}.

{szczegóły wyjątku}		 Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
Treść odpowiedzi ValidationException Nie można zweryfikować treści odpowiedzi dla typu zawartości {messageContentType}.

{szczegóły wyjątku}		 Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
validate-parameters/validate-headers
{paramName} / {headerName} QueryParameter / PathParameter / RequestHeader Nieokreślony Nieokreślony parametr ścieżki / parametr zapytania / nagłówek} {paramName} jest niedozwolony. Nieokreślony parametr ścieżki / parametr zapytania / nagłówek} {paramName} jest niedozwolony. wykrywanie/zapobieganie
{headerName} ResponseHeader Nieokreślony Nieokreślony nagłówek {headerName} jest niedozwolony. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
ApiSchema Schemat interfejsu API nie istnieje lub nie można go rozpoznać. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
ApiSchema Schemat interfejsu API nie określa definicji. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
{paramName} QueryParameter / PathParameter / RequestHeader / ResponseHeader MissingDefinition (Brak definicji) Schemat interfejsu API nie zawiera definicji {definitionName}, która jest skojarzona z parametrem zapytania / parametrem ścieżki / nagłówkiem} {paramName}. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage Żądanie nie może zawierać wielu wartości dla parametru {query / parametru ścieżki / nagłówka} {paramName}. Żądanie nie może zawierać wielu wartości dla parametru {query / parametru ścieżki / nagłówka} {paramName}. wykrywanie/zapobieganie
{headerName} ResponseHeader IncorrectMessage Odpowiedź nie może zawierać wielu wartości nagłówka {headerName}. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage Wartość parametru zapytania / parametru ścieżki / nagłówka} {paramName} nie jest zgodna z definicją.

{valError.Message} Wiersz: {valError.LineNumber}, pozycja: {valError.LinePosition}		 Wartość parametru zapytania / parametru ścieżki / nagłówka} {paramName} nie jest zgodna z definicją.

{valError.Message} Wiersz: {valError.LineNumber}, pozycja: {valError.LinePosition}		 wykrywanie/zapobieganie
{headerName} ResponseHeader IncorrectMessage Wartość nagłówka {headerName} nie jest zgodna z definicją.

{valError.Message} Wiersz: {valError.LineNumber}, pozycja: {valError.LinePosition}		 Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage Nie można przeanalizować wartości {parametru kwerendy/parametru ścieżki/nagłówka} {paramName} zgodnie z definicją.

{np. Wiadomość}		 Nie można przeanalizować wartości {parametru kwerendy/parametru ścieżki/nagłówka} {paramName} zgodnie z definicją.

{np. Wiadomość}		 wykrywanie/zapobieganie
{headerName} ResponseHeader IncorrectMessage Nie można przeanalizować wartości nagłówka {headerName} zgodnie z definicją. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
{paramName} QueryParameter / PathParameter / RequestHeader ValidationError {Parametr zapytania / Parametr ścieżki / Nagłówek} Nie można zweryfikować parametru {paramName}.

{szczegóły wyjątku}		 Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
{headerName} ResponseHeader ValidationError Nie można zweryfikować nagłówka {headerName}.

{szczegóły wyjątku}		 Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie
validate-status-code
{status-code} StatusCode Nieokreślony Kod stanu odpowiedzi {kod stanu} jest niedozwolony. Nie można przetworzyć żądania z powodu błędu wewnętrznego. Skontaktuj się z właścicielem interfejsu API. wykrywanie/zapobieganie

W poniższej tabeli wymieniono wszystkie możliwe wartości Przyczyna błędu weryfikacji wraz z możliwymi wartościami komunikatu:

Przyczyna Wiadomość
Nieprawidłowe żądanie {Details} dla zmiennej kontekstowej { odpowiedź publiczna} dla klienta
Niedozwolona odpowiedź {Details} dla zmiennej kontekstowej { odpowiedź publiczna} dla klienta

Powiązana zawartość

Aby uzyskać więcej informacji na temat pracy z zasadami, zobacz: