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.
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>
is scene7
.
Dienstort
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
Zugriffs-URLs für Dynamic Media-Regionen
Geografischer Standort |
Produktions-URL |
Staging-URL (zur Entwicklung und zum Testen vor der Produktion) |
---|---|---|
Nordamerika |
https://s7sps1apissl.scene7.com/scene7/ |
https://s7sps1apissl-staging.scene7.com/scene7/ |
Europa, Naher Osten, Asien |
https://s7sps3apissl.scene7.com/scene7/ |
https://s7sps3apissl-staging.scene7.com/scene7/ |
Japan/Asien-Pazifik |
https://s7sps5apissl.scene7.com/scene7/ |
https://s7sps5apissl-staging.scene7.com/scene7/ |
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:
API-Versionsversion |
WSDL |
API-Namespace |
---|---|---|
6.8/2014R1 |
ipsApi-2014-04-03.wsdl |
http://www.scene7.com/IpsApi/xsd/2014-04-03 |
6.6/2013R1 |
ipsApi-2013-02-15.wsdl |
http://www.scene7.com/IpsApi/xsd/2013-02-15 |
6.0/2012R1 |
ipsApi-2012-02-14.wsdl |
http://www.scene7.com/IpsApi/xsd/2012-02-14 |
4.5 |
ipsApi-2010-01-31.wsdl |
http://www.scene7.com/IpsApi/xsd/2010-01-31 |
4.4 |
ipsApi-2009-07-31.wsdl |
http://www.scene7.com/IpsApi/xsd/2009-07-31 |
4.2 |
ipsApi-2008-09-10.wsdl |
http://www.scene7.com/IpsApi/xsd/2008-09-10 |
4.0 |
ipsApi-2008-01-15.wsdl |
http://www.scene7.com/IpsApi/xsd/2008-01-15 |
Vor 4.0 |
ipsApi.wsdl |
http://www.scene7.com/IpsApi/xsd |
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 .
Bindungen
Der IPS-API-Webdienst unterstützt nur eine SOAP-Bindung.
Unterstützte Transporte
Die SOAP-Bindung der IPS-API unterstützt nur den HTTP-Transport. Nehmen Sie alle SOAP-Anfragen mit der HTTPS-POST vor.
SOAP-Aktionskopfzeile
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/) und in der WSDL-Datei angegeben. 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, die authHeader
-Element, 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
Name |
Beschreibung |
---|---|
Benutzer |
Gültige IPS-Benutzer-E-Mail. |
Passwort |
Kennwort für das Benutzerkonto. |
locale |
Optionales Gebietsschema für die Anforderung. Siehe Gebietsschema für Details. |
appName |
Anwendungsname aufrufen. Dieser Parameter ist optional. Es wird jedoch empfohlen, ihn in alle Anforderungen aufzunehmen. |
appVersion |
Aufrufen der Anwendungsversion. |
gzipResponse |
Optionales Flag zum Aktivieren oder Deaktivieren der gzip-Komprimierung der Antwort-XML. Standardmäßig werden Antworten gzip-komprimiert, wenn der HTTP Accept-Encoding-Header die Unterstützung für gzip anzeigt. |
failureHttpStatusCode |
Optionaler Parameter zum Überschreiben des HTTP-Status-Codes für Fehlerantworten. Standardmäßig geben Fehlerantworten den HTTP-Status-Code 500 (Interner Server-Fehler) zurück. Einige Clientplattformen, einschließlich Adobe-Flash, können den Antworttext nur lesen, wenn ein Statuscode von 200 (OK) zurückgegeben wird. |
Die authHeader
Element wird immer im Namespace definiert http://www.scene7.com/IpsApi/xsd
, unabhängig von der API-Version.
Das folgende Beispiel zeigt die Verwendung der authHeader
-Element in einer SOAP-Anforderungs-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 Authentifizierungsmethoden für Anfragen
Aus irgendeinem Grund ist es nicht möglich, dass Ihre Client-Anwendung die authHeader
SOAP-Header können API-Anfragen auch Anmeldeinformationen mithilfe der HTTP Basic-Authentifizierung (wie in RFC 2617 angegeben) angeben.
Für die HTTP-Standardauthentifizierung muss der HTTP-Header-Abschnitt jeder SOAP-POST-Anfrage einen Header des Formulars enthalten:
Authorization: Basic base64(<IPS_user_email>:<password>)
Wo base64()
wendet die standardmäßige Base64-Kodierung an, <IPS_user_email>
die E-Mail-Adresse eines gültigen IPS-Benutzers und <password>
ist das Kennwort des Benutzers.
Senden Sie die Autorisierungs-Kopfzeile mit der ersten Anfrage vorab. Wenn keine Authentifizierungsberechtigungen in der Anfrage enthalten sind, IpsApiService
antwortet nicht mit dem Status-Code von 401 (Unauthorized)
. Stattdessen wird ein Statuscode von 500 (Internal Server Error)
wird mit einem SOAP-Fehlerkörper 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
-Elemente im Namespace http://www.scene7.com/IpsApi
. 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 für die authHeader
-Element.
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.
Beispielhafte SOAP-Anforderung und -Antwort
Das folgende Beispiel zeigt eine vollständige addCompany
-Vorgang, 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 ein SOAP-Fehler anstelle der normalen Antwort als Text der SOAP-Nachricht zurückgegeben. Wenn beispielsweise ein Benutzer ohne Administratorrechte versucht, die vorherige addCompany
-Anfrage, 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>