Versioni WSDL servizio Web IPS ips-web-service-wsdl-versions

Il servizio Web IPS è supportato da un insieme di documenti WSDL (Web Services Description Language) a cui si accede da qualsiasi installazione IPS in cui è installato il componente Servizio Web IPS. Ogni versione API IPS include un nuovo file WSDL che fa riferimento a uno spazio dei nomi XML di destinazione con versione. Sono supportate anche le versioni precedenti dello spazio dei nomi WSDL per consentire la compatibilità con le applicazioni esistenti.

Accesso WSDL section-62e69fa2c87f4dc9bca72f10ba028f6c

Accedere ai file WSDL di Scene7 come illustrato di seguito.

https://<IPS_hostname:<IPS_port>/<IPS_webapp>/
webservice/IpsApi[-<API_version>].wsdl

Il valore predefinito per <IPS_webapp> è scene7.

Posizione del servizio

L'URL del servizio è specificato nella sezione del servizio del documento WSDL del servizio Web IPS. L’URL del servizio è generalmente nel formato:

https://<IPS_hostname>:<IPS_port>/<IPS_webapp>/
services/IpsApiService

Accedere agli URL per le aree geografiche di Dynamic Medie

WSDL supportati section-ebbba69880f94e9c823f1147974eb404

Ricorda che potrebbe essere necessario modificare il codice se desideri utilizzare le funzioni nell’ultima versione dell’API IPS. L'API IPS supporta WSDL per le seguenti versioni:

Le applicazioni esistenti che devono essere modificate per utilizzare le nuove funzioni devono eseguire l’aggiornamento alla versione API più recente e potrebbe essere necessario apportare modifiche al codice esistente. Per ulteriori informazioni, vedere il log delle modifiche.

SOAP section-51e7ecbd1d7f451b9e4f6bf7e1579cae

Associazioni

Il servizio Web API IPS supporta solo un'associazione SOAP.

Trasporti supportati

Il binding SOAP API IPS supporta solo il trasporto HTTP. Effettuare tutte le richieste SOAP utilizzando il metodo HTTPS POST.

Intestazione azione SOAP

Per elaborare una richiesta, impostare l'intestazione HTTP SOAPAction sul nome dell'operazione richiesta. L'attributo del nome dell'operazione nella sezione di associazione WSDL specifica il nome.

Formato del messaggio

Lo stile document/literal viene utilizzato per tutti i messaggi di input e output con tipi basati sul linguaggio di definizione dello schema XML ( https://www.w3.org/TR/xmlschema-0/) e specificate nel file WSDL. Tutti i tipi richiedono nomi qualificati che utilizzano il valore dello spazio dei nomi di destinazione specificato nel file WSDL.

Richiedi autenticazione

Il metodo preferito per trasmettere le credenziali di autenticazione nelle richieste API consiste nell’utilizzare authHeader come definito nel file WSDL API IPS.

<element name="authHeader">
    <complexType>
       <sequence>
            <element name="user" type="xsd:string"/>
            <element name="password" type="xsd:string"/>
            <element name="locale" type="xsd:string" minOccurs="0"/>
            <element name="appName" type="xsd:string" minOccurs="0"/>
            <element name="appVersion" type="xsd:string" minOccurs="0"/>
            <element name="gzipResponse" type="xsd:boolean" minOccurs="0"/>
            <element name="faultHttpStatusCode" type="xsd:int" minOccurs="0"/>
       </sequence>
    </complexType>
 </element>

Campi

Il authHeader è sempre definito nello spazio dei nomi http://www.scene7.com/IpsApi/xsd, indipendentemente dalla versione API.

Di seguito è riportato un esempio di utilizzo di authHeader elemento in un’intestazione SOAP della richiesta:

<soap:Header xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <authHeader xmlns="http://www.scene7.com/IpsApi/xsd">
      <user>user@scene7.com</user>
      <password>mypassword</password>
      <appName>MyApp</appName>
      <appVersion>1.0</appVersion>
   </authHeader>
 </soap:Header>

Altri metodi di autenticazione delle richieste

Se per qualche motivo l’applicazione client non può trasmettere il authHeader L’intestazione SOAP e le richieste API possono inoltre specificare le credenziali utilizzando l’autenticazione HTTP Basic (come specificato nella RFC 2617).

Per l’autenticazione HTTP Basic, la sezione dell’intestazione HTTP di ogni richiesta SOAP POST deve includere un’intestazione del modulo:

Authorization: Basic base64(<IPS_user_email>:<password>)

Dove base64() applica la codifica standard Base64, <IPS_user_email> è l'indirizzo e-mail di un utente IPS valido e <password> è la password dell'utente.

Invia preventivamente l’intestazione Autorizzazione con la richiesta iniziale. Se nella richiesta non sono incluse credenziali di autenticazione, IpsApiService non risponde con un codice di stato 401 (Unauthorized). Invece, un codice di stato di 500 (Internal Server Error) viene restituito un corpo dell'errore SOAP che indica che la richiesta non può essere autenticata.

Prima di IPS 3.8, l’autenticazione tramite l’intestazione SOAP era implementata utilizzando AuthUser e AuthPassword elementi nello spazio dei nomi http://www.scene7.com/IpsApi. Ad esempio:

<soap:Header xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <AuthUser xmlns="http://www.scene7.com/IpsApi">user@scene7.com</AuthUser>
   <AuthPassword xmlns="http://www.scene7.com/IpsApi">mypassword</AuthPassword>
</soap:Header>

Questo stile è ancora supportato per la compatibilità con le versioni precedenti, ma è stato dichiarato obsoleto a favore del authHeader elemento.

Richiedi autorizzazione

Dopo l'autenticazione delle credenziali del chiamante, la richiesta viene controllata per assicurarsi che il chiamante sia autorizzato a eseguire l'operazione richiesta. L'autorizzazione si basa sul ruolo utente del chiamante e può anche richiedere il controllo della società target, dell'utente target e di altri parametri operativi. Inoltre, gli utenti di Image Portal devono appartenere a un gruppo con le autorizzazioni necessarie per eseguire determinate operazioni su cartelle e risorse. La sezione Riferimento operazioni descrive i requisiti di autorizzazione per ciascuna operazione.

Richiesta e risposta SOAP di esempio

L’esempio seguente mostra un’ addCompany operazione, incluse le intestazioni HTTP:

POST /scene7/services/IpsApiService HTTP/1.1
User-Agent: Axis/2.0
SOAPAction: addCompany
Content-Type: text/xml; charset=UTF-8

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
      <authHeader xmlns="http://www.scene7.com/IpsApi/xsd">
        <user>user@scene7.com</user>
        <password>mypassword</password>
        <appName>MyApp</appName>
        <appVersion>1.0</appVersion>
      </authHeader>
    </soapenv:Header>
    <soapenv:Body>
    <ns1:addCompanyParam xmlns:ns1="http://www.scene7.com/IpsApi/xsd/2008-01-15">
      <ns1:companyName>Sample Company</ns1:companyName>
      <ns1:expires>2008-07-31T12:00:00-06:00</ns1:expires>
    </ns1:addCompanyParam>
    </soapenv:Body>
 </soapenv:Envelope>

E la risposta corrispondente:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 21 Jul 2006 20:47:55 GMT

<?xml version='1.0' encoding='utf-8'?><soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header />
   <soapenv:Body>
     <ns1:addCompanyReturn xmlns:ns1="http://www.scene7.com/IpsApi/xsd/2008-01-15">
       <ns1:companyInfo>
          <ns1:companyHandle>2</ns1:companyHandle>
          <ns1:name>Sample Company</ns1:name>
          <ns1:rootPath>SampleCompany/</ns1:rootPath>
          <ns1:expires>2008-07-31T18:00:00.000Z</ns1:expires>
       </ns1:companyInfo>
     </ns1:addCompanyReturn>
   </soapenv:Body>
</soapenv:Envelope>

Errori SOAP

Quando un'operazione rileva una condizione di eccezione, viene restituito un errore SOAP come corpo del messaggio SOAP al posto della risposta normale. Ad esempio, se un utente non amministratore tenta di inviare il precedente addCompany richiesta, viene restituita la seguente risposta:

HTTP/1.1 500 Internal Server Error
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 21 Jul 2006 16:36:20 GMT
Connection: close

<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header />
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode>soapenv:Client</faultcode>
         <faultstring>AuthorizationException</faultstring>
         <detail>
           <ns1:authorizationFault xmlns:ns1="http://www.scene7.com/IpsApi/xsd">
               <code xmlns="http://www.scene7.com/IpsApi/xsd">20003</code>
             <reason xmlns="http://www.scene7.com/IpsApi/xsd">User does not
             have permission to access operation 'addCompany'</reason>
           </ns1:authorizationFault>
         </detail>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>