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 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.

Acceso a 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 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

WSDL admitidos

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:

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.

JABÓ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

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>