连接 API

按最新优先列出项目的连接，每页最多 200 个；把 next_cursor 作为 after 传回即可获取下一页。

连接是项目可重复使用的 Microsoft 或 Google 访问权限，供无人值守运行的数据源使用：microsoft365 或 google_calendar 数据源、Power BI 连接和 SharePoint 媒体同步账号，在 config.connection_id 中指明一个连接，而不是自带凭据（docs/connections.md）。

密钥、密钥文件或刷新令牌绝不会返回：secret 显示是否已保存，以及一条不属于机密的提示。读取绝不会带有授权链接。

创建到 Microsoft（provider microsoft）或 Google（provider google）的连接。own_app 模式是客户自己的应用：Microsoft 需要 config.tenant_id（目录 ID 或主域名；common、organizations 和 consumers 会被拒绝）、config.client_id 和 secret（应用某个客户端密钥的值）；Google 的 secret 是服务账号的 JSON 密钥文件。

密钥加密封存，绝不会返回。screenrig_app 模式使用 screenRIG 自己的应用，不接受 config 和 secret：连接以 pending_consent 创建，响应带有 consent_url，这是供完成授权的人使用的一次性链接（有效期至 consent_expires_at）。

对于 Microsoft，这是 Microsoft 365 管理员，他为租户同意 screenRIG 的应用；随后浏览器登录 Microsoft 指明的租户，因此连接记录的是已确认的租户，绝不会是回调仅仅声称的租户。

对于 Google，这是账号持有者，他授予对该账号可见日历的只读访问权限；screenRIG 加密封存刷新令牌，并保存账号的地址。该链接是一次授权的凭据：只发送给那个人。

没有该提供商 screenRIG 应用的服务器会返回 409 connection_app_not_configured，own_app 连接仍可正常工作。一个组织在其所有项目中最多有 50 个连接（connection_limit_reached）。追加 connection.created。

使用相同 Idempotency-Key 的完全相同的重试会返回同一个连接（screenrig_app 的重试会得到新的授权链接，它会取代第一个）。

一个连接，附带其状态、最后一次错误和最后一次测试。

更改连接的名称，在 own_app 模式下还可更改其凭据：config.tenant_id 和 config.client_id（Microsoft）或 secret（发送的密钥会替换已封存的密钥；省略则保留原密钥）。screenrig_app 模式的连接只能重命名：要更改授权的人，请重新连接它（POST /api/connections/{id}/connect）。

更改凭据会使连接回到 ready，清除 last_error 和 last_test，并作废为旧凭据签发的所有令牌。追加 connection.updated。If-Match 保护修订版本。

删除没有任何内容通过它读取的连接。只要有数据源、Power BI 连接或媒体同步账号还在使用它，响应就是指明它们的 resource_conflict（used_by 列出它们的类型和 ID）。

删除并不会终止服务商那一侧：Microsoft 365 租户会一直保留 screenRIG 的应用，直到其管理员将其移除；Google 账号会一直保留其授权，直到其持有者撤销。追加 connection.deleted。If-Match 保护修订版本。

用该连接登录，并把结果存为 last_test。

对于 Microsoft，检查项是 credentials（Microsoft 为租户签发了应用令牌）和 permissions（应用令牌带有 Calendars.Read、Sites.Selected、Files.Read.All、Sites.Read.All 和 Place.Read.All 中的哪些；一个都没有的应用检查失败，仅有 Sites.Selected 则是警告，因为每个 SharePoint 站点都需要授予）。

对于 Google，检查项是 credentials：Google 接受了服务账号，或授权账号的刷新令牌，响应会指明日历必须对哪个账号可见。被拒绝即检查失败，连接会转为 error 并带有 last_error；成功则回到 ready。

它不判断日历的共享设置、邮箱访问策略或站点授予，这些由数据源或同步在运行时证明。每个组织每分钟最多 30 次。

为 screenrig_app 模式的连接生成新的一次性授权链接（consent_url，有效期至 consent_expires_at），发送给完成授权的人：Microsoft 365 管理员或 Google 账号持有者。它会取代之前的所有链接。

正常工作的连接在新的授权完成之前保持不变，因此这也可用于续期已转为 error 的连接（授权被撤回、访问被撤销），或把它改到另一个租户或账号。该链接是授权的凭据：只发送给那个人。

当那个人完成后，浏览器会回到 GET /oauth/connections/{provider}/callback，并被转到控制台中该连接的页面，该页面读取 status 和 last_error。own_app 模式的连接没有授权步骤（409 resource_conflict）；没有该提供商 screenRIG 应用的服务器会返回 409 connection_app_not_configured。

对于 screenrig_app 模式的连接，Microsoft 在 Microsoft 365 管理员完成管理员同意页面之后（以及随后的登录步骤之后再次）把其浏览器送到的地址。

它不携带任何凭据：查询中已签名的 state 是唯一的依据，在读取它所指向的任何内容之前先验证，并且只在它是该连接待处理的授权时才被采信。

第一次返回指明了一个租户，但该租户尚未经过身份验证：响应是重定向到该租户的登录，其代码用应用的密钥和只有本服务器能推导出的 PKCE 验证码来兑换；连接记录的是 ID 令牌所携带的租户，且是在客户端凭据令牌证明应用在那里持有其权限之后才记录。

已验证 state 之后的每种结果，都会重定向到控制台中该连接的页面（/dashboard/connections/{id}?consent=connected 或 ?consent=failed），该页面读取 status 和 last_error；错误文本由固定的句子和 Microsoft 自己的错误响应（其 AADSTS 代码）构成，绝不取自回调查询所携带的内容。

未知、已过期、已使用、已被取代或属于已删除连接的 state，会显示一个不指明任何内容的页面。仅在登记回调的 API 主机上响应。

对于 screenrig_app 模式的连接，Google 在账号持有者完成授权页面之后把其浏览器送到的地址。

它不携带任何凭据：查询中已签名的 state 是唯一的依据，在读取它所指向的任何内容之前先验证，并且只在它是该连接待处理的授权时才被采信。screenRIG 用应用的密钥和只有本服务器能推导出的 PKCE 验证码兑换代码，要求已授予日历范围（人可以在授权页面取消勾选）以及一个刷新令牌，从 Google 在该调用中返回的 ID 令牌读取授权账号，加密封存刷新令牌，并追加 connection.connected。

已验证 state 之后的每种结果，都会重定向到控制台中该连接的页面（/dashboard/connections/{id}?consent=connected 或 ?consent=failed），该页面读取 status 和 last_error。未知、已过期、已使用、已被取代或属于已删除连接的 state，会显示一个不指明任何内容的页面。

仅在登记回调的 API 主机上响应。