# 接入开放平台

开放平台让组织自己的小程序或系统的后台（下称「集成」）用凭证调用 Raise：管理员新建集成、勾选它能用的数据范围、生成凭证、订阅事件，集成的后台再用凭证换令牌去读写这些数据。

Raise 这边的设置在「我的组织」→「应用」→「开放平台」。只有管理员能修改，审计员只能查看。

## 开始前准备

- Raise 里「管理员」角色的账号。
- 一个能保存密钥的后台（集成）。凭证和签名密钥都只显示一次，要放进它的密钥库。

## 新建集成

1. 在「开放平台」页点「新建集成」。
2. 填写：

   | 字段 | 说明 |
   |---|---|
   | 「标识」 | 创建后不能改。3–48 位小写字母、数字或 -，字母开头，不能是保留词。被用过的标识不能再用 |
   | 「名称」 | 最多 60 个字符 |
   | 「范围」 | 勾选它能用的数据。不勾选则什么都不能用，见[数据范围](#scopes) |

3. 点「创建」。勾了中风险、高风险或会修改数据的范围时，会先问「授予这些范围？」，确认后才创建。

## 生成凭证

1. 在集成卡片的「凭证」里点「生成凭证」，「名称」选填，用来区分（最多 100 个字符）。
2. 点「生成」。弹窗显示「Client ID」「密钥」和「令牌地址」，以及一条获取令牌的命令，都可复制。
3. 把密钥交给集成的后台，放进它的密钥库。密钥只在生成或轮换时显示一次。
4. 集成的后台用 Client ID 和密钥向「令牌地址」换令牌，再带着令牌调用接口。请用页面给出的令牌地址，不要自己拼主机。

每个集成最多 5 个有效凭证，到上限时先吊销一个。

- **轮换**：旧凭证默认再可用 7 天，然后失效；新密钥只显示一次。
- **吊销**：持有这个凭证的后台立刻取不到令牌，已经取到的令牌也立即失效。

## 数据范围

每个范围显示名字、说明、风险（「低风险」「中风险」「高风险」），会写数据的还标「会修改数据」。

1. 在集成卡片的「数据范围」里勾选或取消。
2. 点「保存范围」。新增中高风险或会写数据的范围时，会先请你确认。

授予后，这个集成的后台可以读取或修改你组织里相应的数据。收回的范围立即失效。范围的清单随已安装的应用而变，以页面上列出的为准。

## 事件订阅

平台会把你订阅的事件 POST 到集成的后台，并用签名密钥签名。只有授予了对应范围的事件才会发。

1. 在集成卡片的「事件订阅」里点「新建订阅」。
2. 填「接收地址」（以 http:// 或 https:// 开头，正式环境只接受 https），「说明」选填（最多 200 个字符），勾选「要接收的事件」（至少一个）。
3. 点「创建」。弹窗显示「签名密钥」，只显示这一次，复制给后台用来验签。
4. 点「发送测试」，再看「投递记录」（最近 50 条）里的状态：「等待」「已送达」「失败」。

轮换签名密钥时，旧的立刻失效，没有重叠期。每个集成的订阅条数有上限，页面会写明。

## 读取表格数据

集成可以从外部读取组织的表（[站点](/apps/site)应用里的表），只读，不能写。

1. 给集成授予表的读取范围：自建的表是 `tables.base:read`，系统表是各自的 `tables.<表>:read`。可以在「开放平台」里勾，也可以在站点应用右上角「设置 → 开放接口」里设置（同一批集成和凭证，那里只管表的范围）。
2. 在站点应用里打开这张表的「开放给项目」开关。表没开放时，集成读不到。
3. 集成按表和视图读取行：视图的筛选照用，敏感列不会返回。

读取接口的地址和参数，交给开发者按开放平台的接口说明调用。

## 常见问题

#### 集成的后台换令牌被拒，说没有范围？
集成当前没有生效的范围。在「数据范围」里勾选需要的范围并保存，再换令牌。

#### 删除集成会怎样？
这个集成的后台立刻取不到令牌，已取到的令牌也立即失效；它的事件订阅一并删除。标识仍被占用，不能用同一个标识再建。

#### 「发送测试」之后没有投递记录？
测试只是排进了队列，不表示对方已经回答。稍等后在「投递记录」里点「刷新」再看。