整合 API 的 API 需求

本文件說明對於要做為類型提供者加入 Deployment Manager 之 API 的一般要求。您可以透過這些準則來瞭解 Deployment Manager 所預期的 API 特性。如果您的 API 與此處說明的規範未完全相符，您可以使用進階 API 選項來解決這些不一致的問題。

API 包含有效的描述元文件

描述元文件可說明 API 及其資源。只有 OpenAPI 規格或 Google Discovery 描述元文件支援的 API 才能整合至 Deployment Manager。如需 OpenAPI 規格建立方式的完整資訊，請前往 OpenAPI GitHub 存放區。

API 描述元文件端點可供存取

Deployment Manager 會發出 HTTP 要求以取得 API 的描述元文件，因此請確保將描述元文件託管在 Deployment Manager 可以存取的位置。該位置可以是可公開存取的網址，或是受基本驗證保護的端點。

如果託管在某些 Google 服務上，API 接受基本驗證或 OAuth2

Deployment Manager 目前支援對託管在 Google Kubernetes Engine 或 Google Endpoints 上的某些 API 進行基本驗證 (使用者名稱和密碼) 及 OAuth 2.0 驗證，您可以設定驗證以使用專案的服務帳戶。

詳情請參閱建立類型提供者一文。

支援建立、讀取、更新、刪除 (CRUD) 作業

相關 API 必須是支援 CRUD 作業的 RESTful API。也就是說，有一些方法可以執行：

  • 建立作業：建立資源。須為 HTTP POST 要求。
  • 讀取作業：取得 API 資源的相關資訊。須為 HTTP GET 要求。
  • 更新作業：更新資源。須為 HTTP PUT 要求。
  • 刪除作業：刪除資源。須為 HTTP DELETE 要求。

僅支援部分 CRUD 作業的 API 還是可以運作，但其行為會視可用的作業而不同。

支援 GET 要求 支援 CREATE 要求 支援 UPDATE 要求 支援 DELETE 要求 是否有特殊的 API 行為？
是 是 是 是 無
是 是 是 否 使用者可以捨棄資源，但無法將其刪除。
是 是 否 是 對現有資源所做的任何變更都會失敗。使用者將需要刪除並重新建立資源才能將其更新。
是 是 否 否 上述兩種行為。
是 否 是 是 如果 API 不支援建立要求，使用者可以透過 ACQUIRE 政策更新部署作業，藉此將現有資源加入部署作業。
是 否 是 否 使用者可以取得資源，或在取得資源後進行更新，但無法刪除該資源。
是 否 否 是 使用者可以刪除資源及取得資源，也可以將現有資源加入部署作業。
是 否 否 否 使用者可以取得現有資源，或透過 ABANDON 政策將其移除。

所有路徑和查詢參數都能成功解析

API 的所有路徑和查詢參數必須做為資源主體的一部分存在，或者存在於 API 的所有方法中，以便 Deployment Manager 可以在使用者提供參數時進行比對。下列條件適用於路徑和查詢參數。

POST 的每項路徑/查詢參數都必須是 PUT 的參數

下列內容無效，因為 POST 有 myParameter，而 PUT 沒有：

POST  /my-api/{myParameter}/resource/{mySecondParameter}
PUT   /my-api/resource/{mySecondParameter}  # myParameter is not present

非 POST 方法的每項參數都必須存在於所有方法介面，或是隸屬於相關資源。如果這項參數是由伺服器產生，您就必須特別留意。

在最佳情況下，API 可能會如下所示 (所有方法都含有 name 參數)。

POST   /my-api/my-resource/{name}
PUT    /my-api/my-resource/{name}
GET    /my-api/my-resource/{name}
DELETE /my-api/my-resource/{name}

在另一種情況下，某個方法可能含有一個路徑參數欄位，但其他方法沒有這個路徑參數欄位。在這種情況下，該欄位應為 API 資源的一部分。例如：

POST  /my-api/my-resource ← the 'id' field  is not present on the POST request
GET   /my-api/my-resource/{id}

schema for my-resource
type: object
properties:
# id is part of the resource so Deployment Manager will use this value for
# POST requests after creation
  id:
    type: string

在這個範例中，我們假設 id 是伺服器產生的值，相關資源中包含這項參數，但發出 POST 要求時沒有這項參數。如果您必須具備 id 屬性才能向現有資源發出要求，但該項屬性不在資源中或無法透過路徑取得，則您在將 API 傳送至 Deployment Manager 時會發生問題。

細微的 API 行為需要額外的設定

某些 API 行為需要額外的 API 設定，才能將 API 與 Deployment Manager 整合在一起。這些行為包括：

  • 伺服器產生的值：某些 API 資源含有伺服器產生的屬性，這些屬性會在每次要求發出後或 API 中發生特定事件時改變。您可以使用進階 API 選項，指示 Deployment Manager 在每次發出要求後取得這個新的值。

    舉例來說，API 可能需要先取得資源的最新指紋屬性，才會核准更新要求。您可以使用進階 API 選項，在每次使用者利用這個值發出部署作業更新要求時，指示 Deployment Manager 取得該值。

  • 操縱使用者輸入：舉例來說，如果您的 API 要求某個欄位的值一律須以專案 ID 當做前置字串，您可以使用輸入對應來自動新增該項資訊，而不必強迫使用者手動新增前置字串。

  • 會隨著每種方法變更的欄位值：對於會重複使用同一個欄位但採用不同值的方法，您可以使用 API 選項來指示 Deployment Manager 何時要使用哪個值。

詳情請參閱設定進階 API 選項一文。

後續步驟