百积木文档
DevelopmentBundle development

Hosted Service Capability 列表

先发现当前环境的可用能力,再选择提供方查询方法及请求响应合同。

Hosted Service 能力来自当前环境登记的提供方。先查看能力列表,选择提供方,再查看该能力的方法;能力和方法名称都不写死在 CLI 中。

能力列表

下列页面是各提供方维护的合同快照,用于阅读和开发参考。实际可用能力及版本始终以当前环境的查询结果为准。

能力协议方法目录合同快照
Browser Session CapabilityHTTPbrowser-session2.2.1
Database CapabilityMYSQL、POSTGRESQLdatabase1.0.0
Workflow Worker CapabilityHTTPworkflow3.0.0
bundle-runtimeHTTPbundle-runtime2.0.0
bundle-workflowHTTPbundle-workflow2.0.0
bundle-timerHTTPbundle-timer2.0.0

1. 查看当前可用能力

baijimu hosted-service capability list --workspace-id <workspaceId> --project-id <projectId>

结果包含 providerId、providerKey、capabilityType、name、scopeType、bindingSupported。--project-id 可选;指定后只返回该项目可见的全局、工作区和项目提供方。只列出已启用的提供方。 同一能力类型可以有多个提供方,必须使用本次列表返回的 providerId 明确选择。列表不包含内部地址、提供方凭据或配置。

2. 查看所选能力的方法

baijimu hosted-service capability get --workspace-id <workspaceId> --project-id <projectId> --provider-id <providerId>
baijimu hosted-service capability methods list --workspace-id <workspaceId> --project-id <projectId> --provider-id <providerId>

get 返回能力的完整 OpenAPI 合同,包含说明和协议;methods list 返回 operationId、HTTP 方法、相对路径和用途,可用 --keyword 筛选。数据库驱动等非 HTTP 能力的方法列表可以为空,应按能力说明使用对应协议。

3. 查看方法定义

baijimu hosted-service capability methods get <operationId> --workspace-id <workspaceId> --project-id <projectId> --provider-id <providerId>

返回所选方法的 OpenAPI 定义及其引用的 components:请求参数、请求体、响应状态、响应 Schema、鉴权要求。支持绑定的能力,方法路径拼接在绑定解析所得 baseUrl 后;声明 x-baijimu-base-url-source: platform-api 的能力使用当前连接环境的平台 API 根地址。凭据必须来自该提供方的授权流程;目录可见不等于具备执行权限。 发现 API 使用 CModel,先检查 errorCode。实际业务调用是否使用 CModel,由对应方法合同决定。提供方不可用、合同不匹配或方法不存在时直接报告查询失败,不使用文档快照代替环境响应。

提供方如何扩展

通过 Hosted Service 的 config-provider 注册接口登记提供方及其可见范围。resolverKind: capability-http 在已登记 endpointUrl 上以 GET 返回 OpenAPI 3.1.0,以 POST 处理绑定解析;resolverKind: capability-discovery-http 仅通过 GET 提供方法合同,可指向提供方的不可变合同发布物,不能用于配置绑定。配置绑定列表仅返回支持绑定的提供方,能力发现列表包括两种类型。Hosted Service 按目录读取并校验合同,不保存另一份方法目录。 合同必须声明 info.title、严格 SemVer info.version、info.description、与登记项相符的 x-baijimu-capability-type、x-baijimu-protocols、paths 和 components。每个操作声明唯一 operationId、summary、description、parameters、responses、security,需要请求体时声明 requestBody。路径参数放在各操作的 parameters 中。 文档和单个方法响应不得包含真实服务地址、Token、密码或租户数据。提供方请求不跟随重定向,合同最多 2 MiB;身份匹配和合同校验失败会使查询失败。扩展提供方不要求修改 Hosted Service 或 CLI 的能力名单。

Bundle Runtime、Bundle Workflow、Bundle Timer 也通过上述目录发现;Hosted 通过 Bundle Capability 受管绑定 自动获得配置和凭据。方法发现与受管绑定分别执行;调用合同见Bundle Capability 方法参考。

本页内容