Headers valideren

  • Artikel
  • 8 minuten om te lezen

Het validate-headers beleid valideert de antwoordheaders op basis van het API-schema.

Belangrijk

Als u een API hebt geïmporteerd met behulp van een beheer-API-versie ouder dan 2021-01-01-preview, werkt het validate-headers beleid mogelijk niet. Mogelijk moet u uw API opnieuw importeren met behulp van de beheer-API-versie 2021-01-01-preview of hoger.

Notitie

De maximale grootte van het API-schema dat door dit validatiebeleid kan worden gebruikt, is 4 MB. Als het schema deze limiet overschrijdt, retourneert validatiebeleid fouten tijdens runtime. Neem contact op met ondersteuning als u deze wilt verhogen.

Notitie

Stel de beleidselementen en onderliggende elementen in de volgorde in die in de beleidsinstructie is opgegeven. Om u te helpen dit beleid te configureren, biedt de portal een begeleide, op formulieren gebaseerde editor. Meer informatie over het instellen of bewerken van API Management beleid.

Beleidsverklaring

<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>

Kenmerken

Kenmerk Beschrijving Vereist Standaard
specified-header-action Actie die moet worden uitgevoerd voor antwoordheaders die zijn opgegeven in het API-schema. Beleidsexpressies zijn toegestaan. Ja N.v.t.
unspecified-header-action Actie die moet worden uitgevoerd voor antwoordheaders die niet zijn opgegeven in het API-schema. Beleidsexpressies zijn toegestaan. Ja N.v.t.
errors-variable-name Naam van de variabele in om validatiefouten in context.Variables te registreren. Beleidsexpressies zijn niet toegestaan. Nee N.v.t.

Elementen

Naam Beschrijving Vereist
koptekst Voeg een of meer elementen toe voor benoemde headers om de standaardvalidatieacties voor headers in antwoorden te overschrijven. No

Acties

Het beleid voor inhoudsvalidatie bevat een of meer kenmerken die een actie opgeven, die API Management uitvoert bij het valideren van een entiteit in een API-aanvraag of -antwoord op basis van het API-schema.

  • Een actie kan worden opgegeven voor elementen die worden weergegeven in het API-schema en, afhankelijk van het beleid, voor elementen die niet worden weergegeven in het API-schema.

  • Een actie die is opgegeven in het onderliggende element van een beleid overschrijft een actie die is opgegeven voor het bovenliggende element.

Beschikbare acties:

Actie Beschrijving
Negeren Validatie overslaan.
Voorkomen Blokkeer de verwerking van de aanvraag of het antwoord, registreer de uitgebreide validatiefout en retourneer een fout. De verwerking wordt onderbroken wanneer de eerste set fouten wordt gedetecteerd.
detect Logboekvalidatiefouten, zonder de verwerking van aanvragen of antwoorden te onderbreken.

Gebruik

Logboeken

Details over de validatiefouten tijdens het uitvoeren van beleid worden vastgelegd in de variabele in die context.Variables is opgegeven in het errors-variable-name kenmerk in het hoofdelement van het beleid. Wanneer deze is geconfigureerd in een prevent actie, blokkeert een validatiefout verdere verwerking van aanvragen of antwoorden en wordt deze ook doorgegeven aan de context.LastError eigenschap.

Als u fouten wilt onderzoeken, gebruikt u een traceringsbeleid om de fouten van contextvariabelen in Application Insights te registreren.

Gevolgen voor de prestaties

Het toevoegen van een validatiebeleid kan van invloed zijn op DE API-doorvoer. De volgende algemene principes zijn van toepassing:

  • Hoe groter de API-schemagrootte, hoe lager de doorvoer.
  • Hoe groter de nettolading in een aanvraag of antwoord, hoe lager de doorvoer.
  • De grootte van het API-schema heeft een grotere invloed op de prestaties dan de grootte van de nettolading.
  • Validatie op basis van een API-schema dat enkele megabytes groot is, kan onder bepaalde omstandigheden time-outs van aanvragen of reacties veroorzaken. Het effect wordt meer uitgesproken in de lagen Verbruik en Ontwikkelaars van de service.

We raden u aan belastingtests uit te voeren met uw verwachte productieworkloads om de impact van validatiebeleid op API-doorvoer te beoordelen.

Voorbeeld

<validate-headers specified-header-action="ignore" unspecified-header-action="prevent" errors-variable-name="responseHeadersValidation" />

Validatiefouten

API Management genereert inhoudsvalidatiefouten in de volgende indeling:

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

De volgende tabel bevat alle mogelijke fouten van het validatiebeleid.

  • Details: Kan worden gebruikt om fouten te onderzoeken. Niet bedoeld om openbaar te worden gedeeld.
  • Openbaar antwoord: fout geretourneerd naar de client. Er worden geen implementatiegegevens gelekt.

Wanneer een validatiebeleid de prevent actie specificeert en een fout produceert, bevat het antwoord van API Management een HTTP-statuscode: 400 wanneer het beleid wordt toegepast in de sectie binnenkomend en 502 wanneer het beleid wordt toegepast in de uitgaande sectie.

Naam Type Validatieregel Details Openbaar antwoord Actie
validate-content
RequestBody SizeLimit De hoofdtekst van de aanvraag is {size} bytes lang en overschrijdt de geconfigureerde limiet van {maxSize} bytes. De hoofdtekst van de aanvraag is {size} bytes lang en overschrijdt de limiet van {maxSize} bytes. detecteren/voorkomen
ResponseBody SizeLimit De hoofdtekst van het antwoord is {size} bytes lang en overschrijdt de geconfigureerde limiet van {maxSize} bytes. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
{messageContentType} RequestBody Niet opgegeven Niet-opgegeven inhoudstype {messageContentType} is niet toegestaan. Niet-opgegeven inhoudstype {messageContentType} is niet toegestaan. detecteren/voorkomen
{messageContentType} ResponseBody Niet opgegeven Niet-opgegeven inhoudstype {messageContentType} is niet toegestaan. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
ApiSchema Het schema van de API bestaat niet of kan niet worden omgezet. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
ApiSchema In het schema van de API worden geen definities opgegeven. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
{messageContentType} RequestBody/ResponseBody MissingDefinition Het schema van de API bevat geen definitie {definitionName}, die is gekoppeld aan het inhoudstype {messageContentType}. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
{messageContentType} RequestBody IncorrectMessage De hoofdtekst van de aanvraag voldoet niet aan de definitie {definitionName}, die is gekoppeld aan het inhoudstype {messageContentType}.

{valError.Message} Regel: {valError.LineNumber}, Positie: {valError.LinePosition}		 De hoofdtekst van de aanvraag voldoet niet aan de definitie {definitionName}, die is gekoppeld aan het inhoudstype {messageContentType}.

{valError.Message} Regel: {valError.LineNumber}, Positie: {valError.LinePosition}		 detecteren/voorkomen
{messageContentType} ResponseBody IncorrectMessage De hoofdtekst van het antwoord voldoet niet aan de definitie {definitionName}, die is gekoppeld aan het inhoudstype {messageContentType}.

{valError.Message} Regel: {valError.LineNumber}, Positie: {valError.LinePosition}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
RequestBody ValidationException De hoofdtekst van de aanvraag kan niet worden gevalideerd voor het inhoudstype {messageContentType}.

{uitzonderingsdetails}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
ResponseBody ValidationException De hoofdtekst van het antwoord kan niet worden gevalideerd voor het inhoudstype {messageContentType}.

{uitzonderingsdetails}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
validate-parameters /validate-headers
{paramName} / {headerName} QueryParameter/PathParameter/RequestHeader Niet opgegeven Niet-opgegeven {padparameter/queryparameter/header} {paramName} is niet toegestaan. Niet-opgegeven {padparameter/queryparameter/header} {paramName} is niet toegestaan. detecteren/voorkomen
{headerName} ResponseHeader Niet opgegeven Niet-opgegeven header {headerName} is niet toegestaan. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
ApiSchema Het schema van de API bestaat niet of kan niet worden omgezet. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
ApiSchema Het API-schema geeft geen definities op. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
{paramName} QueryParameter/PathParameter/RequestHeader/ResponseHeader MissingDefinition Het schema van de API bevat geen definitie {definitionName}, die is gekoppeld aan de {queryparameter / padparameter / header} {paramName}. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage Aanvraag kan niet meerdere waarden bevatten voor de {queryparameter/padparameter/header} {paramName}. Aanvraag kan niet meerdere waarden bevatten voor de {queryparameter/padparameter/header} {paramName}. detecteren/voorkomen
{headerName} ResponseHeader IncorrectMessage Het antwoord mag niet meerdere waarden bevatten voor de header {headerName}. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage De waarde van de {queryparameter / padparameter / header} {paramName} voldoet niet aan de definitie.

{valError.Message} Regel: {valError.LineNumber}, Positie: {valError.LinePosition}		 De waarde van de {queryparameter/padparameter/header} {paramName} voldoet niet aan de definitie.

{valError.Message} Regel: {valError.LineNumber}, Positie: {valError.LinePosition}		 detecteren/voorkomen
{headerName} ResponseHeader IncorrectMessage De waarde van de header {headerName} voldoet niet aan de definitie.

{valError.Message} Regel: {valError.LineNumber}, Positie: {valError.LinePosition}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
{paramName} QueryParameter/PathParameter/RequestHeader IncorrectMessage De waarde van de {queryparameter/padparameter/header} {paramName} kan niet worden geparseerd volgens de definitie.

{ex. Bericht}		 De waarde van de {queryparameter / padparameter / header} {paramName} kan niet worden geparseerd volgens de definitie.

{ex. Bericht}		 detecteren/voorkomen
{headerName} ResponseHeader IncorrectMessage De waarde van de header {headerName} kan niet worden geparseerd volgens de definitie. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
{paramName} QueryParameter/PathParameter/RequestHeader ValidationError {Queryparameter / Padparameter / Header} {paramName} kan niet worden gevalideerd.

{uitzonderingsdetails}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
{headerName} ResponseHeader ValidationError De header {headerName} kan niet worden gevalideerd.

{uitzonderingsdetails}		 De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen
validate-status-code
{status-code} Statuscode Niet opgegeven Antwoordstatuscode {status-code} is niet toegestaan. De aanvraag kan niet worden verwerkt vanwege een interne fout. Neem contact op met de EIGENAAR van de API. detecteren/voorkomen

De volgende tabel bevat alle mogelijke redenwaarden van een validatiefout, samen met mogelijke berichtwaarden:

Reden Bericht
Ongeldige aanvraag {Details} voor contextvariabele, {Openbaar antwoord} voor client
Antwoord niet toegestaan {Details} voor contextvariabele, {Openbaar antwoord} voor client

Volgende stappen

Zie voor meer informatie over het werken met beleid: