Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Il criterio SOAPMessageValidation esegue le seguenti operazioni:
- Convalida qualsiasi messaggio XML in base agli schemi XSD
- Convalida i messaggi SOAP in base a una definizione WSDL
- Determina la correttezza dei messaggi JSON e XML
Sebbene il nome di questo criterio nell'interfaccia utente sia SOAPMessageValidation, il criterio convalida più di quanto non facciano i messaggi SOAP. In questa sezione, il criterio viene chiamato criterio di convalida dei messaggi.
Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla loro disponibilità in base a ciascun tipo di ambiente, consulta Tipi di criteri.
Elemento <MessageValidation>
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
La sintassi dell'elemento <MessageValidation>
è la seguente:
<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 di convalida dei messaggi al flusso nell'interfaccia utente 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/D | Obbligatorio |
Il nome interno del criterio. Il valore dell'attributo Se vuoi, utilizza l'elemento |
continueOnError |
falso | Facoltativo | Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del 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 | Ritirato | Questo attributo è stato ritirato. |
Esempi
Gli esempi riportati di seguito 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.
- 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 di convalida dei messaggi SOAP al pre-flusso dell'endpoint proxy:
- Specifica la posizione del file della risorsa 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 del criterio 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 della risorsa XSD con l'elemento
- 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>'
Tieni presente 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 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.
- Crea un nuovo file di risorse WSDL. Ad esempio, "example-wsdl.wsdl":
- Aggiungi il criterio di convalida dei messaggi SOAP al pre-flusso dell'endpoint proxy:
- 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"/> ...
- Imposta il valore dell'elemento
<Element>
sull'elemento da convalidare:... <Element namespace="https://example.com/gateway">getID</Element> ...
<Element>
specifica il primo elemento secondario dell'elemento<Body>
nell'involucro della richiesta SOAP.Imposta l'attributo
namespace
sullo spazio dei nomi per l'elemento secondario. - Specifica la posizione del file della risorsa WSDL con l'elemento
<ResourceURL>
. Ad esempio:... <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL> ...
La definizione del criterio 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 l'involucro 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 formato correttamente (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
- I contenuti non contengono caratteri non ammessi
- Gli oggetti e i tag sono nidificati correttamente
- Corrispondenza dei tag di inizio e di fine
Per verificare la presenza di un payload XML o JSON ben formato:
- Aggiungi il criterio di convalida dei messaggi SOAP al pre-flow dell'endpoint proxy.
- Rimuovi gli elementi
<ResourceURL>
,<SOAPMessage>
e<Element>
dalla definizione delle norme.La definizione del criterio 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." } }'
Tieni presente che l'intestazione
Content-type
è impostata suapplication/json
.Per verificare la correttezza di un file XML, utilizza XML come payload del messaggio e imposta
Content-type
suapplication/xml
.
Dovresti ricevere una risposta HTTP 200
. Quando invii un payload del messaggio
che non contiene XML o JSON ben formattato, dovresti ricevere un
messaggio di 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. Si tratta del primo elemento secondario dell'elemento <Body>
nell'involucro della richiesta SOAP.
Valore predefinito | sampleObject |
Obbligatorio? | Facoltativo |
Tipo | Stringa |
Elemento principale |
<MessageValidation>
|
Elementi secondari | Nessuno |
La sintassi dell'elemento <Element>
è la seguente:
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 |
La sintassi dell'elemento <ResourceURL>
è la seguente:
Sintassi
... <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL> ...
Esempi
Per un file XML:
... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
Per un file 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>
, viene controllato che il messaggio sia JSON o XML ben formato se l'intestazione Content-type
è application/json
o application/xml
.
L'elemento <ResourceURL>
non ha elementi secondari o attributi.
Utilizzo degli XSD per la convalida
Se il payload XML convalidato con il criterio di convalida dei messaggi fa riferimento
a un altro schema, devi anteporre al file XSD incluso il prefisso xsd
nell'attributo
schemaLocation
.
Lo schema di esempio riportato di seguito è costituito da più file 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 dei file WSDL per la convalida
Un file WSDL deve definire almeno uno schema. Se non fa riferimento ad almeno uno schema, il criterio MessageValidation non va a buon fine.
La profondità massima di importazione per uno schema è 10. Se superi questo numero di importazioni nidificate, il criterio di convalida dei messaggi non va a buon fine.
<SOAPMessage>
Definisce la versione SOAP rispetto alla quale viene convalidato il criterio MessageValidation.
Valore predefinito | n/a |
Obbligatorio? | Facoltativo |
Tipo | n/a |
Elemento principale |
<MessageValidation>
|
Elementi secondari | Nessuno |
La sintassi dell'elemento <SOAPMessage>
è la seguente:
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 questo criterio per convalidare i messaggi SOAP.
I valori validi sono:
|
Per ulteriori 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 da convalidare.
Se non imposti <Source>
, questo criterio assume per impostazione predefinita il valore 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 |
La sintassi dell'elemento <Source>
è la seguente:
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. Tuttavia, se lo fai, devi creare un messaggio personalizzato con quel nome nel flusso prima che venga eseguita questa norma. In caso contrario, riceverai un messaggio di errore.
Se il valore di <Source>
non può essere risolto nel flusso di messaggi o si risolve in un tipo diverso da messaggio, si verifica una delle seguenti condizioni:
- Se un valore nullo: Apigee genera un
errore
steps.messagevalidation.SourceMessageNotAvailable
. - Se il 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 di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi durante l'esecuzione del criterio.
Codice guasto | 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 di 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 del messaggio di input in base allo schema XSD o alla definizione WSDL. Si verifica anche se nel messaggio del payload è presente JSON o XML con formato errato. | build |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome dell'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 si fa 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 rispetta le regole XML per la denominazione degli elementi validi. |
build |
Schemi
Ogni tipo di norma è definito da uno schema XML (.xsd
). Come riferimento, gli schemi delle norme sono disponibili su GitHub.
Argomenti correlati
- Criteri di protezione dalle minacce XML
- Criteri XML to JSON
- Criteri JSON to XML
- Criteri di protezione dalle minacce in formato JSON