使用流程

本文介绍集成中心的通用使用流程，包括如何创建集成、调用集成函数、查看运行状态、修改配置以及删除集成。具体集成类型（如微信支付）的接入细节请参考对应集成的接入指南。

准备工作

使用集成中心前，请确认：

已开通云开发 CloudBase 环境
当前账号在该环境下具有「集成管理」与「云函数管理」权限
已准备好待接入第三方服务所需的凭证（如商户号、API Key、证书等），具体清单以集成详情为准

创建集成

1. 进入集成中心

登录云开发控制台后，左侧菜单选择 模板与集成 → 集成中心，或直接访问集成中心首页。

页面会展示已上架的所有集成类型，按类别分组（支付、公众号、AI、消息等）。

2. 选择集成类型

点击目标集成卡片（如「小程序微信支付」），进入集成详情页。详情页会展示：

能力说明：该集成提供哪些功能、覆盖的第三方接口范围
接入文档链接：完整的接入步骤与示例代码
创建集成入口：右上角的「创建集成」按钮

3. 填写集成信息

点击「创建集成」后，按表单填写：

集成名称：自定义标识，建议使用小写字母 + 连字符（如 miniapp-wxpay）。该名称将作为生成的云函数名前缀。
凭证字段：根据集成类型不同而不同（如商户号、APIv3 密钥、证书内容等）。每个字段会有提示说明取值出处。
可选高级配置：部分集成支持回调路径自定义、调试模式开关等。

提交前请仔细核对，特别是 PEM 格式的证书与密钥——粘贴时容易出现换行被替换为空格、首尾行缺失等问题，导致后续调用失败。

4. 等待资源创建完成

提交后，平台会异步完成以下操作（约 1–2 分钟）：

资源	说明
HTTP 云函数	函数名形如 `<集成名>-<随机串>`，模板代码已预置
环境变量	凭证、回调地址等以环境变量形式注入函数
回调域名	形如 `https://<集成标识>.integration-callback.tcloudbase.com`
回调路由	各类异步通知的接收路径（如 `/wechatpay/order`）

创建完成后，集成详情页会展示上述所有资源的实际值，复制即可使用。

调用集成函数

集成函数本质上是一个 HTTP 云函数，可通过以下任一方式调用：

方式一：小程序 `wx.cloud.callHTTPFunction`（推荐用于小程序）

平台自动注入用户身份（x-wx-openid / x-wx-appid），无需登录、无需 Token：

wx.cloud.init({ env: 'your-env-id' })

wx.cloud.callHTTPFunction({
  name: 'miniapp-wxpay-rwmx67sc',     // 实际函数名（创建后查看）
  config: { env: 'your-env-id' },
  method: 'POST',
  header: { 'Content-Type': 'application/json' },
  path: '/wx-pay/wxpay_order',         // Express 标准路由
  data: { /* 业务参数 */ },
  success: (res) => console.log(res.data),
  fail: console.error,
})

小程序基础库版本需 ≥ 3.15.2。

方式二：CloudBase Web SDK（推荐用于 Web/H5）

使用 Bearer Token 调用云 API 网关：

import cloudbase from '@cloudbase/js-sdk'

const app = cloudbase.init({ env: 'your-env-id' })
const auth = app.auth({ persistence: 'local' })
// ⚠️ 必须使用「认证登录」（邮箱、手机号、自定义登录等），匿名登录无权调用云函数
const accessToken = (await auth.signIn({ /* ... */ })).credential.accessToken

const res = await fetch(
  `https://your-env-id.api.tcloudbasegateway.com/v1/functions/miniapp-wxpay-rwmx67sc?webfn=true`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({ /* 业务参数 */ }),
  }
)
const body = await res.json()

方式三：服务端 SDK / HTTP 调用

后端服务调用集成函数与调用普通 HTTP 云函数一致，参考 HTTP 访问服务文档。

处理回调

第三方服务的异步通知（如支付结果、消息推送）会先到达集成中心提供的回调域名，集成中心完成验签 + 解密后，将明文转发到云函数的特定路由（如 /wechatpay/order）。

业务侧只需在云函数代码的对应路由中处理明文数据：

// pay-common/services/orderService.js（节选）
async function handlerUnifiedTrigger(params) {
  // params 已经是验签解密后的明文
  // - params.out_trade_no
  // - params.transaction_id
  // - params.amount.total
  // - params.payer.openid
  
  // 1. 幂等校验：检查订单是否已处理过
  // 2. 金额核对：与下单时的金额一致
  // 3. 状态原子更新：PENDING → PAID
  // 4. 触发业务副作用：发货、积分、通知等
  
  return { code: 'SUCCESS' }   // 必须 5 秒内返回
}

回调处理需遵循的原则：

快速返回：5 秒内返回成功响应，否则触发第三方重试
幂等性：同一回调可能被重复投递，必须保证多次执行结果一致
金额/签名核对：除集成中心已做的验签外，业务侧仍建议核对关键字段
耗时操作异步化：发货、推送、外部 API 调用等异步派发到队列或定时任务

查看与管理集成

查看集成列表

集成中心首页 → 「我的集成」标签页，可查看当前环境下所有已创建的集成，包括：

集成名称与类型
创建时间、状态（运行中 / 配置错误 / 已停用）
关联的云函数名

查看集成详情

点击任一集成名称进入详情页，可查看：

基本信息：名称、类型、创建时间
关联资源：云函数、回调域名、回调路径
环境变量速查：当前注入到函数的所有环境变量（凭证字段会脱敏显示）
回调日志：最近的回调记录，包括来源、状态、耗时、错误码

修改集成配置

详情页右上角「编辑」按钮可修改集成参数。保存后平台将自动重新部署云函数，约 1–2 分钟后新配置生效。

常见的修改场景：

凭证轮换（如 APIv3 密钥到期更新）
切换证书模式 ↔ 公钥模式
添加可选字段（如转账场景的 service_app_id）

⚠️ 修改期间正在进行的请求可能受影响，建议在低峰期操作。

查看运行日志

集成函数本质是云函数，可通过以下方式查看运行日志：

控制台 → 云函数 → 找到对应函数 → 「日志」标签页
命令行：tcb fn log <函数名> --tail

回调日志在集成详情页有专门的查看入口，包含验签状态等集成层信息。

修改集成函数代码

集成创建时生成的云函数代码是模板，业务侧通常需要补齐业务逻辑（如订单入库、回调处理）。修改方式：

方式一：通过 CLI 下载并部署

# 下载云函数源码
tcb fn code <函数名> --download

# 修改后部署
tcb fn deploy <函数名>

方式二：通过控制台在线编辑

控制台 → 云函数 → 找到对应函数 → 「函数代码」→ 在线编辑器修改后保存部署。

⚠️ 不要修改环境变量或集成中心注入的配置文件——下次集成中心重新部署时会被覆盖。仅修改业务逻辑代码（如 services/orderService.js）。

删除集成

不再使用的集成可在详情页右上角「删除」按钮移除。删除时会：

删除关联的云函数
释放回调域名（不可恢复）
清除所有环境变量

⚠️ 删除前请确认：

已撤销第三方平台对该集成回调地址的依赖（如商户平台的支付通知 URL 已切换或停用）
业务侧已停止调用该集成函数
必要的运行日志已备份

常见问题

Q1：集成创建失败，提示凭证校验未通过

通常是凭证字段填写错误。检查：

字段值是否完整（特别是 PEM 格式：-----BEGIN ...----- 与 -----END ...----- 头尾完整、中间换行未被破坏）
凭证类型是否匹配（如微信支付公钥模式与平台证书模式不能混用）
关联应用（如小程序 AppID）是否已与商户号绑定

Q2：集成函数调用返回 401

调用方未提供合法的 accessToken 或 openid：

小程序场景：确认 wx.cloud.init 已执行、用户已登录微信
Web 场景：accessToken 必须来自认证登录（匿名登录的 token 无权调用云函数）

Q3：第三方异步通知未触发业务函数

按以下顺序排查：

第三方平台的回调 URL 是否填写为集成中心生成的地址
集成详情页「回调日志」中是否有对应记录
若回调日志显示验签失败：核对凭证一致性
若回调已转发到函数：查看函数日志确认业务代码是否报错

Q4：能否同时创建多个同类型集成

可以。例如可以创建多个微信支付集成，分别服务不同的小程序或商户号。每个集成生成独立的云函数与回调地址。

Q5：集成函数能否被其他云函数调用

可以。集成函数本质是 HTTP 云函数，可通过 tcb.callFunction / tcb.callContainer 等方式互相调用。详见云函数文档。

下一步

阅读具体集成的接入指南（如小程序接入微信支付）
在集成中心控制台创建第一个集成
了解云函数的开发与调试

准备工作​

创建集成​

1. 进入集成中心​

2. 选择集成类型​

3. 填写集成信息​

4. 等待资源创建完成​

调用集成函数​

方式一：小程序 wx.cloud.callHTTPFunction（推荐用于小程序）​

方式二：CloudBase Web SDK（推荐用于 Web/H5）​

方式三：服务端 SDK / HTTP 调用​

处理回调​

查看与管理集成​

查看集成列表​

查看集成详情​

修改集成配置​

查看运行日志​

修改集成函数代码​

方式一：通过 CLI 下载并部署​

方式二：通过控制台在线编辑​

删除集成​

常见问题​

Q1：集成创建失败，提示凭证校验未通过​

Q2：集成函数调用返回 401​

Q3：第三方异步通知未触发业务函数​

Q4：能否同时创建多个同类型集成​

Q5：集成函数能否被其他云函数调用​

下一步​