Versiones WSDL del servicio web IPS

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 IPS en la que esté instalado el componente de servicio web IPS. Cada versión de la API IPS incluye un nuevo archivo WSDL que hace referencia a un espacio de nombres XML de destino con versiones. Las versiones anteriores del espacio de nombres WSDL también son compatibles para permitir la compatibilidad con versiones anteriores de las aplicaciones existentes.

Acceso WSDL

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 de <IPS_webapp> es scene7.

Ubicación del servicio

La 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

WSDL compatibles

Recuerde que es posible que tenga que modificar el código si desea utilizar funciones en la última versión de la API de IPS. La API de IPS admite WSDL para las siguientes versiones:

Las aplicaciones existentes que deben modificarse para utilizar nuevas funciones deben actualizarse a la última versión de la API y es posible que deban realizar cambios en el código existente. Consulte el registro de cambios para obtener más información.

SOAP

Enlaces

El servicio web de API de IPS solo admite un enlace SOAP.

Transportes admitidos

El enlace SOAP de la API IPS solo admite transporte HTTP. Realice todas las solicitudes SOAP utilizando el método de 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 la operación en la sección de enlace 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 del esquema XML ( https://www.w3.org/TR/xmlschema-0/) y especificados en el archivo WSDL. Todos los tipos requieren nombres cualificados que utilicen el valor de espacio de nombres de destino especificado en el archivo WSDL.

Solicitud de autenticación

El método preferido para pasar credenciales de autenticación en solicitudes de API es utilizar el elemento authHeader tal como se define en el WSDL de la 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>

Campos

El elemento authHeader siempre se define en el espacio de nombres http://www.scene7.com/IpsApi/xsd, independientemente de la versión de la API.

A continuación se muestra un ejemplo del uso del elemento 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 solicitud

Si, por algún motivo, su aplicación cliente no puede pasar el encabezado authHeader SOAP, las solicitudes de API también pueden especificar credenciales mediante 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 de POST SOAP debe incluir un encabezado del formulario:

Authorization: Basic base64(<IPS_user_email>:<password>)

Donde base64() aplica la codificación base64 estándar, <IPS_user_email> es la dirección de correo electrónico de un usuario 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, se devuelve un código de estado de 500 (Internal Server Error) 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 los elementos AuthUser y AuthPassword en el espacio 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 se ha desaprobado en favor del elemento authHeader .

Solicitud de autorización

Una vez autenticadas las credenciales del llamador, se comprueba la solicitud para garantizar que el llamador esté autorizado a realizar la operación solicitada. La autorización se basa en la función de usuario del llamador y también puede requerir la comprobación de los parámetros de empresa de destino, usuario de destino y otras operaciones. 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.

Solicitud y respuesta SOAP de ejemplo

El siguiente ejemplo muestra una operación addCompany completa, 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>

Fallos 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 la solicitud anterior addCompany , 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>