IPS Web服務WSDL版本

IPS Web服務受一組WSDL（Web服務描述語言）文檔的支援，這些文檔從安裝了IPS Web服務元件的任何IPS安裝中訪問。 每個IPS API版本都包含一個新的WSDL檔案，該檔案引用版本控制目標XML命名空間。 也支援以前的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

支援的WSDL

請記住，如果您想要使用最新版IPS API中的功能，則可能需要修改代碼。 IPS API支援以下版本的WSDL:

需要修改以使用新功能的現有應用程式必須升級至最新的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>

Fields

無論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基本身份驗證（如RFC 2617中所指定）來指定憑據。

對於HTTP基本驗證，每個SOAPPOST請求的HTTP標題區段必須包含表單的標題：

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

其中base64()應用標準Base64編碼，<IPS_user_email>是有效IPS用戶的電子郵件地址，<password>是用戶的密碼。

使用初始請求搶先傳送授權標頭。 如果請求中未包含驗證憑據，IpsApiService不會以401 (Unauthorized)的狀態代碼回應。 相反地，系統會以SOAP錯誤內文傳回500 (Internal Server Error)狀態代碼，指出無法驗證請求。

在IPS 3.8之前，已使用命名空間http://www.scene7.com/IpsApi中的AuthUser和AuthPassword元素實作透過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元素。

請求授權

在主叫方的認證被驗證之後，檢查請求以確保主叫方被授權執行所請求的操作。 授權基於呼叫者的用戶角色，並且可能還需要檢查目標公司、目標用戶和其他操作參數。 此外，Image Portal使用者必須屬於具有執行特定資料夾和資產作業所需權限的群組。 操作參考部分詳細說明了每個操作的授權要求。

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