Weryfikowanie nagłówków
DOTYCZY: Wszystkie warstwy usługi API Management
Zasady validate-headers
weryfikują nagłówki odpowiedzi 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-headers
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-headers specified-header-action="ignore | prevent | detect" unspecified-header-action="ignore | prevent | detect" errors-variable-name="variable name">
<header name="header name" action="ignore | prevent | detect" />
</validate-headers>
Atrybuty
Atrybut | opis | Wymagani | Wartość domyślna |
---|---|---|---|
określona akcja nagłówka | Akcja do wykonania dla nagłówków odpowiedzi określonych w schemacie interfejsu API. Wyrażenia zasad są dozwolone. | Tak | Nie dotyczy |
nieokreślona akcja nagłówka | Akcja do wykonania dla nagłówków odpowiedzi, 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 |
---|---|---|
nagłówek | Dodaj co najmniej jeden element dla nazwanych nagłówków, aby zastąpić domyślne akcje weryfikacji nagłówków w odpowiedziach. | 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
- Sekcje zasad: ruch wychodzący, błąd
- Zakresy zasad: globalny, obszar roboczy, produkt, interfejs API, operacja
- Bramy: klasyczne, v2, zużycie, self-hosted
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
<validate-headers specified-header-action="ignore" unspecified-header-action="prevent" errors-variable-name="responseHeadersValidation" />
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ązane zasady
Powiązana zawartość
Aby uzyskać więcej informacji na temat pracy z zasadami, zobacz:
- Samouczek: przekształcanie i ochrona interfejsu API
- Dokumentacja zasad dla pełnej listy instrukcji zasad i ich ustawień
- Wyrażenia zasad
- Ustawianie lub edytowanie zasad
- Ponowne używanie konfiguracji zasad
- Repozytorium fragmentów zasad
- Tworzenie zasad przy użyciu rozwiązania Microsoft Copilot dla platformy Azure