Criterio di SOAPMessageValidation

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Il criterio SOAPMessageValidation comporta le seguenti operazioni:

  • Convalida qualsiasi messaggio XML in base agli schemi XSD
  • Convalida i messaggi SOAP in base a una definizione WSDL
  • Determina la corretta formattazione dei messaggi JSON e XML
di Gemini Advanced.

Mentre il nome di questo criterio nella UI è "SOAP Message Validation", il criterio convalida ulteriormente che semplici messaggi SOAP. Questa sezione fa riferimento al criterio come "Criterio di convalida dei messaggi".

<MessageValidation> elemento

Definisce il criterio di convalida dei messaggi.

Valore predefinito Consulta la scheda Criterio predefinito di seguito
Obbligatorio? Facoltativo
Tipo Oggetto complesso
Elemento principale n/d
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>

Criterio predefinito

L'esempio seguente mostra le impostazioni predefinite quando aggiungi un criterio di convalida dei messaggi al flusso nella UI di Edge:

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

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo Predefinita Obbligatorio? Description (Descrizione)
name N/A Obbligatorio

Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può contenere più di 255 caratteri.

Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor del proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError false Facoltativo Imposta su "false" per restituire un errore quando un criterio non va a buon fine. Si tratta di un comportamento previsto per la maggior parte dei criteri. Impostalo su "true" per far sì che l'esecuzione del flusso continui anche dopo l'esito negativo di un criterio.
enabled true Facoltativo Imposta su "true" per applicare il criterio. Imposta su "false" per "disattivare" il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.
async   false Deprecazione Questo attributo è obsoleto.

Esempi

I seguenti esempi mostrano alcuni modi in cui è possibile utilizzare Message Validation norme:

1: Convalida XSD

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

  1. Crea un nuovo file di risorse XSD. Per 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 SOAP Message Validation al pre-flusso del tuo endpoint proxy:
    1. Specifica la posizione del file di risorse XSD con <ResourceURL> . Ad esempio: 
      ...
  <ResourceURL>xsd://note-schema.xsd</ResourceURL>
...
    2. Rimuovi gli elementi <SOAPMessage> e <Element> da definizione delle norme.

    La definizione delle tue norme dovrebbe avere il seguente aspetto:

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

    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/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 specifica -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 la tua 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 usare il criterio Message Validation per convalidare il payload di richiesta di messaggi SOAP rispetto a un WSDL.

  1. Crea un nuovo file di risorse WSDL. Ad esempio, "example-wsdl.wsdl":
  2. Aggiungi il criterio SOAP Message Validation al pre-flusso del tuo endpoint proxy:
    1. Imposta l'attributo version dell'elemento <SOAPMessage> su del protocollo SOAP da utilizzare per la convalida. Ad esempio: "1,1": 
      ...
  <SOAPMessage version="1.1"/>
...
    2. Imposta il valore dell'elemento <Element> sull'elemento che vuoi convalida: 
      ...
  <Element namespace="https://example.com/gateway">getID</Element>
...

      <Element> specifica il primo elemento secondario dell'elemento <Body> nella busta della richiesta SOAP.

      Imposta l'attributo namespace sullo spazio dei nomi dell'asset secondario.

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

    La definizione delle tue norme dovrebbe avere il seguente aspetto:

    <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 dei messaggi, come illustrato 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 target, la risposta dovrebbe essere simile a:

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

Puoi utilizzare il criterio Message Validation per confermare che un messaggio JSON o XML payload sia nel formato corretto (non equivale alla convalida). Il criterio garantisce che la struttura e i contenuti soddisfino gli standard accettati, tra cui:

  • È presente un solo elemento radice
  • I contenuti non contengono caratteri illegali
  • Oggetti e tag sono nidificati correttamente
  • Corrispondenza dei tag di inizio e fine

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

  1. Aggiungi il criterio SOAP Message Validation al pre-flusso dell'endpoint proxy.
  2. Rimuovi <ResourceURL>, <SOAPMessage>, ed elementi <Element> dalla definizione del criterio.

    La definizione delle tue norme dovrebbe avere il seguente aspetto:

    <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."
  }
}'

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

    Per verificare il corretto formato di un file XML, utilizza XML come payload dei messaggi e imposta Content-type su "application/xml".

Dovresti ricevere una risposta HTTP 200. Quando invii un payload di messaggio che non contiene XML o JSON in formato corretto, dovresti ricevere steps.messagevalidation.Failed errore.

Riferimento elemento secondario

In questa sezione vengono descritti gli elementi secondari di <MessageValidation>.

<DisplayName>

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy UI 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>, il valore del valore viene utilizzato l'attributo name del criterio
Tipo Stringa
Elemento principale &lt;PolicyElement&gt;
Elementi secondari Nessuno

L'elemento <DisplayName> utilizza la seguente sintassi:

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 nel messaggio da convalidare. Questo è il primo figlio Elemento <Body> nella busta 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ù <Element> elementi:

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

L'elemento <Element> ha i seguenti attributi:

Attributo Predefinito Obbligatorio? Descrizione
namespace &quot;http://sample.com&quot; 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 puntare a una risorsa 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 non ci siano errori di formato JSON o XML se l'intestazione Content-type è "application/json" o "application/xml", rispettivamente.

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

Utilizzo di XSD per la convalida

Se il payload XML che convalidi con il criterio di convalida dei messaggi fa riferimento un altro schema, devi aggiungere xsd come prefisso al file XSD incluso 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, Il criterio di convalida dei messaggi ha esito negativo.

La profondità di importazione massima per uno schema è 10. Se superi questo numero di importazioni nidificate, Il criterio di convalida dei messaggi ha esito negativo.

<SOAPMessage>

Definisce la versione SOAP in base alla quale viene convalidato il criterio di convalida dei messaggi.

Valore predefinito n/d
Obbligatorio? Facoltativo
Tipo n/d
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> ha i seguenti attributi:

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

I valori validi sono:

  • "1,1"
  • "1,2"
  • "1,1/1,2"

Per ulteriori informazioni, vedi 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 messaggio da convalidare.

Se non imposti <Source>, questo criterio è impostato in modo predefinito su "messaggio", che si riferisce all'intera messaggio di richiesta (in un flusso di richiesta) o messaggio di risposta (in un flusso di risposta), inclusi eventuali per il payload. Puoi anche impostarlo esplicitamente su "request" o "risposta" fare riferimento alla richiesta o la risposta corretta.

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 "messaggio", "richiesta" e "risposta", puoi impostare il valore di <Source> al nome di qualsiasi messaggio nel tuo flusso. Se lo fai, però, devi creare un messaggio personalizzato con questo nome nel flusso prima dell'esecuzione di questo criterio. Altrimenti, otterrai un errore.

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

  • Se un valore nullo: Edge genera un Errore steps.messagevalidation.SourceMessageNotAvailable.
  • Se si tratta di un tipo che non è un messaggio:Edge genera un Errore steps.messagevalidation.NonMessageVariable.

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

Codici di errore

Gli errori restituiti dai criteri di Edge seguono un formato coerente, come descritto nella pagina Riferimento al codice di errore.

Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Codice di errore Stato HTTP Causa Correggi
steps.messagevalidation.SourceMessageNotAvailable 500

Questo errore si verifica se una variabile specificata nell'elemento <Source> del criterio è:

  • fuori ambito (non disponibile nel flusso specifico in cui viene eseguito il criterio)
    • o
  • non può essere risolto (non è definito)
steps.messagevalidation.NonMessageVariable 500

Questo errore si verifica se l'elemento <Source> nel criterio SOAPMessageValidation è impostato su una variabile non di tipo messaggio.

Le variabili del tipo di messaggio rappresentano intere richieste e risposte HTTP. Le variabili di flusso Edge integrate request, response e message sono di tipo messaggio. Per scoprire di più sulle variabili messaggio, consulta la documentazione di riferimento sulle variabili.
steps.messagevalidation.Failed 500 Questo errore si verifica se il criterio SOAPMessageValidation non riesce a convalidare il payload dei messaggi di input in base allo schema XSD o alla definizione WSDL. Si verifica anche se il formato JSON o XML del messaggio del payload è in formato errato.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Nome errore Causa Correggi
InvalidResourceType L'elemento <ResourceURL> nel criterio SOAPMessageValidation è impostato su un tipo di risorsa non supportato dal criterio.
ResourceCompileFailed Lo script della risorsa a cui viene fatto riferimento nell'elemento <ResourceURL> del criterio SOAPMessageValidation contiene un errore che ne impedisce la compilazione.
RootElementNameUnspecified L'elemento <Element> nel criterio SOAPMessageValidation non contiene il nome dell'elemento principale.
InvalidRootElementName L'elemento <Element> nel criterio SOAPMessageValidation contiene un nome dell'elemento principale che non ottempera alle regole XML per la denominazione di elementi validi.

Schemi

Ogni tipo di criterio è definito da uno schema XML (.xsd). Come riferimento, consulta gli schemi dei criteri sono disponibili su GitHub.

Argomenti correlati