WSDL-Versionen des IPS-Webdienstes
Erstellt für:
- Entwickler
- Admin
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 die Abwärtskompatibilität mit vorhandenen Anwendungen zu ermöglichen.
WSDL-Zugriff
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.
Service-Speicherort
Die Service-URL wird im Abschnitt Service des WSDL-Dokuments des IPS-Webservices angegeben. Die Service-URL hat im Allgemeinen folgende Form:
https://<IPS_hostname>:<IPS_port>/<IPS_webapp>/
services/IpsApiService
Zugriff auf URLs für Dynamic Media-Regionen
Unterstützte WSDLs
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 am vorhandenen Code vornehmen. Einzelheiten finden Sie im Änderungsprotokoll .
SOAP
Bindungen
Der IPS-API-Webservice unterstützt nur eine SOAP-Bindung.
Unterstützte Transporte
Die SOAP-Bindung der IPS-API unterstützt nur den HTTP-Transport. Stellen Sie alle SOAP-Anfragen mithilfe der HTTPS-POST-Methode.
SOAP-Aktionskopfzeile
Um eine Anfrage zu verarbeiten, legen Sie den SOAPAction-HTTP-Header auf den Namen des angeforderten Vorgangs fest. Das Attribut „Vorgangsname“ im Abschnitt „WSDL-Bindung“ 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 Namespace-Zielwert verwenden.
Authentifizierung anfordern
Die bevorzugte Methode zum Übergeben von Authentifizierungsdaten in API-Anfragen besteht darin, das authHeader-Element zu verwenden, wie es in der IPS-API-WSDL definiert ist.
<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 authHeader-Element 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 authHeader-Elements in einem Anfrage-SOAP-Header:
<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 Authentifizierungsmethoden für Anfragen
Wenn es aus irgendeinem Grund für Ihre Client-Anwendung nicht möglich ist, den authHeader-SOAP-Header zu übergeben, können API-Anfragen auch Anmeldeinformationen mithilfe der HTTP-Standardauthentifizierung angeben (wie in RFC 2617 angegeben).
Für die HTTP-Standardauthentifizierung muss der HTTP-Header-Abschnitt jeder SOAP-POST-Anfrage eine Kopfzeile des Formulars enthalten:
Authorization: Basic base64(<IPS_user_email>:<password>)
Wenn base64() die standardmäßige Base64-Codierung 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 präventiv mit der ursprünglichen Anfrage. Wenn in der Anfrage keine Authentifizierungs-Anmeldeinformationen enthalten sind, antwortet IpsApiService nicht mit dem Status-Code 401 (Unauthorized). Stattdessen wird ein Status-Code 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 den SOAP-Header mithilfe der 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 aus Gründen der Abwärtskompatibilität weiterhin unterstützt, wurde jedoch zugunsten des authHeader Elements eingestellt.
Autorisierung anfordern
Nachdem die Anmeldeinformationen des Aufrufers authentifiziert wurden, wird die Anfrage überprüft, um sicherzustellen, dass der Aufrufer berechtigt ist, den angeforderten Vorgang auszuführen. Die Autorisierung basiert auf der Benutzerrolle der Aufrufenden und erfordert möglicherweise auch die Überprüfung des Zielunternehmens, des Zielbenutzers und anderer Vorgangsparameter. Darüber hinaus müssen Image Portal-Benutzer einer Gruppe mit den erforderlichen Berechtigungen angehören, um bestimmte Ordner- und Asset-Vorgänge auszuführen. Im Abschnitt Operations Reference werden die Autorisierungsanforderungen für jeden Vorgang beschrieben.
Beispiel für SOAP-Anfrage und -Antwort
Das folgende Beispiel zeigt einen vollständigen addCompany einschließlich HTTP-Kopfzeilen:
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-Fehler
Wenn bei einem Vorgang eine Ausnahmebedingung auftritt, wird anstelle der normalen -Antwort ein SOAP-Fehler als Text der SOAP-Nachricht 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>