使用 kintone REST API 更新记录流程状态时的权限问题

在 kintone 开发中，透过 REST API 操作记录流程状态是一个常见需求，尤其是自动化工作流程时。然而，在开发过程中可能会遇到执行【PUT】/k/v1/record/status.json 时出现「无权限」、「非执行者」等错误。本文将探讨这些错误的成因以及解决方法，并提供权限设定的建议。

REST API 更新记录流程状态的权限要求

kintone 提供的【PUT】/k/v1/record/status.json API 用于更新记录的流程状态。在呼叫此 API 时，必须满足以下基本权限要求：

• 执行 API 之使用者，需具备对象记录的阅览权限。

而根据执行 API 时的认证方式不同，还会有以下限制：

开发者最常遇到的问题是：「我明明使用 API token 认证执行 API，怎么还会没有权限？」就是因为上面第二点的限制。简单来说，即便是使用 REST API 更新流程，除非没有指定执行者，否则操作者也必须是执行者，而透过 API token 认证时的操作者则视为 Administrator。因此，在未做额外处理的情况下，仍需确认执行者身份。

权限问题的解决方案

原则上，遵循仅有执行者可以执行流程动作的规则是比较合乎逻辑的，但若有必要，仍可透过「修改执行者」的方式来解决权限不足的问题。

在执行状态更新的 API 前，先执行更新执行者的 API： 【PUT】/k/v1/record/assignees.json，使操作者的权限符合需求。

由于执行此 API 需要有应用程式管理权限，较方便的做法是使用 kintoneRestAPIClient ，以 API token 认证（需授予：查看记录、应用程式管理）进行操作。范例程式码如下：

// 使用 API token 认证
const tokenClient = new KintoneRestAPIClient({
auth: {
apiToken: \'YOUR_APP_API_TOKEN\'
}
});

// 不带 auth 参数时，使用登入使用者认证（Session authentication）
const userClient = new KintoneRestAPIClient();

// 更新执行者
await tokenClient.record.updateRecordAssignees({
app: kintone.app.getId(), // 应用程式ID
id: \'指定记录ID\',
assignees: [] // 更改执行者
});

// 更新流程状态
await userClient.record.updateRecordStatus({
app: kintone.app.getId(),
id: \'指定记录ID\',
action: \'欲执行的动作名称\'
});

参数 assignees 为一阵列，内含执行者的使用者代号（code）。由于只要该状态未指定执行者时，操作者只需拥有记录的阅览权限即可执行，因此直接清除指定执行者是最简单、最通用的方式，只要将 assignees 设为空阵列即可。

清除指定执行者后再使用 API 更新流程状态时，状态履历上的动作执行者将依验证方式而定：

• 使用者认证：执行者为该使用者。
• API token 认证：执行者为 Administrator。

特殊情境注意事项

若流程动作按钮出现的条件与使用者绑定，例如：

设定了「Administrator」为指定执行者的动作「复原」，若使用上述方式清除执行者再更新流程状态，会发生以下错误：

await tokenClient.record.updateRecordAssignees({
app: kintone.app.getId(),
id: \'指定记录ID\',
assignees: []
});

await tokenClient.record.updateRecordStatus({
app: kintone.app.getId(),
id: \'指定记录ID\',
action: \'复原\'
});

错误讯息：

KintoneRestAPIError: [400] [GAIA_IL03] 状态变更失败。可能有其他使用者变更了状态或状态的设定。 (PWcmHG5YX7vgZu6EtEHe)

发生错误的原因是，在执行状态更新之前执行者已被清空，导致没有「复原」这个动作可以执行。这点也是在实际应用上需要特别留意的地方。

结语

在使用 kintone REST API 自动化流程时，理解 API 的权限要求能有效避免执行错误。若需在流程中切换执行者，可透过 [PUT] /k/v1/record/assignees.json 清除或指定执行者，确保流程能顺利执行。最后，请谨慎管理 API token 权限，避免不必要的安全风险。