Udostępnij za pośrednictwem

Weryfikowanie parametrów

  • Artykuł

DOTYCZY: Wszystkie warstwy usługi API Management

Zasady validate-parameters weryfikują parametry nagłówka, zapytania lub ścieżki w żądaniach względem schematu interfejsu API.

Ważne

Jeśli interfejs API został zaimportowany przy użyciu wersji interfejsu API zarządzania wcześniejszej niż 2021-01-01-preview, validate-parameters zasady mogą nie działać. Może być konieczne ponowne zaimportuj interfejs API przy użyciu wersji interfejsu API zarządzania lub nowszej 2021-01-01-preview .

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-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </headers>
    <query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </query>
    <path specified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </path>
</validate-parameters>

Atrybuty

Atrybut opis Wymagani Wartość domyślna
określona akcja parametru Akcja do wykonania dla parametrów żądania określonych w schemacie interfejsu API.

W przypadku podania w elemecie headers, querylub path wartość zastępuje wartość specified-parameter-action elementu validate-parameters . Wyrażenia zasad są dozwolone.		 Tak Nie dotyczy
nieokreślone-parametr-action Akcja do wykonania dla parametrów żądania, które nie są określone w schemacie interfejsu API.

W przypadku podania w elemecie headerslub query wartość zastępuje wartość unspecified-parameter-action elementu validate-parameters . 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
nagłówki Dodaj ten element i co najmniej jeden parameter podelement, aby zastąpić domyślne akcje weryfikacji dla niektórych nazwanych parametrów w żądaniach. Jeśli parametr jest określony w schemacie interfejsu API, ta wartość zastępuje konfigurację wyższego poziomu specified-parameter-action . Jeśli parametr nie jest określony w schemacie interfejsu API, ta wartość zastępuje konfigurację wyższego poziomu unspecified-parameter-action . Nie.
zapytanie Dodaj ten element i co parameter najmniej jeden podelement, aby zastąpić domyślne akcje walidacji dla niektórych nazwanych parametrów zapytania w żądaniach. Jeśli parametr jest określony w schemacie interfejsu API, ta wartość zastępuje konfigurację wyższego poziomu specified-parameter-action . Jeśli parametr nie jest określony w schemacie interfejsu API, ta wartość zastępuje konfigurację wyższego poziomu unspecified-parameter-action . Nie.
path Dodaj ten element i co najmniej jeden parameter podelement, aby zastąpić domyślne akcje sprawdzania poprawności dla niektórych parametrów ścieżki adresu URL w żądaniach. Jeśli parametr jest określony w schemacie interfejsu API, ta wartość zastępuje konfigurację wyższego poziomu specified-parameter-action . Jeśli parametr nie jest określony w schemacie interfejsu API, ta wartość zastępuje konfigurację wyższego poziomu unspecified-parameter-action . Nie.

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 przychodzący
  • 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

W tym przykładzie wszystkie parametry zapytania i ścieżki są weryfikowane w trybie zapobiegania i nagłówkom w trybie wykrywania. Walidacja jest zastępowana dla kilku parametrów nagłówka:

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

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: