百积木文档
开发指南Bundle 生命周期插件开发

最小示例:通过 Adapter 校验业务配置

使用一个受保护的业务回调理解 Adapter 接入,不在业务代码中拼装平台生命周期或引用协议。

普通 Bundle 组合资源时不需要插件。本例用于已有外部业务后端希望接入生命周期的开发者:公共 Adapter 承担平台协议、握手、凭据轮换和资源授权,业务后端只处理业务合同 1.0.0。直接实现平台协议的 Rust 开发者使用同一个公开 SDK 入口,见直接实现插件协议。

本例做什么

完整 Python 示例只校验 message 配置,在前后两个资源阶段返回 VERIFIED。它没有外部实例和持久状态,因此 INSTALL、UPGRADE、CONFIGURE、DETACH 都不会创建、删除或重放业务资源。 实际开通租户、迁移数据或释放资源时,业务后端必须另外实现完整安装归属、事务幂等和执行顺序校验。

使用标准 Python 运行,不安装额外依赖:

python3 server.py

启动前由自己的 Hosted Service 配置提供 APP_ENDPOINT_LIFECYCLE_PORT,由受控 Secret 提供 ADAPTER_BUSINESS_TOKEN;不把凭据写入示例、Git 或 Bundle。入口固定为本程序的 POST /execute, 正式 HTTPS 地址从部署 Endpoint 返回,不根据项目 ID 拼接。 Adapter 的业务地址和业务 Token 配置成该入口及对应受保护调用凭据。

完整业务请求

以下身份仅为解释结构的测试数据。正式调用中 context 和资源来源都由 Adapter 从已验证的生命周期请求交付, 开发者不填写真实安装身份,也不解析或持久化回调 context.token。

{
  "contractVersion": "1.0.0",
  "context": {
    "token": "example-callback-scope",
    "pluginId": "example-plugin",
    "installation": {
      "environmentKey": "consumer",
      "applicationRuntimeId": "runtime-a",
      "workspaceId": 42,
      "bundleInstallId": "installation-a",
      "installedBy": 25,
      "bundle": {"environmentKey": "publisher", "bundleId": "example"}
    },
    "operation": {
      "operationId": "operation-a",
      "operationType": "CONFIGURE",
      "currentVersion": "1.0.0",
      "targetVersion": "1.0.0"
    },
    "stage": "BEFORE_RESOURCES",
    "executionSequence": 1
  },
  "configuration": {"schemaVersion": "1.0.0", "values": {"message": "hello"}},
  "resources": {}
}

成功响应:

{
  "contractVersion": "1.0.0",
  "errorCode": "0",
  "data": {"contractVersion": "1.0.0", "outcome": "VERIFIED", "resources": {}}
}

示例使用业务服务自有的 BUSINESS_UNAUTHORIZED、BUSINESS_INVALID_CONFIGURATION 错误码;正式项目 按自己的错误目录维护。HTTP 200 仍须检查 errorCode。Adapter 负责重新组装平台响应的关联字段;业务后端 不返回 installation、operation、stage 或 executionSequence。

从示例到真实接入

  1. 部署业务 Endpoint,验证独立业务凭据与非法配置会被拒绝。
  2. 独立部署、配置 Adapter 后端和提供方 Runtime,完成受管握手与引导变量清理。
  3. 在业务 Bundle 顶层绑定插件,配置 message,资源读写范围按实际需要明确声明。
  4. 创建精确版本并在目标 Runtime 安装,执行真实配置操作,回读业务结果及 Owner 当前资源。
  5. 按交付验收记录精确程序、制品、部署及业务证据。

示例通过不证明通用 Adapter 已在你的环境部署;接入顺序和全部验收见 首次接入流程与验收。

本页内容