此页面由 Cloud Translation API 翻译。

将 Microsoft OneDrive 与数据注入功能相关联

本页介绍了如何使用数据注入功能将 Microsoft OneDrive 关联到 Gemini Enterprise。

请按照以下过程操作，从 OneDrive 同步数据。

首次设置数据源并导入数据后，数据存储区会按照您在设置期间选择的频率同步来自该来源的数据。

限制

增量同步不会检测到文件夹级操作，例如复制、移动或重命名。

准备工作

如需在 Gemini Enterprise 中强制执行数据源访问权限控制并保护数据安全，请确保您已配置身份提供方。

关于 Microsoft Entra ID 应用注册

您必须先设置 Microsoft Entra ID 应用注册，以实现对 OneDrive 的安全访问，然后才能在 Gemini Enterprise 中创建连接器。注册应用的方式取决于您在 Gemini Enterprise 中创建连接器时选择的身份验证方法。您可以选择以下方法之一：

联合凭证：
- 可让 Google 使用加密签名的令牌安全地访问 OneDrive，而无需实际的用户主账号。
- 需要有主体 ID 才能在 Entra 中注册 Gemini Enterprise。在 Gemini Enterprise 中创建 OneDrive 连接器时，可以使用此方法。
- 在 Entra ID 中注册应用时，您必须收集以下详细信息：
  - 实例 URI：
    - 对于所有第一级网站：https://DOMAIN_OR_SERVER.onedrive.com，例如 mydomain.onedrive.com。
    - 对于单个网站：https://DOMAIN_OR_SERVER.onedrive.com/[sites/]WEBSITE，例如 mydomain.onedrive.com/sites/sample-site。
  - 租户 ID
  - 客户端 ID
  这些详细信息对于完成身份验证并在 Gemini Enterprise 中创建 OneDrive 连接器是必需的。
- Google 建议您使用此方法。
OAuth 2.0 刷新令牌：
- 可精细控制哪些用户可以连接到 OneDrive API。
- 在 Entra ID 中注册应用时，您必须收集以下详细信息：
  - 实例 URI：采用以下格式：
    - 对于所有第一级网站：https://DOMAIN_OR_SERVER.onedrive.com，例如 mydomain.onedrive.com。
    - 对于单个网站：https://DOMAIN_OR_SERVER.onedrive.com/[sites/]WEBSITE，例如 mydomain.onedrive.com/sites/sample-site。
  - 租户 ID
  - 客户端 ID
  - 客户端密钥
  这些详细信息对于完成身份验证并在 Gemini Enterprise 中创建 OneDrive 数据存储区是必需的。
- 身份验证流程包括登录您的 OneDrive 账号。
- 如果您的 OneDrive 设置需要双重身份验证，则此方法非常适合。
- 需要您创建新的 OneDrive 用户，这可能会增加许可费用。
OAuth 2.0 密码授权：
- 可精细控制哪些用户可以连接到 OneDrive API。
- 在 Entra ID 中注册应用时，您必须收集以下详细信息：
  - 实例 URI：
    - 对于所有第一级网站：https://DOMAIN_OR_SERVER.onedrive.com，例如 mydomain.onedrive.com。
    - 对于单个网站：https://DOMAIN_OR_SERVER.onedrive.com/[sites/]WEBSITE，例如 mydomain.onedrive.com/sites/sample-site。
  - 租户 ID
  - 客户端 ID
  - 客户端密钥
  这些详细信息对于完成身份验证并在 Gemini Enterprise 中创建 OneDrive 数据存储区是必需的。
- 身份验证流程包括提供 Entra ID 管理员提供的用户名和密码。
- 如果您的 OneDrive 设置不需要双重身份验证，则此方法非常适合。
- 此方法需要您创建新的 OneDrive 用户，这可能会增加许可费用。

设置联合凭证

请按照以下步骤配置应用注册、授予权限和建立身份验证。Google 建议您使用联合凭证方法。

错误消息中列出了您在此过程中可能会遇到的一些常见错误消息。

获取服务账号客户端 ID：
1. 在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。
2. 在导航菜单中，点击数据存储区。
3. 点击 创建数据存储区。
4. 在选择数据源页面上，滚动查找或搜索 OneDrive 以连接第三方来源。
5. 记下主体标识符。请先不要点击继续。执行此任务的后续步骤，并按照创建 OneDrive 连接器中的说明，在 Google Cloud 控制台完成后续操作。
在 Entra ID 中注册应用：
1. 前往 Microsoft Entra 管理员中心。
2. 在菜单中，展开应用部分，然后选择应用注册。
3. 在应用注册页面上，选择新注册。
  
  在 Microsoft Entra 管理中心内注册新应用
4. 在注册应用页面上创建应用注册：
  - 在支持的账号类型部分，选择仅此组织目录中的账号。
  - 在重定向 URI 部分，选择 Web，然后输入重定向 URI https://vertexaisearch.cloud.google.com/console/oauth/onedrive_oauth.html
  - 保留其他设置的默认值，然后点击注册。
  选择账号类型并输入重定向 URI
5. 记下客户端 ID 和租户 ID。
  
  应用详情页面
添加联合凭证：
1. 前往证书和密钥 > 联合凭证 > 添加凭证。
  
  在 Microsoft Entra 中添加联合凭证
2. 使用以下设置：
  - 联合凭证场景：其他颁发者
  - 颁发者：https://accounts.google.com
  - 主体标识符：使用您在上一步中记下的主体标识符的值。
  - 名称：提供一个唯一名称。
3. 点击添加以授予访问权限。
  
  将您的 Google 账号关联到 Microsoft Entra ID

设置 API 权限。

添加并授予以下 Microsoft Graph 权限。您可以选择网站控制选项（Sites.FullControl.All 和 Sites.Selected）或个人资料读取选项（User.Read.All 和 User.ReadBasic.All）：

用于联合凭据的 Microsoft Graph 权限

权限	类型	说明	理由
`GroupMember.Read.All`	应用	读取所有群组成员资格	此权限可让 Gemini Enterprise 了解 OneDrive 网站中用户群组的成员资格。
`User.Read`	委派	登录并读取用户个人资料	这是不得移除的默认权限。移除后，OneDrive 会显示一条错误消息，要求您恢复此权限。
`Files.Read.All`	应用	读取所有网站集中的文件	此权限可让 Gemini Enterprise 读取所有网站集中的所有文件。
网站控制选项
选项 1：`Sites.FullControl.All`	应用	完全控制所有网站	此权限可让 Gemini Enterprise 获取 OneDrive 用户群组和角色分配，这些信息不包含在 `Sites.Read.All` 权限中。它还允许 Gemini Enterprise 将所有 OneDrive 网站中的文档、事件、注释、附件和文件编入索引。如果授予对所有网站的完全控制权过于宽泛，请使用选项 2：`Sites.Selected` 来授予精细的控制权。
选项 2：`Sites.Selected`	应用	控制所选网站	此权限可让 Gemini Enterprise 获取 OneDrive 用户群组和角色分配，这些信息不包含在 `Sites.Read.All` 权限中。它还允许 Gemini Enterprise 将所选 OneDrive 网站中的文档、事件、注释、附件和文件编入索引。此权限可提供更精细的控制，而不是 `Sites.FullControl.All` 注意：使用 `Sites.Selected` 时，您必须授予所选网站的 `fullcontrol` 权限。此外，为了使此权限生效，您必须在 Gemini Enterprise 中创建 OneDrive 连接器时至少执行以下一项操作：在第 5 步中，使用特定网站网址作为 OneDrive 连接器实例网址，例如 `mydomain.onedrive.com/sites/sample-site`。在第 6 步中，设置 Gemini Enterprise 数据存储区时，提供精确的 `siteName` 过滤条件。
个人资料读取选项
选项 1：`User.Read.All`	应用	读取所有用户的完整个人资料	此权限可让 Gemini Enterprise 了解 OneDrive 内容的数据访问权限控制。
选项 2：`User.ReadBasic.All`	应用	读取所有用户的基本个人资料	此权限可让 Gemini Enterprise 了解 OneDrive 内容的数据访问权限控制。

添加并授予以下 OneDrive 权限。您可以选择 Sites.FullControl.All 或 Sites.Selected：

用于联合凭证的 OneDrive 权限

权限类型说明理由

权限	类型	说明	理由
选项 1：`Sites.FullControl.All`	应用	完全控制所有网站	此权限可让 Gemini Enterprise 获取 OneDrive 用户群组和角色分配，这些信息不包含在 `Sites.Read.All` 权限中。它还允许 Gemini Enterprise 将所有 OneDrive 网站中的文档、事件、注释、附件和文件编入索引。如果授予对所有网站的完全控制权过于宽泛，请使用选项 2：`Sites.Selected` 来授予精细的控制权。
选项 2：`Sites.Selected`	应用	控制所选网站	此权限可让 Gemini Enterprise 获取 OneDrive 用户群组和角色分配，这些信息不包含在 `Sites.Read.All` 权限中。它还允许 Gemini Enterprise 将所选 OneDrive 网站中的文档、事件、注释、附件和文件编入索引。注意：使用 `Sites.Selected` 时，您必须授予所选网站的 `fullcontrol` 权限。此外，为了使此权限生效，您必须在 Gemini Enterprise 中创建 OneDrive 连接器时至少执行以下一项操作：在第 5 步中，使用特定网站网址作为 OneDrive 连接器实例网址，例如 `mydomain.onedrive.com/sites/sample-site`。在第 6 步中，设置 Gemini Enterprise 连接器时，提供精确的 `siteName` 过滤条件。

选项 1：Sites.FullControl.All

应用

完全控制所有网站

此权限可让 Gemini Enterprise 获取 OneDrive 用户群组和角色分配，这些信息不包含在 Sites.Read.All 权限中。它还允许 Gemini Enterprise 将所有 OneDrive 网站中的文档、事件、注释、附件和文件编入索引。

如果授予对所有网站的完全控制权过于宽泛，请使用选项 2：Sites.Selected 来授予精细的控制权。

选项 2：Sites.Selected

应用

控制所选网站

此权限可让 Gemini Enterprise 获取 OneDrive 用户群组和角色分配，这些信息不包含在 Sites.Read.All 权限中。它还允许 Gemini Enterprise 将所选 OneDrive 网站中的文档、事件、注释、附件和文件编入索引。

对于添加的权限，请检查状态列是否将相应权限列为 Granted 并带有绿色对勾标记。

授予管理员同意书。如需了解如何授予同意权，请参阅 Microsoft Entra 文档中的为租户范围的管理员授予对应用的同意权。

为刷新令牌和密码授权设置 OAuth 2.0

您可以使用 OAuth 2.0 方法设置 Entra ID 应用注册，并实现对 OneDrive 的安全访问。此方法包含配置应用注册、授予权限和建立身份验证的步骤。

您可以按照以下流程，使用 OAuth 2.0 身份验证来获取刷新令牌和密码授权，以在 Entra ID 中注册应用。如果您需要精细控制 OneDrive REST API 权限，以便限制对用户账号的资源访问权限，则首选此方法。

错误消息中列出了您在此过程中可能会遇到的一些常见错误消息。

下表介绍了建议用于 OAuth 2.0 身份验证方法的 OneDrive 角色：

查看角色

建议用于 OAuth 2.0 身份验证方法的 OneDrive 角色
角色	客户端应用注册	提取所有实体的内容	提取 ACL	提取身份	备注
网站管理员	否	是	是	是
网站集管理员	否	是	是	是
全局管理员	是	否	是	否	限制：全局管理员无法提取身份或注释和附件实体。
网站所有者	否	是	是	否	限制：网站所有者与 Microsoft 365 管理员中心/Entra ID 管理员中心相关，而非特定于 OneDrive。
应用管理员	是	不适用	不适用	不适用	应用管理员角色与 Microsoft 365 管理员中心/Entra ID 管理员中心相关，而非特定于 OneDrive。

创建应用注册：
1. 前往 Entra ID 管理员中心。
2. 创建应用注册：
  - 支持的账号类型：仅限组织目录中的账号。
  - 重定向 URI：https://vertexaisearch.cloud.google.com/console/oauth/onedrive_oauth.html。
3. 记下客户端 ID 和租户 ID。
添加客户端密钥：
1. 前往证书和密钥 > 新客户端密钥。
2. 记下密钥字符串。

设置 API 权限。

添加并授予以下 Microsoft Graph 权限。您可以选择 Sites.FullControl.All 或 Sites.Selected：

用于 OAuth 2.0 身份验证的 Microsoft Graph 权限

权限	类型	说明	理由
`GroupMember.Read.All`	应用	读取所有群组成员资格	此权限可让 Gemini Enterprise 了解 OneDrive 网站中用户群组的成员资格。
`User.Read`	委派	登录并读取用户个人资料	这是不得移除的默认权限。移除后，OneDrive 会显示一条错误消息，要求您恢复此权限。
选项 1：`Sites.FullControl.All`	应用	完全控制所有网站	此权限可让 Gemini Enterprise 获取 OneDrive 用户群组和角色分配，这些信息不包含在 `Sites.Read.All` 权限中。它还允许 Gemini Enterprise 将所有 OneDrive 网站中的文档、事件、注释、附件和文件编入索引。
选项 2：`Sites.Selected`	应用	控制所选网站	此权限可让 Gemini Enterprise 获取 OneDrive 用户群组和角色分配，这些信息不包含在 `Sites.Read.All` 权限中。它还允许 Gemini Enterprise 将所选 OneDrive 网站中的文档、事件、注释、附件和文件编入索引。此权限可提供更精细的控制，而不是 `Sites.FullControl.All` 注意：使用 `Sites.Selected` 时，您必须授予所选网站的 `fullcontrol` 权限。此外，为了使此权限生效，您必须在 Gemini Enterprise 中创建 OneDrive 数据存储区时至少执行以下一项操作：在第 5 步中，使用特定网站网址作为 OneDrive 数据存储区实例 `mydomain.onedrive.com/sites/sample-site`。在第 6 步中，设置 Gemini Enterprise 数据存储区时，提供精确的 `siteName` 过滤条件。
`User.Read.All`	应用	读取所有用户的完整个人资料	此权限可让 Gemini Enterprise 了解 OneDrive 内容的数据访问权限控制。

添加并授予以下用于 OAuth 2.0 身份验证的 OneDrive 权限。您可以选择 AllSites.FullControl 或 Sites.Selected：

用于 OAuth 2.0 身份验证的 OneDrive 权限

权限	类型	说明	理由
选项 1：`AllSites.FullControl`	委派	完全控制所有网站	此权限可让 Gemini Enterprise 获取 OneDrive 用户群组和角色分配，这些信息不包含在 `Sites.Read.All` 权限中。它还允许 Gemini Enterprise 将所有 OneDrive 网站中的文档、事件、注释、附件和文件编入索引。
选项 2：`Sites.Selected`	委派	控制所选网站	此权限可让 Gemini Enterprise 获取 OneDrive 用户群组和角色分配，这些信息不包含在 `Sites.Read.All` 权限中。它还允许 Gemini Enterprise 将所选 OneDrive 网站中的文档、事件、注释、附件和文件编入索引。此权限可提供比 `AllSites.FullControl` 更精细的控制。注意：使用 `Sites.Selected` 时，您必须授予所选网站的 `fullcontrol` 权限。此外，为了使此权限生效，您必须在 Gemini Enterprise 中创建 OneDrive 数据存储区时至少执行以下一项操作：在第 5 步中，使用特定网站网址作为 OneDrive 数据存储区实例网址，例如 `mydomain.onedrive.com/sites/sample-site`。在第 6 步中，设置 Gemini Enterprise 数据存储区时，提供精确的 `siteName` 过滤条件。

对于添加的权限，请检查状态列是否将相应权限列为 Granted 并带有绿色对勾标记。

验证 API 权限
使用对特定网站具有有限访问权限的专用用户账号。验证此账号是否拥有对所选网站的所有者访问权限。

授予管理员同意书。如需了解如何授予同意权，请参阅 Microsoft Entra 文档中的为租户范围的管理员授予对应用的同意权。

错误消息

下表列出了将 OneDrive 与 Gemini Enterprise 连接时可能会出现的常见错误消息及其相关说明。

错误代码	错误消息
`ONEDRIVE_MISSING_PERMISSION_1`	缺少必需的 REST API 角色（Sites.FullControl.All 或 Sites.Selected）。对于委托的权限，缺少 AllSites.FullControl 或 Sites.Selected。
`ONEDRIVE_MISSING_PERMISSION_2`	缺少必需的 Graph API 角色（Sites.FullControl.All 或 Sites.Selected）。
`ONEDRIVE_MISSING_PERMISSION_3`	缺少必需的 Graph API 角色 GroupMember.Read.All。
`ONEDRIVE_MISSING_PERMISSION_4`	缺少必需的 Graph API 角色（User.Read.All 或 User.ReadBasic.All）。
`ONEDRIVE_INVALID_SITE_URI`	未能检索到 Graph API 访问令牌。可能的原因：客户端 ID 或密钥值无效，或者缺少联合凭证。
`ONEDRIVE_INVALID_AUTH`	未能检索到 Graph API 访问令牌。可能的原因：客户端 ID 或密钥值无效，或者缺少联合凭证。
`ONEDRIVE_INVALID_JSON`	未能解析 JSON 内容。
`ONEDRIVE_TOO_MANY_REQUESTS`	向 OneDrive 发送的 HTTP 请求过多；收到了 429 HTTP 响应。

清单文件：

前往清单标签页。
删除 requiredResourceAccess 下 [ 和 ] 之间的内容。

修改清单文件

将以下 JSON 内容粘贴到这对方括号内。

{
 "resourceAppId": "00000003-0000-0000-c000-000000000000",
 "resourceAccess": [
   {
     "id": "01d4889c-1287-42c6-ac1f-5d1e02578ef6",
     "type": "Role"
   },
   {
     "id": "5b567255-7703-4780-807c-7be8301ae99b",
     "type": "Role"
   },
   {
     "id": "df021288-bdef-4463-88db-98f22de89214",
     "type": "Role"
   }
 ]
}

返回到 API 权限。
确认所有必要的权限都已存在。
授予管理员同意书。

创建 OneDrive 连接器

控制台

如需使用 Google Cloud 控制台将 OneDrive 中的数据同步到 Gemini Enterprise，请按以下步骤操作：

在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。

Gemini Enterprise
在导航菜单中，点击数据存储区。
点击 创建数据存储区。
在选择数据源页面上，滚动查找或搜索 OneDrive 以关联该第三方来源。
在身份验证设置下，选择要使用的身份验证方法。
1. 输入您的身份验证信息。
2. 点击继续。
  
  选择身份验证方法并提供身份验证信息。
选择下列要同步的实体：
- 文件
如需将实体从索引中排除，或确保其被纳入索引中，请点击过滤。
- fileName 仅匹配文件名。
- filePath 必须是完整的 Microsoft Graph API 路径，通常以 /drive/root: 为前缀。例如，如果 OneDrive 直接链接为 https:/example-my.onedrive.com/personal/user_example_com/Documents/folder1/folder2，则 filePath 为 /drive/root:/folder1/folder2。
指定用于包含或排除实体的过滤条件
点击继续。
为完全同步选择同步频率，为增量数据同步选择增量同步频率。如需了解详情，请参阅同步时间表。

如果您想分开安排实体数据和身份数据的完全同步，请展开完全同步下的菜单，然后选择自定义选项。

分开设置实体数据的完全同步和身份数据的完全同步的同步计划。
为您的数据存储区选择一个区域。
为数据存储区输入名称。
点击创建。Gemini Enterprise 会创建数据存储区，并在数据存储区页面上显示这些数据存储区。
如需查看数据注入状态，请前往数据存储区页面，然后点击数据存储区名称，在其数据页面查看相关详情。当连接器开始同步数据时，连接器状态会从正在创建变为正在运行。注入完成后，状态会变为活跃，表明已设置与数据源之间的关联，并在等待下一次的计划同步。

注入过程可能需要几分钟或几小时才能完成，具体取决于数据的大小。

启用实时同步

如需为数据存储区启用实时同步，请按以下步骤操作。

在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。

Gemini Enterprise
在导航菜单中，点击数据存储区。
点击要为其启用实时同步的 OneDrive 数据存储区的名称。
在数据存储区的数据页面上，等待连接器状态变为活跃。
在实时同步字段中，点击查看/修改。

查看和修改实时同步设置。
点击启用实时同步切换开关，将其切换到开启位置。
为客户端密钥字段提供一个值。此值用于验证 OneDrive 网络钩子事件。我们建议使用 20 个字符的字符串。

启用实时同步并提供客户端密钥。
点击保存。

等待实时同步字段变为正在运行。

错误代码

下表列出了 OneDrive 错误代码及其说明。

错误代码	说明
ONEDRIVE_MISSING_PERMISSION_1	应用缺少必要的 Graph API 角色：Files.Read.All。
ONEDRIVE_MISSING_PERMISSION_2	应用缺少必要的 Graph API 角色：Group.Read.All。
ONEDRIVE_MISSING_PERMISSION_3	应用缺少必要的 Graph API 角色：User.Read.All 或 User.ReadBasic.All。
ONEDRIVE_INVALID_SITE_URI	实例网址无效。
ONEDRIVE_INVALID_AUTH	检索 Graph API 访问令牌时出错。这可能是因为客户端 ID 或密钥值无效，或者缺少联合凭证。
ONEDRIVE_UNCATEGORIZED_ERROR	文件中的 ACL 无效或不存在。
ONEDRIVE_TOO_MANY_REQUESTS	向 OneDrive 发送的 HTTP 请求过多。收到了 HTTP 429 响应。

后续步骤

如需将数据存储区挂接到应用，请按照创建应用中的步骤创建应用并选择数据存储区。
如需在设置应用和数据存储区后预览搜索结果以了解其显示方式，请参阅预览搜索结果。