Web 服務結構節點與屬性

REST 內送 Web 服務作業會叫用以單一結構為基礎的物件，可以是業務物件、業務服務或服務指令檔。物件有一個同時預設為「要求」和「回應」結構的結構。本產品讓您能夠為 Web 服務作業定義明確的結構，以代表面向外部消費者的基礎內部結構檢視。請注意，作業結構是內部結構的嚴格檢視，因此不會引入結構變更。

定義作業結構雖然是選擇性的，但具有以下優點：

  • 宣告元素的用途，表示元素屬於「要求」結構、「回應」結構或兩者，或以上皆非。

  • 將外部元素名稱指派給內部元素。這有助於避免僅為了此目的便複製內部服務。

  • 更佳的 GET 作業參考管理與可見性。

  • 支援內部結構以外的 HATEOAS 樣式結構。這可允許無縫內部處理。

  • 提供個別元素的說明文字。

下列文件是建構內部 Web 服務結構時，可供您使用的屬性完整列表。

作業結構定義

下列屬性定義面向外部作業結構，以建立作業的要求和回應結構。

記憶碼 有效值 描述 範例
usage= "REQ"

指出元素僅應包含在要求結構中。

為群組或列表元素指定時，值會套用至整個容器。容器中的特定元素可置換容器預設值。

 
<customerName usage="REQ" />
"RESP"

指出元素僅應包含在回應結構中。

為群組或列表元素指定時，值會套用至整個容器。容器中的特定元素可置換容器預設值。

 
<customerId usage="RESP" />
"BOTH"

指出元素應同時包含在要求與回應結構定義中。這是預設值

為群組或列表元素指定時，值會套用至整個容器。容器中的特定元素可置換容器預設值。

 
<customerName usage="BOTH" />
"EXCL"

指出元素不應包含在要求或回應結構定義中。

為群組或列表元素指定時，值會套用至整個容器。容器中的特定元素可置換容器預設值。

 
<httpMethod usage="EXCL" />
mapTo= "internal element name"

將 Web 服務元素對應至內部元素。內部元素名稱預設會假設為與 Web 服務元素名稱相同。使用此屬性來指派作業結構中的面向外部元素名稱，並將其對應至對應的內部元素。

請注意，這不是 XPath 表示式，而是一個對應至已展開內部結構之有效元素名稱的參考。

元素的擁有者必須與 Web 服務結構的擁有者相同。如果作業的基礎結構已延伸 (使用動態資料區域延伸)，則延伸擁有者只能在作業的 Web 服務結構延伸上參考其元素。

內部結構元素：

<toDoPriority .../>

作業結構元素：

<priority mapTo="toDoPriority"/>
role= "FKGP"

建立代表實體外來索引鍵的群組結構。

元素本身不存在於內部結構中。它會將外來索引鍵值元素與在執行時間提供該實體之 GET 作業端點 URL 的對應 _​link 元素組成群組。Web 服務的消費者可以使用該連結來取得實體的資料。

內部結構元素：

<user .../>

作業結構群組：

<user role="FKGP">
   <user>
   <_link getOperation="mo:'USER';pk1:user;"/>
</user>
"COLL"

建立代表對應至內部服務列表之實體集合的群組結構。

元素本身不存在於內部結構中。它會將對應至 _​data 元素的內部列表，與在執行時間為集合之 GET 作業端點 URL 的對應 _​link 元素組成群組。Web 服務的消費者可以使用該連結，取得列表中每個實體更詳細的資訊集。

參考列表中的所有元素預設都會包括在作業結構中。您可以視需要明確參考和定義特定元素的屬性。

內部結構元素：

<alerts type="list">
     <alert/>
     <startDate />
     <endDate />
     <version />
   </_data> </alerts>

作業結構群組：

<alerts role="COLL">
   <_link getOperation="... "/>
   <_data mapTo="alerts">
        <version usage="EXCL"/>
   </_data>
</alerts>
getOperation=

“expression”

表示式元件：

  • mo:’<維護物件>’；

  • pk1:<內部結構中元素的相對 xpath>；

  • pk2:...；

  • pk3:...；

  • pk4:...；

  • pk5:...；

需有參數 pk2-5 才符合維護物件的主索引鍵定義。

只有 _self 和 _link 元素才有效。此屬性是用來參考實體的預設 GET 作業，如其維護物件或業務物件所定義。

應用程式會決定要使用的 GET 作業，如下所示：

  • 如果實體的業務物件使用 GET 作業選項參考作業，則會使用該作業。

  • 如果實體的維護物件使用 GET 作業選項參考作業，則會使用該作業。

  • 如果發現參考維護物件的 GET 作業，則會使用該作業。

如果無法判定實體的 GET 作業，則會改為傳回表示連結無法使用的標準文字。
 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>

“expression”

表示式元件：

  • iws:’<內送 Web 服務名稱>’;

  • operation:’<作業名稱>’;

  • parms:[<如 GET 作業記錄定義的外部參考>:<保留該值內部結構中元素名稱的相對 xpath>; <另一個外部參考名稱>:<另一個相對 xpath>;...];

只有 _self 和 _link 元素才有效。此屬性是用來參考特定的 GET 作業，以及組成其路徑參數所需的資訊。

 
<_self getOperation="iws:'F1-ToDoEntry'; operation:'getToDoEntry'; parms:[toDoEntryId:toDoEntryId;]"/>

特殊元素

作業結構定義使用超媒體樣式中的特殊元素名稱作為「應用程式狀態引擎」(HATEOAS) 標準。這些元素只能由作業結構定義，因為它們不相關也不應交由內部作業服務管理。

以下列表說明每個元素及其使用方式。

元素名稱 描述 範例
<_​self .../>

回應承載可能包含「_self」元素，此元素包含與回應中所傳回實體相關的 GET 作業端點 URL。

這是選擇性元素，在作業結構中只能有一個此元素。

如需詳細資訊，請參考 getOperation= 結構定義屬性。

 
<_self getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>
<_​link .../>

回應承載可能包含外來索引鍵，而對於這些實體，回應會包含一個「_link」元素，其中包含該實體 GET 作業的端點 URL (如果有的話)。

如需詳細資訊，請參考 role= 和 getOperation= 結構定義屬性。

 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>
<_​data .../>

提供對內部結構中實體列表的標準參考。

如需詳細資訊，請參考 role=”COLL” 結構定義屬性。

 
<alerts role="COLL">
   <_link getOperation="... "/>
   <_data mapTo="alerts">
   </_data>
</alerts>

文件屬性

下列屬性為納入作為 Web 服務之開放 API 規格一部分的個別元素提供其他文件。

記憶碼 有效值 描述 範例
helpText= 「說明文字欄位名稱」

將元素與為內送 Web 服務定義的特定說明文字記錄產生關聯。如果元素同時包含在要求和回應結構中，則會在兩者中使用相同的說明文字。

如果未指定此屬性，且與內部元素相關聯的「欄位」有單一「說明文字欄位」記錄存在，則會使用該說明文字記錄。如果有多個此類「說明文字欄位」記錄存在，則會使用其說明文字名稱與「欄位」名稱相同的記錄。

請注意，內部元素會透過 mdField= 屬性 (若有的話) 與「欄位」名稱相關聯，否則會透過 mapField= 屬性建立關聯。

對於 _​self 與 _​link 元素無效。

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY"/>

在此範例中，內送 Web 服務定義說明文字欄位名稱「TD_​ENTRY」，以提供此元素的說明文字。對於在要求和回應結構中皆存在的元素，會為該元素包含相同的說明文字。
helpTextResponse= 「說明文字欄位名稱」

將要求與回應結構中皆包含的元素，與要用於回應結構內容中的特定說明文字記錄產生關聯。

遵循與 helpText= 屬性相同的規則。

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY" helpTextResponse="TD_ENTRY_RESP"/>
在此範例中，內送 Web 服務定義下列說明文字記錄：

  • 說明文字欄位名稱「TD_​ENTRY」描述要求結構中傳送的元素。

  • 說明文字欄位名稱「TD_​ENTRY_​RESP」描述回應結構中植入的元素。