集成 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 Endpoint 的某些 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 的参数

以下代码无效，因为 myParameter 存在于 POST 中，但不存在于 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 发出更新部署请求时获取此值。

  • 操控用户输入：例如，如果您的 API 要求字段的值必须始终以项目 ID 为前缀，则可以使用输入映射自动添加该信息，而不是强制用户手动添加它。

  • 随每种方法变化的字段值：对于重复使用相同字段但具有不同值的方法，可以使用 API 选项向 Deployment Manager 说明何时使用哪个值。

如需了解更多信息，请参阅设置高级 API 选项。

后续步骤