#Connector API

#概述

在集群中集成工具后，可以为当前 Connector 提供一个 RESTful API，方便从工具中获取资源。这些 API 统一通过 Connector API 暴露，使用户能够从当前 Connector 所指向的工具中获取资源。

Connectors 系统支持通过 API 访问工具资源的两种方式：

• Original Tool API：通过 Proxy Service 访问工具的原始 API
• Custom API：使用为 ConnectorClass 提供的自定义 API

使用 Connectors API 时，客户端无需管理工具的原始认证凭据，只需要拥有访问 Connector 的权限即可。对于工具的 API 请求权限，由 Connector 中配置的凭据（Secret）权限决定。

#Connector API 地址与认证

#API 地址

Connector API 地址由三部分组成：

• Platform API 或集群 ingress 访问入口
• Connector API 相对路径
• 请求的工具原始 API 路径或自定义 API 路径

在集群中创建 Connector 后，Connector 会自动将当前 Connector 的 API 路径记录到 <connector>.status.api.path 中。请注意，该路径是相对于集群访问入口的相对路径。

最终的 Connector API 地址为：{platform_api_address}/{<connector>.status.api.path}/{api-path}

#认证与授权

认证遵循 Kubernetes 认证标准，并通过 Kubernetes 的认证和授权机制完成。请求用户必须拥有对应 Connector 的读取权限。目前仅支持 Bearer Token 认证。

在向工具发起最终请求时，将使用 Connector 指定的 Secret 信息进行认证。

默认情况下，当 enable-connector-apis-permissions 被禁用时，仅需拥有 Connector 的读取权限即可调用 Connectors API。 当 enable-connector-apis-permissions 被启用时，系统会对目标 Connector 额外执行一次 connectors/apis 权限检查。该额外能力权限用于区分 Connector 发现与实际 API 使用。

关于整体模型以及 connectors/apis 的含义，请参见 Connectors Permission Model。

有关 Kubernetes API 认证的更多信息，请参阅 Kubernetes Authentication documentation。

#访问原始工具 API

当你的 ConnectorClass 提供了 Proxy Service 能力时，可以通过 Connector API 直接访问工具的原始 API。

例如，如果工具的原始 API 地址为 /api/v4/projects，则可以通过 Connector API 访问。假设你在 default 命名空间中有一个名为 gitlab-connector 的 Connector，且该 Connector 的 API 路径为 /connectors/v1alpha1/default/gitlab-connector/path，请求如下：

K8S_TOKEN=xxxx

curl -H "Authorization: Bearer ${K8S_TOKEN}" "https://platform.example.com/connectors/v1alpha1/default/gitlab-connector/path/api/v4/projects"

Proxy Service 能力可以通过 ConnectorClass 规范进行配置。有关配置细节，请参见 ConnectorClass Proxy。如需更深入地理解 Connectors Proxy 概念，请参见 Connectors Proxy。

#使用 x-openapi-address 选择后端地址

当 OpenAPI operation 使用 x-provider-type: proxy 时，可以选择性地设置 x-openapi-address，以控制请求应使用哪个后端地址。

支持的选择方式如下：

• 为空或未设置：回退到 Connector.spec.address
• 扩展名称：通过 name 从 Connector.spec.addressExtensions 中解析
• 直接地址：完整的 http/https URL

示例：

spec:
  api:
    openapi:
      openapi: "3.0.1"
      paths:
        /repos/{owner}/{repo}/pulls:
          get:
            x-provider-type: proxy
            x-openapi-address: api
        /search/code:
          get:
            x-provider-type: proxy
            x-openapi-address: https://api.github.com

在此示例中：

• /repos/{owner}/{repo}/pulls 使用名为 api 的 connector 扩展。
• /search/code 使用直接 URL https://api.github.com。
• 如果省略 x-openapi-address，请求将使用 Connector.spec.address。

如果 x-openapi-address 引用了不存在的扩展名称或无效的直接 URL，请求将被拒绝。

#自定义 API

当工具的原始 API 不能满足你的需求，或者 ConnectorClass 不提供 Proxy Service 能力时，可以为当前 ConnectorClass 提供一个自定义 API service 以满足需求。

自定义 API service 可以通过 ConnectorClass 的 spec.api 字段进行配置，从而使 Connectors 系统能够发现并使用它。有关配置细节，请参见 ConnectorClass API。

此外，为了让系统识别该 API 是自定义 API，需要通过 spec.api.openapi 字段配置 OpenAPI 描述。

#API 定义

#API 路径

自定义 API 提供的 API 路径可以在扩展 API service 中自由定义。推荐格式为 /<connectorclass-name>/xxx。

结合上文介绍的 API 地址和认证方式，下面是一个请求示例。假设你在 default 命名空间中有一个名为 git-connector 的 Connector，且自定义 API 路径为 /git/gitrefs，请求如下：

K8S_TOKEN=xxxx

curl -H "Authorization: Bearer ${K8S_TOKEN}" "https://platform.example.com/connectors/v1alpha1/default/git-connector/path/git/gitrefs"

#查询参数

查询参数由具体的 ConnectorClass API Specification 决定。

#分页

分页信息通过查询参数表示：

#响应格式

当返回列表时，响应结构如下：

{
    "listMeta":{
        "totalItems":0
    },
    "items": [
        {

        }
    ]
}

当响应不是 200 时，返回的数据结构应符合 k8s status。

例如：

{
    "status": "Failure",
    "message": "api address of connectorclass 'git-noapi' is not resolved",
    "reason": "BadRequest",
    "code": 400,
    "details": null
}

字段定义和枚举值与 k8s status 保持一致。

#OpenAPI 描述

除了提供自定义 API service 之外，还需要在 ConnectorClass 的 spec.api.openapi 字段中配置 OpenAPI 描述信息，以便系统识别该 API 是自定义 API。

示例：

kind: ConnectorClass
metadata:
  name: gitlab
spec:
  api:
    ref:  # Reference to the custom API service
      name: connectors-gitlab-api
      namespace: connectors-system
    openapi:
      openapi: "3.0.1"
      info:
        title: GitLab Custom API
        version: "1.0.0"
      paths:
        /gitlab/custom-api:  # Custom API defined in the connectors-gitlab-api service
          get:
            x-provider-type: api  # Indicates this API is a custom API
            summary: Request custom API
            responses:
              "200":
                description: Custom API response

系统会根据 spec.api.openapi 描述，自动将自定义 API 转发到 ConnectorClass API Address。

有关 spec.api.openapi 的配置细节，请参见 ConnectorClass OpenAPI Description。如需更多使用示例，请参见 Using Connectors API in Dynamic Forms。

#ConnectorClass API 扩展规范

开发者可以扩展 ConnectorClass 的 API 能力，为用户提供更丰富的资源获取能力。

请参见 ConnectorClass API Extension Specification。

#在动态表单中使用 Connectors API

Connector API 可以提供给 UI 客户端，尤其适用于动态表单场景，在该场景下 UI 客户端可以灵活配置要调用的 API 请求。

为实现这一点，需要通过 ConnectorClass 的 spec.api.openapi 字段配置 OpenAPI 描述信息，该描述与动态表单 DSL 配合使用，以实现前端动态表单渲染。

动态表单描述通常在 Resource Interface 中提供。更多详情，请参见 Resource Interface。

#Connectors Operator API

Connectors Operator API 是 Connectors API 提供的一组 RESTful API，用于让用户获取 Connector 相关信息。

API 路径为 {platform_address}/clusters-rewrite/{cluster_name}/connectors-operator/{api-path}。

当前提供的 API 包括：

• GET /connectors-operator/featureflags：返回当前集群中 Connectors 系统的 feature flags 信息

  响应体示例：

  {
     "enable-connector-apis-permissions": "false",
     "enable-connector-proxy-permissions": "false",
     "enable-connectors-approval": "false",
     "enable-multi-connector": "false"
  }

  权限要求：需要具备访问 ConnectorClass 的权限。

  关于每个 feature flag 的含义及其配置方式，请参见 Feature Flags。

#下一步

• Connectors Permission Model
• Connector Resource Levels and Permissions
• Connectors Proxy
• Feature Flags