Share via

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ę.
Zapobiec 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

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 aplikacji Szczegółowe informacje.

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: