IPS Web服务WSDL版本

IPS Web服务由一组WSDL(Web服务描述语言)文档支持,这些文档可从安装IPS Web服务组件的任何IPS安装中访问。 每个IPS API版本都包含一个引用版本控制目标XML命名空间的新WSDL文件。 还支持以前的WSDL命名空间版本,以便能够向后兼容现有应用程序。

WSDL访问

访问Scene7 WSDL,如下所示。

https://<IPS_hostname:<IPS_port>/<IPS_webapp>/ 
webservice/IpsApi[-<API_version>].wsdl 

<IPS_webapp>的默认值为scene7

服务位置

服务URL在IPS Web服务WSDL文档的服务部分中指定。 服务URL通常采用以下形式:

https://<IPS_hostname>:<IPS_port>/<IPS_webapp>/ 
services/IpsApiService 

访问Dynamic Media区域的URL

地理位置

生产URL

暂存URL(用于预生产开发和测试)

北美

https://s7sps1apissl.scene7.com/scene7/

https://s7sps1apissl-staging.scene7.com/scene7/

欧洲、中东、亚洲

https://s7sps3apissl.scene7.com/scene7/

https://s7sps3apissl-staging.scene7.com/scene7/

日本/亚太

https://s7sps5apissl.scene7.com/scene7/

https://s7sps5apissl-staging.scene7.com/scene7/

支持的WSDL

请记住,如果要使用最新版IPS API中的功能,您可能需要修改代码。 IPS API支持以下版本的WSDL:

API版本

WSDL

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

4.0之前

IpsApi.wsdl

http://www.scene7.com/IpsApi/xsd

需要修改以使用新功能的现有应用程序必须升级到最新的API版本,并且可能需要更改现有代码。 有关详细信息,请参阅更改日志。

SOAP

绑定

IPS API Web服务仅支持SOAP绑定。

支持的传输

IPS API SOAP绑定仅支持HTTP传输。 使用HTTPSPOST方法发出所有SOAP请求。

SOAP操作标头

要处理请求,请将SOAPAction HTTP标头设置为请求操作的名称。 WSDL绑定部分中的操作名称属性指定名称。

消息格式

文档/文字样式用于所有基于XML架构定义语言(https://www.w3.org/TR/xmlschema-0/)并在WSDL文件中指定的类型的输入和输出消息。 所有类型都需要使用WSDL文件中指定的目标命名空间值限定名称。

请求身份验证

在API请求中传递身份验证凭据的首选方法是使用IPS API WSDL中定义的authHeader元素。

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

字段

名称

说明

用户

有效的IPS用户电子邮件。

密码

用户帐户的密码。

locale

请求的可选区域设置。 有关详细信息,请参阅区域设置

appName

正在调用应用程序名称。 此参数是可选的,但建议您将其包含在所有请求中。

appVersion

正在调用应用程序版本。

gzipResponse

用于启用或禁用响应XML的gzip压缩的可选标记。 默认情况下,如果HTTP Accept-Encoding标头指示支持gzip,则响应将进行gzip压缩。

faultHttpStatusCode

用于覆盖故障响应的HTTP状态代码的可选参数。 默认情况下,错误响应会返回HTTP状态代码500(内部服务器错误)。 某些客户端平台(包括AdobeFlash)无法读取响应正文,除非返回状态代码200(OK)。

无论API版本如何,authHeader元素始终在命名空间http://www.scene7.com/IpsApi/xsd中定义。

以下示例用于在请求SOAP标头中使用authHeader元素:

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

其他请求身份验证方法

如果由于某些原因客户端应用程序无法传递authHeader SOAP标头,则API请求还可以使用HTTP Basic身份验证(如RFC 2617中指定)来指定凭据。

对于HTTP Basic身份验证,每个SOAPPOST请求的HTTP标头部分必须包含表单的标头:

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

其中base64()应用标准Base64编码,<IPS_user_email>是有效IPS用户的电子邮件地址,<password>是用户的密码。

使用初始请求先发送授权标头。 如果请求中未包含身份验证凭据,则IpsApiService不会使用401 (Unauthorized)的状态代码做出响应。 而是返回状态代码500 (Internal Server Error) ,并带有SOAP故障主体,说明请求无法进行身份验证。

在IPS 3.8之前,使用命名空间http://www.scene7.com/IpsApi中的AuthUserAuthPassword元素实施了通过SOAP标头的身份验证。 例如:

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

向后兼容性仍支持此样式,但已弃用此样式,推荐使用authHeader元素。

请求授权

在主叫方的凭据被验证之后,检查该请求以确保主叫方被授权执行所请求的操作。 授权基于呼叫者的用户角色,并且可能还需要检查目标公司、目标用户和其他操作参数。 此外,图像门户用户必须属于具有执行某些文件夹和资产操作所需权限的组。 “操作参考”部分详细介绍了每个操作的授权要求。

SOAP请求和响应示例

以下示例显示了完整的addCompany操作,包括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>

并做出相应的响应:

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>

SOAP故障

当操作遇到异常情况时,将返回一个SOAP故障作为SOAP消息的正文来代替正常响应。 例如,如果非管理员用户尝试发送前一个addCompany请求,则会返回以下响应:

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>

在此页面上