Le service Web IPS est pris en charge par un ensemble de documents WSDL (Web Services Description Language) accessibles à partir de toute installation IPS sur laquelle le composant Service Web IPS est installé. Chaque version de l’API IPS comprend un nouveau fichier WSDL qui référence un espace de noms XML cible versionné. Les versions antérieures de l’espace de noms WSDL sont également prises en charge pour garantir une compatibilité descendante avec les applications existantes.
Accédez aux fichiers WSDL Scene7 comme illustré ci-dessous.
https://<IPS_hostname:<IPS_port>/<IPS_webapp>/
webservice/IpsApi[-<API_version>].wsdl
La valeur par défaut de <IPS_webapp>
est scene7
.
Emplacement du service
L’URL du service est spécifiée dans la section service du document WSDL du service Web IPS. L’URL du service est généralement de la forme :
https://<IPS_hostname>:<IPS_port>/<IPS_webapp>/
services/IpsApiService
URL d’accès pour les régions Dynamic Media
Emplacement géographique |
URL de production |
URL d’évaluation (utilisée pour le développement et le test de pré-production) |
---|---|---|
Amérique du Nord |
https://s7sps1apissl.scene7.com/scene7/ |
https://s7sps1apissl-staging.scene7.com/scene7/ |
Europe, Moyen-Orient, Asie |
https://s7sps3apissl.scene7.com/scene7/ |
https://s7sps3apissl-staging.scene7.com/scene7/ |
Japon/Asie-Pacifique |
https://s7sps5apissl.scene7.com/scene7/ |
https://s7sps5apissl-staging.scene7.com/scene7/ |
N'oubliez pas que vous devrez peut-être modifier votre code si vous souhaitez utiliser les fonctionnalités de la dernière version de l'API IPS. L’API IPS prend en charge les fichiers WSDL pour les versions suivantes :
Version de publication de l’API |
WSDL |
Espace de noms API |
---|---|---|
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 |
Pre-4.0 |
IpsApi.wsdl |
http://www.scene7.com/IpsApi/xsd |
Les applications existantes qui doivent être modifiées pour utiliser de nouvelles fonctionnalités doivent être mises à niveau vers la dernière version de l’API et doivent peut-être apporter des modifications au code existant. Consultez le journal des modifications pour plus d’informations.
Liaisons
Le service Web de l’API IPS ne prend en charge qu’une liaison SOAP.
Transferts pris en charge
La liaison SOAP de l’API IPS prend uniquement en charge le transport HTTP. Effectuez toutes les requêtes SOAP à l’aide de la méthode de POST HTTPS.
En-tête d’action SOAP
Pour traiter une requête, définissez l’en-tête HTTP SOAPAction sur le nom de l’opération demandée. L’attribut du nom de l’opération dans la section de liaison WSDL spécifie le nom.
Format du message
Le style document/littéral est utilisé pour tous les messages d’entrée et de sortie avec des types basés sur le langage de définition de schéma XML ( https://www.w3.org/TR/xmlschema-0/) et spécifiés dans le fichier WSDL. Tous les types nécessitent des noms qualifiés à l’aide de la valeur d’espace de noms cible spécifiée dans le fichier WSDL.
Authentification de demande
La méthode privilégiée pour transmettre des informations d’authentification dans les demandes d’API consiste à utiliser l’élément authHeader
tel que défini dans le WSDL de l’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>
Champs
Nom |
Description |
---|---|
utilisateur |
Adresse électronique utilisateur IPS valide. |
mot de passe |
Mot de passe du compte utilisateur. |
locale |
Paramètre régional facultatif pour la requête. Voir Paramètres régionaux pour plus d’informations. |
appName |
Appel du nom de l’application. Ce paramètre est facultatif, mais il est recommandé de l’inclure dans toutes les requêtes. |
appVersion |
Appel de la version de l’application. |
gzipResponse |
Indicateur facultatif pour activer ou désactiver la compression Gzip du XML de réponse. Par défaut, les réponses sont compressées par gzip si l’en-tête HTTP Accept-Encoding indique la prise en charge de gzip. |
faulHttpStatusCode |
Paramètre facultatif permettant de remplacer le code d’état HTTP pour les réponses d’erreur. Par défaut, les réponses d’erreur renvoient le code d’état HTTP 500 (Erreur interne du serveur). Certaines plateformes clientes, y compris Adobe Flash, ne peuvent pas lire le corps de la réponse à moins qu’un code d’état 200 (OK) ne soit renvoyé. |
L’élément authHeader
est toujours défini dans l’espace de noms http://www.scene7.com/IpsApi/xsd
, quelle que soit la version de l’API.
Voici un exemple d’utilisation de l’élément authHeader
dans un en-tête SOAP de requête :
<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>
Autres méthodes d’authentification des demandes
Si, pour une raison quelconque, votre application cliente ne peut pas transmettre l’en-tête SOAP authHeader
, les demandes d’API peuvent également spécifier des informations d’identification à l’aide de l’authentification HTTP de base (comme spécifié dans la norme RFC 2617).
Pour l’authentification HTTP de base, la section d’en-tête HTTP de chaque requête de POST SOAP doit inclure un en-tête du formulaire :
Authorization: Basic base64(<IPS_user_email>:<password>)
Si base64()
applique le codage standard Base64, <IPS_user_email>
est l’adresse électronique d’un utilisateur IPS valide et <password>
est le mot de passe de l’utilisateur.
Envoyez l’en-tête d’autorisation de manière préventive avec la requête initiale. Si aucune information d’authentification n’est incluse dans la requête, IpsApiService
ne répond pas avec un code d’état de 401 (Unauthorized)
. Au lieu de cela, un code d’état 500 (Internal Server Error)
est renvoyé avec un corps de défaillance SOAP indiquant que la requête n’a pas pu être authentifiée.
Avant IPS 3.8, l'authentification via l'en-tête SOAP était mise en oeuvre à l'aide des éléments AuthUser
et AuthPassword
dans l'espace de noms http://www.scene7.com/IpsApi
. Par exemple :
<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>
Ce style est toujours pris en charge pour la compatibilité descendante, mais a été abandonné au profit de l’élément authHeader
.
Demande d’autorisation
Une fois les informations d’identification de l’appelant authentifiées, la requête est vérifiée pour s’assurer que l’appelant est autorisé à effectuer l’opération demandée. L’autorisation est basée sur le rôle utilisateur de l’appelant et peut également nécessiter la vérification de la société cible, de l’utilisateur cible et d’autres paramètres d’opération. En outre, les utilisateurs du portail d’images doivent appartenir à un groupe disposant des autorisations requises pour effectuer certaines opérations sur les dossiers et les ressources. La section de référence Opérations décrit les exigences d’autorisation pour chaque opération.
Exemple de requête et de réponse SOAP
L’exemple suivant illustre une opération addCompany
complète, y compris des en-têtes 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>
Et la réponse correspondante :
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>
Erreurs SOAP
Lorsqu’une opération rencontre une condition d’exception, une erreur SOAP est renvoyée en tant que corps du message SOAP au lieu de la réponse normale. Par exemple, si un utilisateur non-administrateur tente d’envoyer la requête addCompany
précédente, la réponse suivante est renvoyée :
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>