连接 Microsoft 和 Google

连接如何工作

• 提供商和模式。 provider 是 microsoft 或 google。mode 是 own_app（您自己的 Microsoft Entra 应用或 Google 服务账号），或是 screenrig_app（screenRIG 的应用，由 Microsoft 365 管理员或 Google 账号持有者批准）。
• 状态。 在有人批准 screenRIG 的应用之前，连接会停留在 pending_consent。只要它持有上次尝试未被拒绝的凭据，状态就是 ready；Microsoft 或 Google 拒绝凭据时是 error：last_error 会说明原因，之后一次成功会让它回到 ready。限流或服务中断不会改变状态。
• 密钥保持加密封存。 密钥、密钥文件或刷新令牌不会再次显示。读取时会显示是否已保存，以及一条提示：Microsoft 客户端密钥的后四位字符，或 Google 服务账号的地址。
• 测试它。 测试会登录并保存结果。对于 Microsoft，它还会列出所获令牌带有的 Graph 应用程序权限。
• 修改它。 修改您自己应用的凭据会让连接回到 ready 并清除其上一次错误。screenRIG 应用模式的连接只能重命名：如需更换批准人，请申请新的授权链接。
• 删除它。 只要有数据源、Power BI 连接或媒体同步账号通过该连接读取，删除就会被拒绝（resource_conflict）。删除不会结束供应商一侧的授权：租户会保留 screenRIG 的应用，直到管理员将其移除；Google 账号会保留其授权，直到持有者撤销。
• 上限。 一个组织在其所有项目中最多有 50 个连接。

您自己的应用或 screenRIG 的应用

Microsoft

您自己的应用

在 Microsoft Entra 管理中心注册应用，添加客户端密钥（复制其值，而不是其 ID），为应用授予下面的应用程序权限并授予管理员同意。创建连接时，把目录 ID 或主域名作为 config.tenant_id（common、organizations 和 consumers 会被拒绝），应用程序 ID 作为 config.client_id，客户端密钥的值作为 secret。

screenRIG 的应用，经管理员授权

以 screenrig_app 模式创建连接，不带设置，也不带密钥。响应中包含 consent_url，这是一个有效期 24 小时的一次性链接。只把它发给一位 Microsoft 365 管理员，不要发给其他人：它就是这一次授权的凭据。

1. 管理员打开链接，为该租户批准 screenRIG 的应用。
2. Microsoft 返回 screenRIG，后者要求管理员登录该租户。连接会记录实际登录的租户，绝不会记录仅由请求声称的租户。
3. screenRIG 使用获得的权限登录租户一次。连接变为 ready。

链接只能使用一次。更新的链接、完成的授权或删除都会使旧链接失效，您可以随时申请新链接：用于续期已变为 error 的连接，或关联另一个租户。如果管理员拒绝或登录未完成，连接会记录 consent_denied 或 consent_failed（附 Microsoft 的 AADSTS 代码），并保留待处理的授权，因此可以再次打开同一个链接。已经正常工作的连接绝不会因被拒绝的第二次授权而受损。如果租户移除了 screenRIG 的应用，连接会显示 consent_revoked：请管理员重新批准。

批准以租户为单位。管理员一旦批准 screenRIG 的应用，任何能登录该租户的人都可以把它连接到自己的项目，所以请像下面这样缩小应用可读取的范围。在 Microsoft Entra 中删除企业应用程序会结束所有项目的访问。

应用可以读取什么

连接测试会列出所获令牌带有其中哪些权限。如果只有 Sites.Selected，它会发出警告，因为每个站点仍然需要自己的授权；如果一个都没有，测试失败。

Google

您自己的应用

在 Google Cloud 中创建服务账号，启用 Google Calendar API，并下载其 JSON 密钥（不超过 16 KiB）。把整个文件作为 secret 交给连接：screenRIG 会在保存时检查。然后把每个会议室日历共享给服务账号的地址，或在管理控制台中为该账号启用域范围委派，范围为 https://www.googleapis.com/auth/calendar.events.readonly，并在数据源上指定 subject。

screenRIG 的应用

授权链接会打开 Google 的授权页面。账号持有者授予对日历事件的只读访问（范围 calendar.events.readonly，另有 openid 和 email，以便 screenRIG 知道是哪个账号批准的）。如果用户取消勾选日历权限，授权会失败。数据源读取该账号能看到的日历，因此该账号必须能看到数据源列出的每个会议室日历，而且这类连接的数据源不能指定 subject。Google 不再认可该授权时，连接会显示 reconnect_required：请申请新链接。

使用连接

• 会议室数据源。 在 microsoft365 或 google_calendar 数据源上设置 connection_id，以代替 tenant、client_id 和 client_secret（或 service_account_key）。两种模式都可以。内联凭据仍然有效，但不能与 connection_id 混用。
• SharePoint 和 OneDrive 媒体同步。 Microsoft 365 同步账号接受 connection_id，以代替 tenant_id、client_id 和 secret。
• Power BI。 Power BI 连接接受模式为 own_app 的 Microsoft 连接的 connection_id，以代替其自己的租户、客户端 ID 和密钥。Microsoft 没有说明另一个租户的应用可以在客户的租户中生成嵌入令牌，因此 Power BI 不接受 screenRIG 的应用。Power BI 管理员仍需启用服务主体设置，并把该应用添加到每个工作区。

连接缺失、等待批准或属于另一提供商的数据源会报告 config_invalid。Microsoft 或 Google 拒绝登录时，数据源会报告 auth_failed，连接变为 error。

创建连接

在控制台中创建连接，或使用 POST /api/connections。您自己的 Microsoft 应用：

{
  "provider": "microsoft",
  "mode": "own_app",
  "name": "Contoso rooms",
  "config": {"tenant_id": "contoso.com", "client_id": "CLIENT_ID"},
  "secret": "CLIENT_SECRET_VALUE"
}

screenRIG 的应用，不带设置，也不带密钥：

{"provider": "google", "mode": "screenrig_app", "name": "Campus rooms"}

第二个请求的响应包含 consent_url 和 consent_expires_at：把链接发给负责批准的人。POST /api/connections/ID/connect 会生成新链接，POST /api/connections/ID/test 会登录并保存结果。请把密钥放在请求文件中，不要放在命令行上。

connection_app_not_configured 表示服务器没有该提供商的 screenRIG 应用：请使用您自己的应用创建连接。connection_limit_reached 表示组织已有 50 个：删除一个没有任何内容在读取的，或重用现有连接。

相关

• 数据源：使用连接的会议室数据源。
• API 参考：每个连接路由。
• 单点登录：人员如何登录。连接用于无人登录时运行的工作。