新增類型提供者的最佳做法

本頁說明下列流程的最佳做法：建立新的 API 做為類型提供者來加入 Deployment Manager，或是將現有的 API 做為類型提供者來加入。

Deployment Manager 可讓您將 API 新增為類型提供者，以便將 API 資源公開為可在設定中呼叫的類型。如要以更輕鬆的方式完成此程序，請在設定或建立 API 時使用這些最佳做法。

建立新的 API

如果您打算建立要跟 Deployment Manager 整合的新 API，請使用以下的最佳做法。

使用標準的建立、讀取、更新和刪除 (CRUD) 方法，避免使用自訂方法

如有可能，請避免建立自訂方法，並盡量使用標準的 REST 方法，像是 GET、POST、PUT 和 DELETE 方法等。Deployment Manager 可辨認這些方法並由系統自動對應。

如為 Discovery API，您應根據下列的對應方式來命名您的 API 方法：

REST 方法 建議的 API 命名方式
POST create或insert
GET get
PUT update
DELETE delete

如為 OpenAPI 規格，您必須以與標準 REST 方法相同的方式為您的 API 方法命名。

使用可預測的資源路徑

針對 OpenAPI 規格，Deployment Manager 支援兩種能識別 REST 樣式介面的行為。第一種是資源所有的 REST 方法都屬於同一個資源路徑時：

/foo/{name}
  post:
  get:
  delete:
  put:

如果您必須將方法分開，請使用相同的資源路徑。舉例來說，下列範例參照相同的 /foo 資源，因此屬於有效的做法：

/foo/
  post:
/foo/{id}
  get:
  delete:
  put:

不過下列範例則為無效的做法，因為從 Deployment Manager 的觀點來看，此範例參照兩個不同的資源：

/foo/
 post:
/foo-bar/{id}:
 get:
 put:
 delete:

在極少數情況下，您可能會想要以如下所示的方式來命名資源路徑：

foo/create
  post:

foo/delete
  delete:

從 Deployment Manager 的觀點來看，由於無法識別符合 REST 樣式的介面，因此為無效的命名方式。

在整個介面中使用一致的命名方式

保持 POST 和 PUT 方法之間的輸入和路徑名稱相同。這項做法也適用於參數值，也就是讓不同方法之間的參數值語法保持相同。

例如，如果 POST 要求的要求內文含有名為 email 的參數，則請勿將 PUT 要求的同一項參數命名為 emailAddress。

POST
{
    “email”: “my-email”
}

PUT
{
    “email”: “my-email@gmail.com”
}

如果您必須新增這個類型的行為，請透過設定進階 API 選項來指示 Deployment Manager 應如何處理此行為。

另外，POST 和 PUT 方法的要求內文必須保持一致。如為 GET 和 DELETE 方法，路徑保持相同即可，這是因為系統會假設這些方法不含要求內文。

整合現有的 API

現有 API 的整合程序會因 API 的情況而有極大的差異，因此沒有一套具體的最佳做法可普遍套用到所有 API。以下清單是考慮整合現有 API 的方法時，可能有用的一般建議。

  • 針對非 REST 樣式的 API 使用 API 包裝函式。

    如果現有的 API 並非是符合 REST 樣式的 API，您可以建立 API 包裝函式，僅將 REST 方法公開。

  • 如果 API 大致上符合 REST 樣式，請識別並更新該 API。

    如果您的 API 幾乎符合 REST 樣式，且僅有一些非 REST 的行為，您可以透過更新 API 來解決這些行為。

  • 伺服器產生的值一律需要輸入對應。

    如果您的 API 具有由伺服器產生且 API 方法所需要的值，您必須設定輸入對應才能取得伺服器產生的值，並針對每個要求對應該值。

後續步驟