Versions WSDL du service Web IPS ips-web-service-wsdl-versions
Le service Web IPS est pris en charge par un ensemble de documents WSDL (Web Services Description Language) accessibles à partir de n’importe quelle installation IPS sur laquelle le composant Service Web IPS est installé. Chaque version de l’API IPS inclut un nouveau fichier WSDL qui fait 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 permettre la compatibilité descendante avec les applications existantes.
Accès WSDL section-62e69fa2c87f4dc9bca72f10ba028f6c
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 pour <IPS_webapp>
est scene7
.
Lieu de service
L’URL de service est spécifiée dans la section service du document WSDL du service Web IPS. L’URL de service se présente généralement sous la forme suivante :
https://<IPS_hostname>:<IPS_port>/<IPS_webapp>/
services/IpsApiService
URL d’accès pour les régions Dynamic Media
WSDL pris en charge section-ebbba69880f94e9c823f1147974eb404
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 WSDL pour les versions suivantes :
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 peuvent avoir besoin d’apporter des modifications au code existant. Consultez le journal des modifications pour plus de détails.
SAVON section-51e7ecbd1d7f451b9e4f6bf7e1579cae
Liaisons
Le service Web de l’API IPS prend uniquement en charge une liaison SOAP.
Transports pris en charge
La liaison SOAP API IPS prend en charge le transport HTTP uniquement. Effectuez toutes les demandes SOAP à l’aide de la méthode HTTPS POST.
En-tête d’action SOAP
Pour traiter une demande, 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 dont les types sont 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 utilisant la valeur d’espace de noms cible spécifiée dans le fichier WSDL.
Demander l’authentification
La méthode préférée pour transmettre les informations d’identification d’authentification dans les requêtes 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
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 requêtes
Si, pour une raison quelconque, il n’est pas possible pour votre application cliente de transmettre l’en-tête authHeader
SOAP, les requêtes API peuvent également spécifier des informations d’identification à l’aide de l’authentification HTTP de base (comme spécifié dans RFC 2617).
Pour l’authentification HTTP de base, la section d’en-tête HTTP de chaque demande de POST SOAP doit inclure un en-tête du formulaire :
Authorization: Basic base64(<IPS_user_email>:<password>)
Où base64()
s’applique le codage standard Base64, <IPS_user_email>
est l’adresse e-mail d’un utilisateur IPS valide et <password>
est le mot de passe de l’utilisateur.
Envoie l’en-tête Authorization de manière préventive avec la demande initiale. Si aucune information d’authentification n’est incluse dans la requête, IpsApiService
ne répond pas avec le code d’état .401 (Unauthorized)
Au lieu de cela, un code d’état de 500 (Internal Server Error)
est renvoyé avec un corps d’erreur SOAP indiquant que la demande n’a pas pu être authentifiée.
Avant IPS 3.8, l’authentification par le biais de l’en-tête SOAP était implémentée à l’aide AuthUser
des éléments 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é en faveur de l’élément authHeader
.
Demander une autorisation
Une fois les informations d’identification de l’appelant authentifiées, la demande 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 d’utilisateur de l’appelant et peut également nécessiter de vérifier la société cible, l’utilisateur cible et d’autres paramètres d’opération. En outre, les utilisateurs du portail d’images doivent appartenir à un groupe avec les autorisations requises pour effectuer certaines opérations sur les dossiers et les ressources. La section de référence Opérations détaille les exigences d’autorisation pour chaque opération.
Exemple de requête et de réponse SOAP
L’exemple suivant illustre une opération complète addCompany
, y compris les 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 comme corps du message SOAP à la place 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>