通过一次异步调用,对许多已连接用户执行写入或大型导出。你提交一个作业,轮询其状态,并(对于导出和写入)下载结果文件。在一次调用中对你已连接的用户运行批量操作。与同步读取(获取批量余额、获取批量交易)不同,
submitBulkOperation 是异步的:它会验证请求,为每个目标创建一个作业和一条项目,并立即返回一个 jobId。工作在后台运行——跟踪该作业以了解进度并获取结果。
一个变更覆盖所有五种操作,由 operation 字段选择:
要求
Authorization: Basic <API_KEY>- 你的应用已启用批量 API 能力。
- 所选操作所需的 scope,且由每个目标用户授予(见上表)。缺少 scope 的目标会成为逐项失败——永远不会导致整个作业失败。
每次提交必须携带一个幂等性键——可以是
idempotencyKey 输入,或 Idempotency-Key 头(如果两者都发送则必须匹配)。在请求逐字节完全相同的情况下,使用相同键重新提交会返回原始作业,而不是创建重复项;在相同键下的不同请求将被拒绝。对于扇出式写入,没有安全的默认行为,因此该键为必填。变更
QUEUED 状态的作业。acceptedItemCount 表示将被处理的目标数量;skippedItemCount 表示在前置阶段被拒绝的数量(例如缺少所需的 scope)。轮询该作业以观察 succeededItemCount / failedItemCount 的变化——参见跟踪批量作业。
变量 — 导出余额 / 交易
exportOptions 限定窗口(默认为最近 90 天;GET_BALANCES_EXPORT 为时点快照,忽略该窗口)。与读取相同,使用目标选择。
变量 — 创建转账
每个项目指定其各自的from 和 to 端点,因此一个作业可以混合多种方向:运营方→用户、用户→运营方,以及用户→用户。一个端点要么是 { "operator": true }(你的应用的付款账户)要么是 { "externalReferenceId": "…" }(一个已连接用户)。from 和 to 必须不同。来源用户的授权必须允许 MAKE_PAYOUT_TRANSFER_SEND;目的方只需已连接。转账在同一赞助银行内进行。对于转账不需要 targetSpec——参与方来自各条项目。
变量 — 充值现金余额
从已连接用户本人的支付方式为其消费账户充值——每条项目在bankCardId 或 bankAccountId 中恰好选择一个。使用 SELECTED 目标方式,每个目标一条项目。userCashBalanceId 可选(默认为用户的许可/默认消费账户)。
变量 — 更新交易元数据
编辑用户交易上的memo 和/或 transactionCategory。使用 SELECTED 目标方式,每个目标一条项目,每次提交最多 100 次编辑。将某字段设为 null 会清空它;省略的字段保持不变。元数据编辑是同步执行的——返回的作业已处于终态,因此你可以立即读取每次编辑的结果而无需轮询。