Norme di SOAPMessageValidation

Norme standard

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

La policy SOAPMessageValidation esegue le seguenti operazioni:

  • Convalida qualsiasi messaggio XML in base ai relativi schemi XSD
  • Convalida i messaggi SOAP rispetto a una definizione WSDL
  • Determina la validità dei messaggi JSON e XML

Anche se il nome di questa policy nell'interfaccia utente è SOAPMessageValidation, la policy convalida più di semplici messaggi SOAP. In questa sezione il criterio viene indicato come MessageValidation.

La convalida dei messaggi offre i seguenti vantaggi:

  • Informa immediatamente gli sviluppatori di app che utilizzano la tua API se le loro richieste non sono conformi o sono incomplete.
  • Individua i problemi nelle richieste, ad esempio i tag XML non chiusi correttamente.
  • Protegge i servizi di backend bloccando i messaggi XML o SOAP con strutture che potrebbero causare un comportamento imprevedibile.
  • Riduce il tempo dedicato alla risoluzione dei problemi, alla ricerca nei forum o alla consulenza con l'assistenza tecnica.
  • Incoraggia gli sviluppatori a familiarizzare con la definizione WSDL dello schema XML per eliminare gli errori di convalida, rendendo gli schemi XML ben compresi un componente chiave della documentazione dell'API.

Questa policy è una policy standard e può essere implementata in qualsiasi tipo di ambiente. Per informazioni sui tipi di policy e sulla disponibilità con ogni tipo di ambiente, consulta Tipi di policy.

Video

Guarda i seguenti video per saperne di più sulle norme MessageValidation:

Video Descrizione
Convalida la richiesta XML Convalida la richiesta XML per un'API utilizzando il criterio MessageValidation.
Convalida richiesta JSON Convalida la richiesta JSON per un'API utilizzando il criterio MessageValidation.

Elemento <MessageValidation>

Definisce la policy MessageValidation.

Valore predefinito Consulta la scheda Policy predefinita di seguito.
Obbligatorio? Facoltativo
Tipo Oggetto complesso
Elemento principale n/a
Elementi secondari <DisplayName>
<Element>
<ResourceURL>
<SOAPMessage>
<Source>

Sintassi

L'elemento <MessageValidation> utilizza la seguente sintassi:

<MessageValidation
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All MessageValidation child elements are optional -->
    <DisplayName>policy_display_name</DisplayName>
    <Element namespace="element_namespace">element_to_validate</Element>
    <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
    <Source>message_to_validate</Source>
    <ResourceURL>validation_WSDL_or_XSD</ResourceURL>

</MessageValidation>

Norme predefinite

L'esempio seguente mostra le impostazioni predefinite quando aggiungi un criterio MessageValidation al flusso nell'interfaccia utente Apigee:

<MessageValidation continueOnError="false" enabled="true" name="SOAP-Message-Validation-1">
  <DisplayName>SOAP Message Validation-1</DisplayName>
  <Properties/>
  <Element namespace="http://sample.com">sampleObject</Element>
  <SOAPMessage/>
  <Source>request</Source>
  <ResourceURL>wsdl://SOAP-Message-Validation-1.wsdl</ResourceURL>
</MessageValidation>

此元素具有所有政策中常见的以下属性:

属性 默认 是否必需? 说明
name 不适用 必需

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

(可选)使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

continueOnError false 可选 设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 true,即使在政策失败后,仍可以继续执行流。另请参阅:
enabled true 可选 设置为 true 可实施政策。 设为 false 可关闭政策。即使政策仍附加到某个流,也不会强制执行该政策。
async   false 已弃用 此属性已弃用。

Esempi

Gli esempi seguenti mostrano alcuni dei modi in cui puoi utilizzare il criterio MessageValidation:

1: Convalida XSD

Puoi utilizzare il criterio di convalida dei messaggi per convalidare il payload di una richiesta di messaggio XML in base a uno schema XSD.

  1. Crea un nuovo file di risorse XSD. Ad esempio: note-schema.xsd:
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <xs:element name="note">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="to" type="xs:string"/>
            <xs:element name="from" type="xs:string"/>
            <xs:element name="heading" type="xs:string"/>
            <xs:element name="body" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  2. Aggiungi il criterio di convalida dei messaggi SOAP al pre-flow dell'endpoint proxy:
    1. Specifica la posizione del file di risorse XSD con l'elemento <ResourceURL>. Ad esempio:
      ...
        <ResourceURL>xsd://note-schema.xsd</ResourceURL>
      ...
    2. Rimuovi gli elementi <SOAPMessage> e <Element> dalla definizione della policy.

    La definizione del criterio dovrebbe essere simile alla seguente:

    <MessageValidation continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My XML Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <ResourceURL>xsd://note-schema.xsd</ResourceURL>
    </MessageValidation>
  3. Invia una richiesta POST al proxy API con il tuo XML come payload del messaggio, come mostrato nell'esempio seguente:
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      -d '<note>
      <to>Fred Rogers</to>
      <from>Nick Danger</from>
      <heading>Greetings from my neighborhood</heading>
      <body>Just writing to say hello.</body>
    </note>'

    Nota che l'intestazione Content-type è impostata su application/xml.

    Puoi anche creare un file di dati per il payload e farvi riferimento con un comando simile al seguente:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/note-payload.xml'

Dovresti ricevere una risposta HTTP 200. A seconda dell'endpoint di destinazione, potresti ricevere ulteriori dettagli sulla richiesta. Ad esempio, se utilizzi http://httpbin.org/post come endpoint di destinazione e specifichi l'output -v (dettagliato), la risposta dovrebbe essere simile alla seguente:

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

Per verificare che la convalida XSD funzioni, prova a inserire un altro tag nel corpo della richiesta. Ad esempio:

curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
  -d '<note>
  <to>Fred Rogers</to>
  <from>Nick Danger</from>
  <heading>Greetings from my neighborhood</heading>
  <body>Just writing to say hello.</body>
  <badTag>Not good</badTag>
</note>'

Dovresti ricevere un errore di convalida.

2: Convalida SOAP

Puoi utilizzare il criterio di convalida dei messaggi per convalidare il payload di una richiesta di messaggio SOAP rispetto a un WSDL.

  1. Crea un nuovo file di risorse WSDL. Ad esempio, "example-wsdl.wsdl":
  2. Aggiungi il criterio di convalida del messaggio SOAP al pre-flow dell'endpoint proxy:
    1. Imposta l'attributo version dell'elemento <SOAPMessage> sulla versione del protocollo SOAP rispetto alla quale vuoi eseguire la convalida. Ad esempio, "1.1":
      ...
        <SOAPMessage version="1.1"/>
      ...
    2. Imposta il valore dell'elemento <Element> sull'elemento che vuoi convalidare:
      ...
        <Element namespace="https://example.com/gateway">getID</Element>
      ...

      <Element> specifica il primo elemento secondario dell'elemento <Body> nel corpo della richiesta SOAP.

      Imposta l'attributo namespace sullo spazio dei nomi del bambino.

    3. Specifica la posizione del file di risorse WSDL con l'elemento <ResourceURL>. Ad esempio:
      ...
        <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
      ...

    La definizione del criterio dovrebbe essere simile alla seguente:

    <MessageValidation continueOnError="false"
        enabled="true" name="validateSOAPRequest">
      <DisplayName>My SOAP Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <SOAPMessage version="1.1"/>
      <Element namespace="https://example.com/gateway">getID</Element>
      <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
    </MessageValidation>
  3. Invia una richiesta POST al proxy API con la busta SOAP come payload del messaggio, come mostrato nell'esempio seguente:
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:prox="https://example.com/gateway" xmlns:typ="https://example.com/gateway/types">
      <soapenv:Header/>
      <soapenv:Body>
        <prox:getID>
          <typ:MyType>
            <typ:ID>42</typ:ID>
          </typ:MyType>
        </prox:getID>
      </soapenv:Body>
    </soapenv:Envelope>'

    Tieni presente che l'intestazione Content-type è impostata su "application/xml".

    Puoi anche creare un file di dati per il payload e farvi riferimento con un comando simile al seguente:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/soap-payload.xml'

Dovresti ricevere una risposta HTTP 200. A seconda dell'endpoint di destinazione, potresti ricevere ulteriori dettagli sulla richiesta. Ad esempio, se utilizzi http://httpbin.org/post come endpoint di destinazione, la risposta dovrebbe essere simile alla seguente:

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

3: XML/JSON ben formato

Puoi utilizzare il criterio di convalida dei messaggi per verificare che il payload di un messaggio JSON o XML sia ben formato (non è la stessa cosa della convalida). Le norme garantiscono che la struttura e i contenuti soddisfino gli standard accettati, tra cui:

  • Esiste un solo elemento principale
  • Non sono presenti caratteri non ammessi nei contenuti
  • Gli oggetti e i tag sono nidificati correttamente
  • I tag di inizio e di fine corrispondono

Per verificare la presenza di un payload XML o JSON ben formato:

  1. Aggiungi il criterio di convalida del messaggio SOAP al pre-flow dell'endpoint proxy.
  2. Rimuovi gli elementi <ResourceURL>, <SOAPMessage> e <Element> dalla definizione della policy.

    La definizione del criterio dovrebbe essere simile alla seguente:

    <MessageValidation async="false" continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My JSON Checker</DisplayName>
      <Properties/>
      <Source>request</Source>
    </MessageValidation>
  3. Invia una richiesta POST al proxy API, come mostrato nell'esempio seguente:
    curl -v -X POST -H 'Content-Type: application/json' http://my-test.apigee.net/v1/xsd-mock
      -d '{
    "note": {
      "to": "Fred Rogers",
      "from": "Nick Danger",
      "header": "Greetings from my neighborhood",
      "body": "Just writing to say hello."
      }
    }'

    Nota che l'intestazione Content-type è impostata su application/json.

    Per controllare la validità di un file XML, utilizza XML come payload del messaggio e imposta Content-type su application/xml.

Dovresti ricevere una risposta HTTP 200. Quando invii un payload del messaggio che non contiene XML o JSON ben formattati, dovresti ricevere un errore steps.messagevalidation.Failed.

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <MessageValidation>.

<DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso e più naturale.

L'elemento <DisplayName> è comune a tutti i criteri.

Valore predefinito N/D
Obbligatorio? Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo Stringa
Elemento principale <PolicyElement>
Elementi secondari Nessuno

La sintassi dell'elemento <DisplayName> è la seguente:

Sintassi

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Esempio

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'elemento <DisplayName> non ha attributi o elementi secondari.

<Element>

Specifica l'elemento del messaggio da convalidare. Questo è il primo elemento secondario dell'elemento <Body> nell'envelope della richiesta SOAP.

Valore predefinito sampleObject
Obbligatorio? Facoltativo
Tipo Stringa
Elemento principale <MessageValidation>
Elementi secondari Nessuno

L'elemento <Element> utilizza la seguente sintassi:

Sintassi

...
  <Element namespace="element_namespace">element_to_validate</Element>
...

Esempio 1

L'esempio seguente definisce un singolo elemento da convalidare:

...
<Element namespace="https://example.com/gateway">getID</Element>
...

Esempio 2

Puoi specificare più di un elemento da convalidare aggiungendo più elementi <Element>:

...
<Element namespace="https://example.com/gateway">getID</Element>
<Element namespace="https://example.com/gateway">getDetails</Element>
...

L'elemento <Element> prevede i seguenti attributi:

Attributo Predefinito Obbligatorio? Descrizione
namespace "http://sample.com" Facoltativo Definisce lo spazio dei nomi dell'elemento da convalidare.

<ResourceURL>

Identifica lo schema XSD o la definizione WSDL da utilizzare per convalidare il messaggio di origine.

Valore predefinito wsdl://display_name.wsdl
Obbligatorio? Facoltativo
Tipo Stringa
Elemento principale <MessageValidation>
Elementi secondari Nessuno

L'elemento <ResourceURL> utilizza la seguente sintassi:

Sintassi

...
  <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL>
...

Esempi

Per un file XML:

...
<ResourceURL>xsd://note-schema.xsd</ResourceURL>
...

Per un WSDL:

...
<ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
...

Il valore di <ResourceURL> deve indirizzare a un file di risorse nel proxy API. Non può fare riferimento a risorse esterne tramite HTTP o HTTPS.

Se non specifichi un valore per <ResourceURL>, il messaggio viene controllato per verificare che sia in formato JSON o XML valido se l'intestazione Content-type è application/json o application/xml, rispettivamente.

L'elemento <ResourceURL> non ha elementi secondari o attributi.

Utilizzo di XSD per la convalida

Se il payload XML che convalidi con il criterio MessageValidation fa riferimento a un altro schema, devi aggiungere il prefisso xsd al file XSD incluso nell'attributo schemaLocation.

Il seguente schema di esempio è composto da più XSD:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:include schemaLocation="xsd://note-schema.xsd"/>
  <xs:include schemaLocation="xsd://letter-schema.xsd"/>
  <xs:include schemaLocation="xsd://user-schema.xsd"/>
</xs:schema>

Utilizzo di WSDL per la convalida

Un WSDL deve definire almeno uno schema. Se non fa riferimento ad almeno uno schema, la policy MessageValidation non va a buon fine.

La profondità massima di importazione per uno schema è 10. Se superi questo numero di importazioni nidificate, la policy MessageValidation non viene superata.

<SOAPMessage>

Definisce la versione SOAP rispetto alla quale la policy MessageValidation esegue la convalida.

Valore predefinito n/a
Obbligatorio? Facoltativo
Tipo n/a
Elemento principale <MessageValidation>
Elementi secondari Nessuno

L'elemento <SOAPMessage> utilizza la seguente sintassi:

Sintassi

...
  <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
...

Esempio

...
<SOAPMessage version="1.1"/>
...

L'elemento <SOAPMessage> prevede i seguenti attributi:

Attributo Predefinito Obbligatorio? Descrizione
version Nessuno Facoltativo La versione SOAP utilizzata da questa policy per convalidare i messaggi SOAP.

I valori validi sono:

  • "1.1"
  • "1.2"
  • "1.1/1.2"

Per saperne di più, consulta Da SOAP/1.1 a SOAP versione 1.2 in 9 punti.

<Source>

Identifica il messaggio di origine da convalidare. Il valore di questo elemento è il nome del messaggio che vuoi convalidare.

Se non imposti <Source>, questo criterio viene impostato per impostazione predefinita su message, che si riferisce al messaggio di richiesta completo (in un flusso di richiesta) o al messaggio di risposta (in un flusso di risposta), incluso qualsiasi payload. Puoi anche impostarlo esplicitamente su request o response per fare riferimento alla richiesta o alla risposta.

Valore predefinito richiesta
Obbligatorio? Facoltativo
Tipo Stringa
Elemento principale <MessageValidation>
Elementi secondari Nessuno

L'elemento <Source> utilizza la seguente sintassi:

Sintassi

...
  <Source>message_to_validate</Source>
...

Esempio

...
<Source>request</Source>
...

Oltre a message, request e response, puoi impostare il valore di <Source> sul nome di qualsiasi messaggio nel flusso. Se lo fai, però, devi creare un messaggio personalizzato con quel nome nel flusso prima dell'esecuzione di queste norme. In caso contrario, riceverai un errore.

Se il valore di <Source> non può essere risolto nel flusso di messaggi o viene risolto in un tipo non di messaggio, si verifica una delle seguenti situazioni:

  • Se un valore è nullo, Apigee genera un errore steps.messagevalidation.SourceMessageNotAvailable.
  • Se un tipo non è un messaggio:Apigee genera un errore steps.messagevalidation.NonMessageVariable.

L'elemento <Source> non ha attributi o elementi secondari.

Codici di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.messagevalidation.SourceMessageNotAvailable 500

This error occurs if a variable specified in the <Source> element of the policy is either:

  • out of scope (not available in the specific flow where the policy is being executed)
  • or
  • can't be resolved (is not defined)
steps.messagevalidation.NonMessageVariable 500

This error occurs if the <Source> element in the SOAPMessageValidation policy is set to a variable which is not of type message.

Message type variables represent entire HTTP requests and responses. The built-in Apigee flow variables request, response, and message are of type message. To learn more about message variables, see the Variables reference.

steps.messagevalidation.Failed 500 This error occurs if the SOAPMessageValidation policy fails to validate the input message payload against the XSD schema or WSDL definition. It will also occur if there is malformed JSON or XML in the payload message.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidResourceType The <ResourceURL> element in the SOAPMessageValidation policy is set to a resource type not supported by the policy.
ResourceCompileFailed The resource script referenced in the <ResourceURL> element of the SOAPMessageValidation policy contains an error that prevents it from compiling.
RootElementNameUnspecified The <Element> element in the SOAPMessageValidation policy does not contain the root element's name.
InvalidRootElementName The <Element> element in the SOAPMessageValidation policy contains a root element name that does not adhere to XML rules for valid element naming.

Schemi

Ogni tipo di policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle policy sono disponibili su GitHub.

Argomenti correlati