IPS Web Service WSDL-Versionen ips-web-service-wsdl-versions

Der IPS-Webdienst wird von einer Reihe von WSDL-Dokumenten (Web Services Description Language) unterstützt, auf die von jeder IPS-Installation zugegriffen wird, auf der die IPS-Webdienstkomponente installiert ist. Jede IPS-API-Version enthält eine neue WSDL-Datei, die auf einen versionierten Ziel-XML-Namespace verweist. Frühere WSDL-Namespace-Versionen werden ebenfalls unterstützt, um Abwärtskompatibilität mit bestehenden Anwendungen zu ermöglichen.

WSDL-Zugriff section-62e69fa2c87f4dc9bca72f10ba028f6c

Greifen Sie auf die Scene7-WSDLs zu, wie unten dargestellt.

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

Der Standardwert für <IPS_webapp> ist scene7.

Dienstspeicherort

Die Dienst-URL wird im Dienstabschnitt des IPS Web Service-WSDL-Dokuments angegeben. Die Dienst-URL ist im Allgemeinen wie folgt:

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

Zugreifen auf URLs für Dynamic Media-Regionen

Unterstützte WSDLs section-ebbba69880f94e9c823f1147974eb404

Denken Sie daran, dass Sie möglicherweise Ihren Code ändern müssen, wenn Sie Funktionen in der neuesten Version der IPS-API verwenden möchten. Die IPS-API unterstützt WSDLs für die folgenden Versionen:

Bestehende Anwendungen, die geändert werden müssen, um neue Funktionen zu verwenden, müssen auf die neueste API-Version aktualisieren und müssen möglicherweise Änderungen an vorhandenem Code vornehmen. Weitere Informationen finden Sie im Änderungsprotokoll .

SOAP section-51e7ecbd1d7f451b9e4f6bf7e1579cae

Bindungen

Der IPS-API-Webdienst unterstützt nur eine SOAP Bindung.

Unterstützte Transporte

Die IPS-API-SOAP-Bindung unterstützt nur den HTTP-Transport. Stellen Sie alle SOAP Anfragen mithilfe der HTTPS-POST-Methode.

SOAP Aktionsheader

Um eine Anfrage zu verarbeiten, setzen Sie den SOAPAction-HTTP-Header auf den Namen des angeforderten Vorgangs. Das Vorgangsnamenattribut im WSDL-Bindungsabschnitt gibt den Namen an.

Nachrichtenformat

Der Dokument-/Literalstil wird für alle Eingabe- und Ausgabemeldungen mit Typen verwendet, die auf der XML-Schemadefinitionssprache ( https://www.w3.org/TR/xmlschema-0/) basieren und in der WSDL-Datei angegeben sind. Für alle Typen sind qualifizierte Namen erforderlich, die den in der WSDL-Datei angegebenen Zielnamespace-Wert verwenden.

Authentifizierung anfordern

Die bevorzugte Methode zur Übergabe von Authentifizierungsberechtigungen in API-Anfragen besteht darin, das Element authHeader zu verwenden, wie in der IPS-API-WSDL definiert.

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

Felder

Das Element authHeader wird unabhängig von der API-Version immer im Namespace http://www.scene7.com/IpsApi/xsd definiert.

Im Folgenden finden Sie ein Beispiel für die Verwendung des Elements authHeader in einer Anfrage-SOAP-Kopfzeile:

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

Andere Anfrageauthentifizierungsmethoden

Wenn es aus irgendeinem Grund nicht möglich ist, dass Ihre Client-Anwendung den SOAP-Header authHeader übergibt, können API-Anfragen auch Anmeldeinformationen mithilfe der HTTP Basic-Authentifizierung angeben (wie in RFC 2617 angegeben).

Für die HTTP Basic-Authentifizierung muss der HTTP-Header-Abschnitt jeder SOAP POST-Anfrage einen Header des Formulars enthalten:

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

Wobei base64() die standardmäßige Base64-Kodierung anwendet, ist <IPS_user_email> die E-Mail-Adresse eines gültigen IPS-Benutzers und <password> das Kennwort des Benutzers.

Senden Sie die Autorisierungs-Kopfzeile mit der ersten Anfrage vorab. Wenn keine Authentifizierungsberechtigungen in der Anfrage enthalten sind, antwortet IpsApiService nicht mit dem Statuscode 401 (Unauthorized). Stattdessen wird ein Statuscode von 500 (Internal Server Error) mit einem SOAP Fehlertext zurückgegeben, der angibt, dass die Anfrage nicht authentifiziert werden konnte.

Vor IPS 3.8 wurde die Authentifizierung über SOAP Kopfzeile mit den Elementen AuthUser und AuthPassword im Namespace http://www.scene7.com/IpsApi implementiert. Beispiel:

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

Dieser Stil wird weiterhin aus Gründen der Abwärtskompatibilität unterstützt, wird jedoch nicht mehr zugunsten des Elements authHeader unterstützt.

Autorisierung anfordern

Nachdem die Anmeldeinformationen des Anrufers authentifiziert wurden, wird die Anfrage überprüft, um sicherzustellen, dass der Anrufer zur Durchführung des angeforderten Vorgangs berechtigt ist. Die Autorisierung basiert auf der Benutzerrolle des Aufrufers und erfordert möglicherweise auch die Überprüfung des Zielunternehmens, des Zielbenutzers und anderer Vorgangsparameter. Darüber hinaus müssen Image Portal-Benutzer zu einer Gruppe gehören, die über die erforderlichen Berechtigungen zum Ausführen bestimmter Ordner- und Asset-Vorgänge verfügt. Im Abschnitt "Vorgangsreferenz"werden die Autorisierungsanforderungen für jeden Vorgang beschrieben.

SOAP-Beispielanfrage und -Antwort

Das folgende Beispiel zeigt einen vollständigen addCompany -Vorgang, einschließlich HTTP-Headern:

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>

Und die entsprechende Antwort:

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>

SOAP faults

Wenn bei einem Vorgang eine Ausnahmebedingung auftritt, wird anstelle der normalen Antwort ein SOAP Fehler als Textkörper der SOAP zurückgegeben. Wenn beispielsweise ein Benutzer ohne Administratorrechte versucht, die vorherige addCompany -Anfrage zu senden, wird die folgende Antwort zurückgegeben:

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>