Questa pagina si applica a Apigee e Apigee ibrido.
Visualizza la documentazione di
Apigee Edge.
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
Sebbene il nome di questo criterio nella UI sia SOAPMessageValidation, il criterio convalida più dei semplici messaggi SOAP. In questa sezione si fa riferimento ai criteri come criteri di MessageValidation.
Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutti gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità di ciascun tipo di ambiente, consulta Tipi di criteri.
<MessageValidation>
elemento
Definisce il criterio MessageValidation.
Valore predefinito | Consulta la scheda Criterio predefinito 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>
Criterio predefinito
L'esempio seguente mostra le impostazioni predefinite quando aggiungi un criterio MessageValidation al tuo flusso nella UI di 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>
Questo elemento ha i seguenti attributi comuni a tutti i criteri:
Attributo | Predefinito | Obbligatorio? | Descrizione |
---|---|---|---|
name |
N/A | Obbligatorio |
Il nome interno del criterio. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
continueOnError |
falso | Facoltativo | Imposta su false per restituire un errore in caso di errore del criterio. Questo è un comportamento previsto per
la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un errore nel criterio. Vedi anche:
|
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 |
falso | Deprecato | Questo attributo è stato ritirato. |
Esempi
I seguenti esempi mostrano alcuni modi in cui puoi utilizzare il criterio MessageValidation:
1: Convalida XSD
Puoi utilizzare il criterio Message Validation per convalidare il payload di una richiesta di messaggi XML a fronte di uno schema XSD.
- 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>
- Aggiungi il criterio SOAP Message Validation al pre-flusso dell'endpoint proxy:
- Specifica la posizione del file di risorse XSD con l'elemento
<ResourceURL>
. Ad esempio:... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
- Rimuovi gli elementi
<SOAPMessage>
e<Element>
dalla definizione del criterio.
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>
- Specifica la posizione del file di risorse XSD con l'elemento
- Invia una richiesta
POST
al proxy API con il tuo XML come payload dei messaggi, come mostra l'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 suapplication/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 dettagli aggiuntivi sulla richiesta. Ad esempio, se utilizzi
http://httpbin.org/post
come endpoint di destinazione e specifichi un 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 messaggi SOAP rispetto a un WSDL.
- Crea un nuovo file di risorse WSDL. Ad esempio, "example-wsdl.wsdl":
- Aggiungi il criterio SOAP Message Validation al pre-flusso dell'endpoint proxy:
- Imposta l'attributo
version
dell'elemento<SOAPMessage>
sulla versione del protocollo SOAP da utilizzare per la convalida. Ad esempio, "1,1":... <SOAPMessage version="1.1"/> ...
- Imposta il valore dell'elemento
<Element>
sull'elemento che vuoi convalidare:... <Element namespace="https://example.com/gateway">getID</Element> ...
<Element>
specifica il primo elemento figlio sotto l'elemento<Body>
nella busta della richiesta SOAP.Imposta l'attributo
namespace
sullo spazio dei nomi dell'asset secondario. - Specifica la posizione del file di risorse WSDL con l'elemento
<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>
- Imposta l'attributo
- Invia una richiesta
POST
al proxy API con la busta SOAP come payload, come mostra l'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 dettagli aggiuntivi 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 formulati correttamente
Puoi utilizzare il criterio di convalida dei messaggi per confermare che un payload di messaggio JSON o XML sia in un formato corretto (non equivale alla convalida). Il criterio garantisce che la struttura e i contenuti soddisfino gli standard accettati, tra cui:
- C'è 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:
- Aggiungi il criterio SOAP Message Validation al pre-flusso dell'endpoint proxy.
- Rimuovi gli elementi
<ResourceURL>
,<SOAPMessage>
e<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>
- 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 suapplication/json
.Per verificare la correttezza del formato di un file XML, utilizza XML come payload dei messaggi e imposta
Content-type
suapplication/xml
.
Dovresti ricevere una risposta HTTP 200
. Quando invii un payload dei messaggi che non contiene XML o JSON con formato corretto, dovresti ricevere un errore steps.messagevalidation.Failed
.
Riferimento elemento secondario
In questa sezione vengono descritti gli elementi secondari di <MessageValidation>
.
<DisplayName>
Utilizzalo in aggiunta 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/A |
Obbligatorio? | Facoltativo. Se ometti <DisplayName> , viene utilizzato il valore dell'attributo name del criterio. |
Tipo | Stringa |
Elemento principale | <PolicyElement> |
Elementi secondari | Nessuna esperienza |
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 nel messaggio da convalidare. Questo è il primo asset secondario sotto l'elemento <Body>
nella busta della richiesta SOAP.
Valore predefinito | sampleObject |
Obbligatorio? | Facoltativo |
Tipo | String |
Elemento principale |
<MessageValidation>
|
Elementi secondari | Nessuna |
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>
ha i seguenti attributi:
Attributo | Predefinita | 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 | String |
Elemento principale |
<MessageValidation>
|
Elementi secondari | Nessuna |
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 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 la presenza di JSON o XML correttamente se l'intestazione Content-type
è rispettivamente application/json
o application/xml
.
L'elemento <ResourceURL>
non ha elementi o attributi secondari.
Utilizzo di XSD per la convalida
Se il payload XML che convalidi con il criterio MessageValidation fa riferimento a un altro schema, devi aggiungere xsd
all'attributo schemaLocation
prima del file XSD incluso.
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 MessageValidation non va a buon fine.
La profondità di importazione massima per uno schema è 10. Se superi il numero di importazioni nidificate, il criterio MessageValidation avrà esito negativo.
<SOAPMessage>
Definisce la versione SOAP in base alla quale viene convalidato il criterio MessageValidation.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo |
Tipo | n/a |
Elemento principale |
<MessageValidation>
|
Elementi secondari | Nessuna |
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 | Predefinita | Obbligatorio? | Descrizione |
---|---|---|---|
version |
Nessuna | Facoltativo | La versione SOAP utilizzata da questo criterio per convalidare i messaggi SOAP.
I valori validi sono:
|
Per maggiori informazioni, 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>
, il criterio predefinito è 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 l'eventuale payload. Puoi anche impostarlo esplicitamente su request
o response
per fare riferimento alla richiesta o
alla risposta.
Valore predefinito | request |
Obbligatorio? | Facoltativo |
Tipo | String |
Elemento principale |
<MessageValidation>
|
Elementi secondari | Nessuna |
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. In questo caso, però, devi creare un messaggio personalizzato con questo nome nel flusso prima che venga eseguito questo criterio. In caso contrario, verrà visualizzato un errore.
Se il valore <Source>
non può essere risolto nel flusso di messaggi o si risolve in un tipo non messaggio, si verifica una delle seguenti situazioni:
- Se un valore nullo:Apigee restituisce 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
Questa sezione descrive i codici e i messaggi di errore che vengono restituiti e le variabili di errore impostate da Apigee 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
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
Questo errore si verifica se l'elemento Le variabili del tipo di messaggio rappresentano intere richieste e risposte HTTP. Le variabili di flusso Apigee integrate |
build |
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. | build |
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.
|
build |
ResourceCompileFailed |
Lo script della risorsa a cui viene fatto riferimento nell'elemento <ResourceURL> del criterio SOAPMessageValidation contiene un errore che ne impedisce la compilazione.
|
build |
RootElementNameUnspecified |
L'elemento <Element> nel criterio SOAPMessageValidation non contiene il nome
dell'elemento principale. |
build |
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. |
build |
Schema
Ogni tipo di criterio è definito da uno schema XML (.xsd
). Come riferimento, su GitHub sono disponibili gli schemi dei criteri.
Argomenti correlati
- Criteri di XML Threat Protection
- Criterio da XML a JSON
- Criteri da JSON a XML
- Criteri di protezione dalle minacce per JSON