此页面由 Cloud Translation API 翻译。

将 API 添加为类型提供程序

本页面介绍如何将 API 添加到 Google Cloud Deployment Manager 作为类型提供程序。要详细了解类型和类型提供程序，请阅读类型概览文档。

类型提供程序将第三方 API 的所有资源公开给 Deployment Manager，作为可在配置中使用的基本类型。这些类型必须由支持创建、读取、更新和删除 (CRUD) 的 RESTful API 直接提供。

如果您想要使用不是由 Google 通过 Deployment Manager 自动提供的 API，则必须将该 API 添加为类型提供程序。只要 API 有 OpenAPI 规范（以前称为 Swagger^©）或 Google Discovery 文档，您就可以将任何 API 添加为类型提供程序。

本文档未介绍如何建立您自己的 API 服务。我们假设已有一个您想添加的 API 或者您已创建了一个可以从公共端点访问的正在运行的 API。例如，要使用 Google Cloud Endpoints 部署示例 API，请按照 Cloud Endpoints 快速入门执行操作。

准备工作

如果要使用本指南中的命令行示例，请安装 “gcloud” 命令行工具。
如果希望使用本指南中的 API 示例，请设置 API 访问权限。
如果要使用本指南中的 API 示例，请设置 v2beta API 访问权限。

类型提供程序的组成部分

类型提供程序包括：

名称：类型提供程序所需的名称。您将利用此名称来引用类型及其相关的 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 集群和 Type 示例。

您可以用同一方法对 Google Cloud Endpoints 进行身份验证。

（可选）自定义证书授权机构根

如果要将 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 属性，您无需执行额外的工作。对于较复杂的 API，Deployment Manager 可以理解大多数 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 方法的文档。

测试类型提供程序

要验证类型提供程序类型是否可以按预期正常运行：

在配置中调用新类型提供程序。
部署类型提供程序提供的每个集合，确保 API 按预期正常运行。集合是来自指定类型提供程序的 API 资源。
对每个集合进行更新。
删除每个集合。

当用户对类型提供程序中的类型进行实例化时，实际上是在向 Deployment Manager 发出请求，而不是明确地请求底层 API。Deployment Manager 会利用提供的信息创建请求，并代表用户将其发送给 API。您可能注意到的最常见问题是 API 具有 Deployment Manager 难以自动识别的属性。例如，某些 API 需要只能从 API 响应中提取的属性。其他 API 可能使用具有不同值的相同字段名称，具体依操作而定。这些情况下，您需要明确告知 Deployment Manager 如何处理这些情况。

如果您的 API 具有任一上述特征，请使用输入映射为 Deployment Manager 澄清歧义。