內送 REST Web 服務

HTTP 方法和參數

定義內送 REST Web 服務的作業時，產品可支援 Get、Patch、Post、Put 和 Delete 等 HTTP 方法。請注意，產品對於這些不同 HTTP 方法的支援，其實是一種溝通手段，借此將 Web 服務的用途傳達給外部世界。然而，REST Web 服務的實際行為取決於基於底層結構的物件 (業務物件、業務服務或服務指令檔) 的行為。例如，若某項作業所參考的服務指令檔只會擷取記錄，則您可以為該作業設定 “Put” HTTP 方法。產品無法偵測到這種差異。組態使用者應根據該服務的邏輯，仔細考慮該使用的正確方法。

至於那些參考業務物件的作業，必須提供交易類型。REST 語法不支援在執行時間定義交易類型。在這種情況下，會進行一些與交易類型和 HTTP 方法有關的基本驗證檢查。例如，只有 Read 交易類型，Get 方法才會有意義。

您可以另外定義參數。您可以為每個參數定義元素的外部參考，這就是該參數向外部呼叫程式公開的方式，而且在 API 規格中有相關定義。這些參數中的每一個都會對應至來自基礎業務物件、業務服務或服務指令檔的結構元素 XPath。針對每一個參數，您指定其為 Path 參數或者是 Query 參數。

• 路徑參數是指那些屬於端點組成部分的必要參數。每個路徑參數都必須包含在作業的 URI 元件中，並用大括號括住。

• 查詢參數是選擇性的。這些參數不是端點的一部分，而是包含在端點 URL 中，位於問號之後，後面是名稱值組。

如需範例 URL 中的路徑和查詢參數例子，請參閱以下的 URL 一節。

URL 組成

為 REST 服務建立端點 URL 時，會有三個主要的組成部分構成一個完整的 URL。

• 第一個是與環境有關的組成部分。與雲端實作相比，處所實作則會有所不同。二者都會有主機和連接埠，然後是其他用於識別環境的元件。

• 第二個組成部分是產品指派的硬式編碼路徑，也就是 "/rest/apis"。

  URL 的這兩個組成部分是定義在替代變數 F1_ REST_ BASE_ URL 中。這是在初始化環境時定義的。如需詳細資訊，請參閱伺服器管理指南。

URL 的其餘組成部分是根據每一個內送 Web 服務及其作業的組態動態建立的。元件是 "/ownerURIComponent/resourceCategoryURIComponent/iwsURIComponent/operationURIComponent"

• 擁有者 URI 元件是取自內送 REST Web 服務的擁有者標誌。一個特殊的可延伸查尋 (REST 服務的擁有者組態) 會為每個擁有者標誌定義這個元件。

• 每個內送 REST Web 服務都必須參考一個資源類目。此類目是用來將相關 Web 服務與資源的通用類目產生關聯。至於連結至相同資源類目的多個內送 Web 服務記錄，外部類目可以使用此資訊，將相關 Web 服務組合在一起。資源類目是可延伸的查尋，而 URI 元件是此記錄的屬性。

• 每一個 REST 內送 Web 服務記錄都定義了一個 URI 元件，當作此內送 Web 服務記錄的外部識別碼。這個值在指定的擁有者標誌中必須是唯一的。

• 每個作業都必須定義 HTTP 方法以及一個選擇性 URI 元件。定義路徑參數時，必須在 URI 元件中使用大括號括住路徑參數。

無論什麼情況，URI 元件的開頭都必須是斜線 ('/')。

以下是 REST 服務的 URL 動態組成部分的幾個範例。最後一個範例說明使用查詢參數。

承載格式

REST 服務支援接收採用 XML 或 JSON 格式的要求承載，並傳回採用 XML 或 JSON 格式的承載。傳回的預設格式取決於「REST 引擎版本」的值。

• 版本 2.0 服務採用 JSON 格式為預設值。您可以提供 application/XML 的接受標頭來置換預設值。

• 版本 1.0 服務採用 XML 格式為預設值。您可以提供 application/JSON 的接受標頭來置換預設值。

JSON 格式的根節點

具有 JSON 格式承載的版本 2.0 服務在要求中不接受或在回應中不傳回承載周圍的任何根節點。以下是 2.0 版服務的 REST 呼叫回應範例：

{
   "batchJobId": "string",
   "requestSuccessful": "string"
}

具有 JSON 格式承載的版本 1.0 服務預期要求中有根節點，且在回應中傳回根節點。以下是 1.0 版服務的 REST 呼叫回應範例：

{
  "F1CnclBatJob": {
    "batchJobId": "string",
    "requestSuccessful": "string"
 }
}

內送 Web 服務維護頁面上顯示的開放 API 規格，會在檢視規格時根據記錄的 REST 引擎版本顯示預期的格式。

JSON 中的資料類型格式

在 JSON 格式中，字串會以引號括住，而數字和布林資料則沒有引號。REST 引擎版本 2.0 的所有服務皆遵循此標準。REST 引擎版本 1.0 的服務原本會錯將數字和布林資料視為字串，並傳回帶有引號的資料。此問題已被更正。

為了配合可因應版本 1.0 服務行為的任何整合，系統提供功能可識別為此規則例外的內送 Web 服務。對於識別為例外的任何內送 Web 服務，系統會繼續將數字和布林資料視為 JSON 回應中的字串。若要新增一或多筆內送 Web 服務記錄至例外列表：

• 前往功能組態。

• 尋找功能類型為外部訊息的現有功能組態。如果不存在，請建立一個功能組態。

• 為內送 Web 服務 JSON 資料類型例外選項類型新增一個選項。

• 在選項值中，指出例外的內送 Web 服務記錄。請注意，可以新增選項類型的多個選項。此外，選項值支援以逗號分隔的列表。

面向外部結構

依預設，基礎服務的結構 (例如，服務指令檔、業務物件或業務服務) 也是 REST 內送 Web 服務作業的結構，並同時作為其「要求」與「回應」結構。本產品能夠為 REST 內送 Web 服務作業定義明確的結構，讓使用者可以調整面向外部消費者的結構。內送 Web 服務作業結構也支援某些僅允許針對內送 Web 服務作業結構定義額外功能的特殊組態。

作業結構支援下列功能：

• 宣告元素是僅屬於要求結構、僅屬於回應結構、屬於兩者 (預設值)，還是不屬於以上各項。這是用來在要求與回應結構定義之間建立明確的區隔。

• 將不同的元素名稱指派給內部元素。這可讓內部服務元素名稱更符合對元素的內部參照 (如有需要)。面向外部的元素名稱可以不同，以提供可讀性更高的結構。

• 以不影響內部服務處理的方式，引入支援連結和其他類型結構標準的特殊元素。

如需詳細資訊，請參考 Web 服務結構節點與屬性。

REST Servlet 會使用要求和回應結構，將元素對應至內部結構或從內部結構進行對應。

動態連結

發布的 API 包含「_self」元素，其中包含與回應中所傳回資料相關的 GET 作業端點 URL。此外，回應承載可能包含外來索引鍵，而對於這些實體，回應會包含一個「_link」元素，其中包含該實體 GET 作業的端點 URL (如果有的話)。

REST 內送 Web 服務作業結構中提供語法，以支援建立 _​self 和 _​link 元素的執行時間端點 URL。除了根據目前的環境明細動態建立 URL 的靜態部分之外，還會建立 URL 的動態部分，以替代作業的 URL 元件並替代路徑參數。此語法可讓您定義特定的內送 Web 服務作業，或允許您參照維護物件，且在執行時間，系統會決定維護物件的 GET 作業並相應地建立 URL。

語法範例：

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

執行時間端點 URL 範例：

  _link: "http://.../common/toDos/toDoEntries/28937296450934"

GET 作業可能與維護物件關聯，以表示這是實體的預設 GET 作業。「維護物件」與「業務物件」層級的 GET 作業選項可用來置換此預設值。如果該實體未與業務物件相關聯，或後者未與此類選項相關聯，則會使用與維護物件 (若有的話) 相關聯的作業。

API 規格文件

您可以為內送 Web 服務提供下列文件資訊：

• 每個作業的簡短和詳細描述。

• 可為個別元素提供說明文字。在「內送 Web 服務」的所有作業之間，可以跨多個元素共用相同的文字。如果元素未與說明文字相關聯，則會改用其內部欄位的標籤。

• 可為每個作業提供要求與回應範例文件。

• 作業可能與控制在「開放 API 規格」中顯示順序的序號相關聯。