El servicio web IPS es compatible con un conjunto de documentos WSDL (Lenguaje de descripción de servicios web) a los que se accede desde cualquier instalación de IPS en la que esté instalado el componente Servicio web IPS. Cada versión de la API de IPS incluye un nuevo archivo WSDL que hace referencia a un espacio de nombres XML de destino con versiones. Las versiones de área de nombres de WSDL anteriores también son compatibles para permitir la compatibilidad con versiones anteriores de las aplicaciones existentes.
Acceda a los WSDL de Scene7 como se muestra a continuación.
https://<IPS_hostname:<IPS_port>/<IPS_webapp>/
webservice/IpsApi[-<API_version>].wsdl
El valor predeterminado para <IPS_webapp>
es scene7
.
Ubicación del servicio
La dirección URL del servicio se especifica en la sección de servicio del documento WSDL del servicio web IPS. La URL del servicio suele tener el siguiente formato:
https://<IPS_hostname>:<IPS_port>/<IPS_webapp>/
services/IpsApiService
Acceso a direcciones URL para regiones de Dynamic Media
Ubicación geográfica |
URL de producción |
URL de ensayo (se utiliza para el desarrollo y la prueba previos a la producción) |
---|---|---|
América del Norte |
https://s7sps1apissl.scene7.com/scene7/ |
https://s7sps1apissl-staging.scene7.com/scene7/ |
Europa, Oriente Medio, Asia |
https://s7sps3apissl.scene7.com/scene7/ |
https://s7sps3apissl-staging.scene7.com/scene7/ |
Japón/Asia-Pacífico |
https://s7sps5apissl.scene7.com/scene7/ |
https://s7sps5apissl-staging.scene7.com/scene7/ |
Recuerde que es posible que tenga que modificar el código si desea utilizar características de en la última versión de la API de IPS. La API de IPS admite WSDL para las siguientes versiones:
Versión de versión de API |
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 |
Anterior a 4.0 |
IpsApi.wsdl |
http://www.scene7.com/IpsApi/xsd |
Las aplicaciones existentes que necesiten modificarse para utilizar nuevas funciones deben actualizarse a la última versión de la API y es posible que tengan que realizar cambios en el código existente. Consulte el registro de cambios para obtener más información.
Enlaces
El servicio web de la API de IPS sólo admite un enlace SOAP.
Transportes compatibles
El enlace SOAP de la API de IPS solo admite el transporte HTTP. Realice todas las solicitudes SOAP utilizando el método del POST HTTPS.
Encabezado de acción SOAP
Para procesar una solicitud, establezca el encabezado HTTP SOAPAction en el nombre de la operación solicitada. El atributo de nombre de operación de la sección de enlace de WSDL especifica el nombre.
Formato del mensaje
El estilo documento/literal se utiliza para todos los mensajes de entrada y salida con tipos basados en el lenguaje de definición de esquema XML ( https://www.w3.org/TR/xmlschema-0/) y se especifica en el archivo WSDL. Todos los tipos requieren nombres completos utilizando el valor de área de nombres de destino especificado en el archivo WSDL.
Solicitar autenticación
El método preferido para pasar credenciales de autenticación en solicitudes de API es utilizar la variable authHeader
tal como se define en el WSDL de la API de 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>
Campos
Nombre |
Descripción |
---|---|
usuario |
Correo electrónico de usuario de IPS válido. |
contraseña |
Contraseña de la cuenta de usuario. |
locale |
Configuración regional opcional para la solicitud. Consulte Configuración regional para obtener más información. |
appName |
Llamando al nombre de aplicación. Este parámetro es opcional, pero se recomienda incluirlo en todas las solicitudes. |
appVersion |
Llamando a la versión de aplicación. |
gzipResponse |
Indicador opcional para habilitar o deshabilitar la compresión gzip del XML de respuesta. De forma predeterminada, las respuestas se comprimen con gzip si el encabezado HTTP Accept-Encoding indica compatibilidad con gzip. |
failureHttpStatusCode |
Parámetro opcional para anular el código de estado HTTP para las respuestas de errores. De forma predeterminada, las respuestas de errores devuelven el código de estado HTTP 500 (error interno del servidor). Algunas plataformas cliente, incluido el Flash de Adobe, no pueden leer el cuerpo de la respuesta a menos que se devuelva un código de estado 200 (OK). |
El authHeader
siempre se define en el área de nombres http://www.scene7.com/IpsApi/xsd
, independientemente de la versión de la API.
A continuación se muestra un ejemplo de uso de authHeader
en un encabezado SOAP de solicitud:
<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>
Otros métodos de autenticación de solicitudes
Si, por alguna razón, no es posible que la aplicación cliente pase el authHeader
Encabezado SOAP, las solicitudes de API también pueden especificar credenciales mediante la autenticación HTTP Basic (como se especifica en RFC 2617).
Para la autenticación HTTP Basic, la sección de encabezado HTTP de cada solicitud del POST SOAP debe incluir un encabezado con el siguiente formato:
Authorization: Basic base64(<IPS_user_email>:<password>)
Donde base64()
aplica la codificación estándar Base64, <IPS_user_email>
es la dirección de correo electrónico de un usuario de IPS válido y <password>
es la contraseña del usuario.
Envíe el encabezado Autorización de forma preventiva con la solicitud inicial. Si no se incluyen credenciales de autenticación en la solicitud, IpsApiService
no responde con un código de estado de 401 (Unauthorized)
. En su lugar, un código de estado de 500 (Internal Server Error)
se devuelve con un cuerpo de error SOAP que indica que la solicitud no se pudo autenticar.
Antes de IPS 3.8, la autenticación mediante el encabezado SOAP se implementaba utilizando AuthUser
y AuthPassword
elementos en el área de nombres http://www.scene7.com/IpsApi
. Por ejemplo:
<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>
Este estilo sigue siendo compatible con la compatibilidad con versiones anteriores, pero ha quedado obsoleto en favor de la authHeader
Elemento.
Solicitar autorización
Una vez autenticadas las credenciales del llamador, se comprueba la solicitud para asegurarse de que el llamador está autorizado para realizar la operación solicitada. La autorización se basa en la función de usuario del autor de la llamada y también puede requerir la comprobación de la compañía, el usuario y otros parámetros de operación de destino. Además, los usuarios del portal de imágenes deben pertenecer a un grupo con los permisos necesarios para realizar determinadas operaciones de carpetas y recursos. La sección de referencia Operaciones detalla los requisitos de autorización para cada operación.
Ejemplo de solicitud y respuesta de SOAP
El siguiente ejemplo muestra una addCompany
operación, incluidos los encabezados 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>
Y la respuesta correspondiente:
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>
Errores de SOAP
Cuando una operación encuentra una condición de excepción, se devuelve un error SOAP como el cuerpo del mensaje SOAP en lugar de la respuesta normal. Por ejemplo, si un usuario no administrador intenta enviar el anterior addCompany
solicitud, se devuelve la siguiente respuesta:
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>