Web 服務結構節點與屬性
REST 內送 Web 服務作業會叫用以單一結構為基礎的物件,可以是業務物件、業務服務或服務指令檔。物件有一個同時預設為「要求」和「回應」結構的結構。本產品讓您能夠為 Web 服務作業定義明確的結構,以代表面向外部消費者的基礎內部結構檢視。請注意,作業結構是內部結構的嚴格檢視,因此不會引入結構變更。
-
宣告元素的用途,表示元素屬於「要求」結構、「回應」結構或兩者,或以上皆非。
-
將外部元素名稱指派給內部元素。這有助於避免僅為了此目的便複製內部服務。
-
更佳的 GET 作業參考管理與可見性。
-
支援內部結構以外的 HATEOAS 樣式結構。這可允許無縫內部處理。
-
提供個別元素的說明文字。
下列文件是建構內部 Web 服務結構時,可供您使用的屬性完整列表。
作業結構定義
下列屬性定義面向外部作業結構,以建立作業的要求和回應結構。
記憶碼 | 有效值 | 描述 | 範例 |
---|---|---|---|
usage= | "REQ" |
指出元素僅應包含在要求結構中。 為群組或列表元素指定時,值會套用至整個容器。容器中的特定元素可置換容器預設值。 |
|
"RESP" |
指出元素僅應包含在回應結構中。 為群組或列表元素指定時,值會套用至整個容器。容器中的特定元素可置換容器預設值。 |
|
|
"BOTH" |
指出元素應同時包含在要求與回應結構定義中。這是預設值 為群組或列表元素指定時,值會套用至整個容器。容器中的特定元素可置換容器預設值。 |
|
|
"EXCL" |
指出元素不應包含在要求或回應結構定義中。 為群組或列表元素指定時,值會套用至整個容器。容器中的特定元素可置換容器預設值。 |
|
|
mapTo= | "internal element name" |
將 Web 服務元素對應至內部元素。內部元素名稱預設會假設為與 Web 服務元素名稱相同。使用此屬性來指派作業結構中的面向外部元素名稱,並將其對應至對應的內部元素。 請注意,這不是 XPath 表示式,而是一個對應至已展開內部結構之有效元素名稱的參考。 元素的擁有者必須與 Web 服務結構的擁有者相同。如果作業的基礎結構已延伸 (使用動態資料區域延伸),則延伸擁有者只能在作業的 Web 服務結構延伸上參考其元素。 |
內部結構元素:
作業結構元素:
|
role= | "FKGP" |
建立代表實體外來索引鍵的群組結構。 元素本身不存在於內部結構中。它會將外來索引鍵值元素與在執行時間提供該實體之 GET 作業端點 URL 的對應 _link 元素組成群組。Web 服務的消費者可以使用該連結來取得實體的資料。 |
內部結構元素:
作業結構群組:
|
"COLL" |
建立代表對應至內部服務列表之實體集合的群組結構。 元素本身不存在於內部結構中。它會將對應至 _data 元素的內部列表,與在執行時間為集合之 GET 作業端點 URL 的對應 _link 元素組成群組。Web 服務的消費者可以使用該連結,取得列表中每個實體更詳細的資訊集。 參考列表中的所有元素預設都會包括在作業結構中。您可以視需要明確參考和定義特定元素的屬性。 |
內部結構元素:
作業結構群組:
|
|
getOperation= |
“expression” 表示式元件:
需有參數 pk2-5 才符合維護物件的主索引鍵定義。 |
只有 _self 和 _link 元素才有效。此屬性是用來參考實體的預設 GET 作業,如其維護物件或業務物件所定義。 應用程式會決定要使用的 GET 作業,如下所示:
|
|
“expression” 表示式元件:
|
只有 _self 和 _link 元素才有效。此屬性是用來參考特定的 GET 作業,以及組成其路徑參數所需的資訊。 |
|
特殊元素
作業結構定義使用超媒體樣式中的特殊元素名稱作為「應用程式狀態引擎」(HATEOAS) 標準。這些元素只能由作業結構定義,因為它們不相關也不應交由內部作業服務管理。
以下列表說明每個元素及其使用方式。
元素名稱 | 描述 | 範例 |
---|---|---|
<_self .../> |
回應承載可能包含「_self」元素,此元素包含與回應中所傳回實體相關的 GET 作業端點 URL。 這是選擇性元素,在作業結構中只能有一個此元素。 如需詳細資訊,請參考 getOperation= 結構定義屬性。 |
|
<_link .../> |
回應承載可能包含外來索引鍵,而對於這些實體,回應會包含一個「_link」元素,其中包含該實體 GET 作業的端點 URL (如果有的話)。 如需詳細資訊,請參考 role= 和 getOperation= 結構定義屬性。 |
|
<_data .../> |
提供對內部結構中實體列表的標準參考。 如需詳細資訊,請參考 role=”COLL” 結構定義屬性。 |
|
文件屬性
下列屬性為納入作為 Web 服務之開放 API 規格一部分的個別元素提供其他文件。
記憶碼 | 有效值 | 描述 | 範例 |
---|---|---|---|
helpText= | 「說明文字欄位名稱」 |
將元素與為內送 Web 服務定義的特定說明文字記錄產生關聯。如果元素同時包含在要求和回應結構中,則會在兩者中使用相同的說明文字。 如果未指定此屬性,且與內部元素相關聯的「欄位」有單一「說明文字欄位」記錄存在,則會使用該說明文字記錄。如果有多個此類「說明文字欄位」記錄存在,則會使用其說明文字名稱與「欄位」名稱相同的記錄。 請注意,內部元素會透過 mdField= 屬性 (若有的話) 與「欄位」名稱相關聯,否則會透過 mapField= 屬性建立關聯。 對於 _self 與 _link 元素無效。 |
在此範例中,內送 Web 服務定義說明文字欄位名稱「TD_ENTRY」,以提供此元素的說明文字。對於在要求和回應結構中皆存在的元素,會為該元素包含相同的說明文字。 |
helpTextResponse= | 「說明文字欄位名稱」 |
將要求與回應結構中皆包含的元素,與要用於回應結構內容中的特定說明文字記錄產生關聯。 遵循與 helpText= 屬性相同的規則。 |
在此範例中,內送 Web 服務定義下列說明文字記錄:
|