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.

Percorso 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

URL di accesso per aree geografiche 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 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 messaggio

Lo stile documento/letterale 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 specificati 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 passare le credenziali di autenticazione nelle richieste API consiste nell'utilizzare l'elemento authHeader come definito nel 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

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

Di seguito è riportato un esempio di utilizzo dell'elemento authHeader in un'intestazione SOAP di 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 è in grado di trasmettere l'intestazione SOAP authHeader, le richieste API possono specificare anche 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 Base64 standard, <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 il codice di stato 401 (Unauthorized). Viene invece restituito un codice di stato 500 (Internal Server Error) con un corpo di errore SOAP che indica che la richiesta non può essere autenticata.

Prima di IPS 3.8, l'autenticazione tramite l'intestazione SOAP è stata implementata utilizzando gli elementi AuthUser e AuthPassword 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 dell'elemento authHeader.

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'operazione addCompany completa, 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 la richiesta addCompany precedente, 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>