將 API 新增為類型提供者

本頁面說明如何將 API 新增至 Google Cloud Deployment Manager 來當做類型提供者。如要進一步瞭解類型和類型提供者，請參閱類型總覽說明文件。

類型提供者會向 Deployment Manager 公開第三方 API 的所有資源，做為您可以在設定中使用的基礎類型。這些類型必須由支援建立、讀取、更新和刪除 (CRUD) 作業的 REST 樣式 API 直接提供。

如要使用 Deployment Manager 存取非 Google 自動提供的 API，您必須將該 API 新增為類型提供者。只要 API 具備 OpenAPI 規格 (先前稱為 Swagger©) 或 Google Discovery 文件，您即可將其新增為類型提供者。

這份說明文件不會介紹如何自行建立 API 服務，因為文章假設您已經有要新增的 API，或是您已建立正在執行、可以從公開端點存取的 API。舉例來說，如要使用 Endpoints 部署範例 API，請參閱 Cloud Endpoints 快速入門導覽課程。 Google Cloud

事前準備

類型提供者元件

類型提供者由下列元件組成：

  • 名稱：屬意的類型提供者名稱，用於指稱類型及其相關 API 資源。
  • 描述元文件：該類型的描述元文件網址。系統支援的文件包括 Google Discovery 文件或 OpenAPI 1.2 規格。
  • 驗證：API 需要的驗證憑證。您可以指定基本驗證。如果 API 是在 Cloud Endpoints 或 Google Kubernetes Engine (GKE) 上執行，您也可以使用專案的服務帳戶憑證做為驗證。
  • 進階選項：任何進階輸入對應或 API 選項。

名稱

類型提供者的名稱。在未來的設定和範本中，您會使用這個名稱來指稱類型。舉例來說，如果您建立了名為 my-awesome-type-provider 的類型提供者，就能在後續的範本中按照下列方式予以使用：

resources:
  name: a-deployment
  type: my-project/my-awesome-type-provider:some-collection
  properties:
  …

其中的 my-project 為該類型所屬專案的 ID，some-collection 則是待建立 API 資源的路徑。

描述元文件

類型提供者的描述元文件可為 OpenAPI 1.2 或 2.0 規格；或是 Google Discovery 文件。例如，下列網址提供的 Compute Engine Beta API 的 Google Discovery 文件：

https://content.googleapis.com/discovery/v1/apis/compute/beta/rest

詳情請參閱 Google Discovery 文件完整清單。

描述元文件也接受 OpenAPI 1.2 和 OpenAPI 2.0 文件。

驗證

如果您的 API 必須通過驗證，您可以在此處提供驗證詳細資料。Deployment Manager 支援基本驗證憑證，例如使用者名稱和密碼。如果是 Google Kubernetes Engine 和 Google Cloud Endpoints，您可以使用 Authorization 標頭提供專案服務帳戶的存取權杖。

如要指定基本驗證憑證，請在 credentials 區段中提供使用者名稱和密碼：

credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

您只需要在第一次建立類型提供者時指定使用者名稱和密碼。

如果您在與 Deployment Manager 相同的專案中，有執行 Google Kubernetes Engine (GKE) 的叢集，可以將該叢集新增為類型提供者，並透過 Deployment Manager 存取 GKE API。在這種情況下，您可以取得專案的 Google API 服務帳戶 OAuth 2.0 存取權杖，並在 Authorization 標頭中提供存取權杖。有別於上述的憑證區段，您必須在要求中以輸入對應的形式提供這項資訊：

- fieldName: Authorization
  location: HEADER
  value: >
    $.concat("Bearer ", $.googleOauth2AccessToken())

使用者呼叫該類型提供者時，googleOauth2AccessToken() 方法會自動取得存取憑證。如需完整範例，請參閱 GKE 叢集和類型範例。

您可以使用相同方法驗證 Google CloudEndpoints。

(選用) 自訂憑證授權單位根目錄

如要將 API 新增為 Deployment Manager 的類型供應商，但該 API 的 HTTPS 端點使用非公開信任的憑證授權單位 (CA) 提供的憑證來加密連線，您可以按照下列範例，將 API 新增至設定：

customCertificateAuthorityRoots:
- $(ref.my-gke-cluster.masterAuth.clusterCaCertificate)

其中 my-gke-cluster 是您使用的 GKE 叢集。 如需詳細範例，請參閱 GKE 供應商叢集範例。

進階類型選項

有些 API 可能具有某種特性，讓 Deployment Manager 難以將 API 的所有屬性對應至 Deployment Manager。在理想情況下，您提供描述元文件，Deployment Manager 就會自動找出 API 要求路徑及相關 API 屬性，不需要額外操作。儘管 Deployment Manager 可以解讀大多數 API，不過如果 API 較為複雜，您可能需要明確為行為較不明顯的 API 指定輸入對應。

如要進一步瞭解輸入對應，請參閱進階 API 選項說明文件。

建立類型提供者

如要建立類型提供者，請向 Deployment Manager 提交要求，並在要求酬載中加入所需的類型提供者名稱、描述元網址和任何必要的驗證憑證。

gcloud

如要使用 gcloud CLI 建立類型提供者，請使用 type-providers create 指令：

gcloud beta deployment-manager type-providers create [TYPE_PROVIDER_NAME] --descriptor-url=[URL]

其中：

  • [TYPE_PROVIDER_NAME] 是您要為這個類型指定的名稱。

  • [URL] 是連結至支援這個類型的描述元文件的完整網址。例如：

    http://petstore.swagger.io/v2/swagger.json

如要提供驗證憑證或進階 API 選項，您可以建立以 YAML 編寫的 API 選項檔案，並透過 --api-options-file 旗標提供該檔案。檔案範例如下所示：

collectionOverrides:
- collection: /emailAddresses/v1beta/people
  options:
    inputMappings:
    - methodMatch: ^create$
      fieldName: emailAddress.displayName
      value: $.resource.properties.displayName
      location: BODY
    - methodMatch: ^update$
      fieldName: displayName
      value: $.resource.properties.displayName
      location: PATH
    virtualProperties: |
      schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        displayName:
          type: string
      required:
      - displayName
credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

gcloud 指令如下：

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url]

如要使用自訂憑證授權單位 (CA) 進行驗證，可以將 CA 新增為 gcloud 指令的標記，如下列範例所示：

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url] \
    --custom-certificate-authority-roots=[CA_NAME]

API

如要透過 API 建立基礎類型，請提交 POST 要求，並在要求內文中加入 descriptorUrl 和選用的設定選項。例如：

POST https://www.googleapis.com/deploymentmanager/v2beta/projects/[PROJECT_ID]/global/typeProviders

{ "description":"",
  "descriptorUrl":"https://www.example.com/api/v1beta1.json",
  "name":"my-type-provider",
  "collectionOverrides":[
    {
      "collection":"emailAddresses/v1beta/people",
      "options":{
        "inputMappings":[
          {
            "fieldName":"emailAddress.displayName",
            "location":"BODY",
            "methodMatch":"^create$",
            "value":"$.resource.properties.displayName"
          },
          {
            "fieldName":"displayName",
            "location":"PATH",
            "methodMatch":"^update$",
            "value":"$.resource.properties.displayName"
          }
        ],
        "virtualProperties":"schema: http://json-schema.org/draft-04/schema#\ntype: object\nproperties:\n  displayName:\n    type: string\nrequired:\n- displayName\n"
      }
    }
  ],
  "credential":{
    "basicAuth":{
      "password":"example-password",
      "user":"example-user"
    }
  }
}

詳情請參閱 insert 方法的說明文件。

測試類型提供者

如要針對您的類型提供者驗證其類型是否如預期運作，請依照下列步驟操作：

  1. 在設定中呼叫新的類型提供者。
  2. 部署由類型提供者提供的每個集合，以確認 API 正常運作。集合是指定類型提供者的 API 資源。
  3. 更新每個集合。
  4. 刪除各個集合。

將類型提供者的類型實例化時，使用者實際上是向 Deployment Manager 提交要求，而非明確地向基礎 API 提交要求。接著，Deployment Manager 會依據使用者提供的資訊建立要求，並代表使用者向 API 提交要求。在這項程序中，最常見的問題可能是 API 含有 Deployment Manager 難以自動辨識的屬性。例如，某些 API 需要的屬性只能從 API 回應中擷取。其他的 API 可能使用相同欄位名稱，但根據作業內容採用了不同的值。在這類情況下，您就需要明確指示 Deployment Manager 如何處理這類情況。

如果您的 API 具有任何相似特徵，請使用輸入對應為 Deployment Manager 釐清模稜兩可的情況。

後續步驟

© 2016 Swagger 保留所有權利。