IPS Web服务WSDL版本 :headding-anchor:ips-web-service-wsdl-versions

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

WSDL访问 :headding-anchor:section-62e69fa2c87f4dc9bca72f10ba028f6c

访问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 :headding-anchor:section-ebbba69880f94e9c823f1147974eb404

请记住,如果要使用最新版本的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 :headding-anchor:section-51e7ecbd1d7f451b9e4f6bf7e1579cae

绑定

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用户电子邮件。
密码
用户帐户的密码。
区域设置
请求的可选区域设置。 有关详细信息,请参阅 区域设置
appName
正在调用应用程序名称。 此参数是可选的,但建议将其包含在所有请求中。
appVersion
正在调用应用程序版本。
gzipResponse
启用或禁用响应XML的gzip压缩的可选标记。 默认情况下,如果HTTP Accept-Encoding标头指示支持gzip,则响应将进行gzip压缩。
faultHttpStatusCode
用于覆盖错误响应的HTTP状态代码的可选参数。 默认情况下,错误响应返回HTTP状态代码500(内部服务器错误)。 某些客户端平台(包括AdobeFlash)无法读取响应正文,除非返回200 (OK)状态代码。

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

以下是在请求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基本身份验证(如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之前,通过SOAP标头的身份验证是使用命名空间http://www.scene7.com/IpsApi中的AuthUserAuthPassword元素实现的。 例如:

<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>
recommendation-more-help
4e9b9d8c-5839-4215-aa35-01b652869681