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
支持的WSDL :headding-anchor:section-ebbba69880f94e9c823f1147974eb404
请记住,如果要使用最新版本的IPS API中的功能,则可能需要修改代码。 IPS API支持以下版本的WSDL:
现有应用程序如果需要进行修改才能使用新功能,则必须升级到最新的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>
字段
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
中的AuthUser
和AuthPassword
元素实现的。 例如:
<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>