本頁面由 Cloud Translation API 翻譯而成。

透過資料擷取功能連結 Microsoft OneDrive

本頁說明如何使用資料擷取功能，將 Microsoft OneDrive 連結至 Gemini Enterprise。

按照下列程序同步處理 OneDrive 中的資料。

設定資料來源並首次匯入資料後，資料儲存庫會按照您在設定期間選取的頻率，從該來源同步資料。

限制

增量同步無法偵測資料夾層級的操作，例如「Copy」(複製)、「Move」(移動) 或「Rename」(重新命名)。

事前準備

請務必設定識別資訊提供者，以強制執行資料來源存取控管，並保護 Gemini Enterprise 中的資料。

Microsoft Entra ID 應用程式註冊說明

在 Gemini Enterprise 建立連接器前，必須先設定 Microsoft Entra ID 應用程式註冊，才能安全存取 OneDrive。應用程式的註冊方式，取決於您在 Gemini Enterprise 建立連接器時選取的驗證方式。您可以選擇下列其中一種做法：

聯合憑證：
- 允許 Google 使用以加密編碼方式簽署的權杖安全存取 OneDrive，這樣就不需使用實際的使用者主體。
- 您必須提供主體 ID，才能在 Entra 中註冊 Gemini Enterprise。在 Gemini Enterprise 中建立 OneDrive 連接器時，可取得這個 ID。
- 在 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. 點按導覽選單中的「Data Stores」(資料儲存庫)。
3. 點按「 Create Data Store」(建立資料儲存庫)。
4. 在「Select a data source」(選取資料來源) 頁面中，捲動或搜尋「OneDrive」以連線至第三方來源。
5. 記下「Subject identifier」(主體 ID)，但先不要點選「Continue」(繼續)。請完成這項工作的後續步驟，然後按照「建立 OneDrive 連接器」中的操作說明，在 Google Cloud 控制台中完成相關步驟。
在 Entra ID 中註冊應用程式：
1. 前往 Microsoft Entra 系統管理中心。
2. 在選單中展開「Applications」(應用程式) 專區，然後選取「App registrations」(應用程式註冊)。
3. 在「App registrations」(應用程式註冊) 頁面中，選取「New registration」(新註冊)。
  
  在 Microsoft Entra 系統管理中心註冊新應用程式
4. 在「Register an application」(註冊應用程式) 頁面中，建立應用程式註冊：
  - 在「Supported account types」(支援的帳戶類型) 專區，選取「Accounts in the organizational directory only」(僅限組織目錄中的帳戶)。
  - 在「Redirect URI」(重新導向 URI) 部分選取「Web」(網頁)，然後輸入重新導向 URI https://vertexaisearch.cloud.google.com/console/oauth/onedrive_oauth.html
  - 保留其他設定的預設值，然後點按「Register」(註冊)。
  選取帳戶類型並輸入重新導向 URI
5. 記下「Client ID」(用戶端 ID) 和「Tenant ID」(租戶 ID)。
  
  應用程式詳細資料頁面
新增聯合憑證：
1. 依序前往「Certificates & secrets」(憑證和密鑰) >「Federated credentials」(聯合憑證) >「Add credential」(新增憑證)。
  
  在 Microsoft Entra 中新增聯合憑證
2. 請使用下列設定：
  - 聯合憑證情境：其他核發者
  - 核發者：https://accounts.google.com
  - 主體 ID：使用您在上一個步驟中記下的主體 ID 值。
  - 名稱：輸入不重複的名稱。
3. 點按「Add」(新增) 授予存取權。
  
  將 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，並有綠色勾號圖示。

授予管理員同意。請參閱「Grant tenant-wide administrator consent to an application」(授予應用程式全租戶管理員同意聲明) 這篇 Microsoft Entra 說明文件，瞭解如何授予同意聲明。

設定 OAuth 2.0 以利更新權杖和密碼授權

您可以使用 OAuth 2.0 方法設定 Entra ID 應用程式註冊，以及確保 OneDrive 的存取安全。這個方法包含設定應用程式註冊、授予權限及建立驗證機制。

您可以按照下列步驟在 Entra ID 中註冊應用程式，將 OAuth 2.0 驗證機制用於更新權杖和密碼授權。如果您需要精細控管 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. 記下「Client ID」(用戶端 ID) 和「Tenant ID」(租戶 ID)。
新增用戶端密鑰
1. 依序前往「Certificates & secrets」(憑證和密鑰) >「New client secret」(新增用戶端密鑰)。
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 權限
使用專用使用者帳戶，此帳戶對特定網站的存取權有限。確認這個帳戶具有所選網站的擁有者存取權。

授予管理員同意。請參閱「Grant tenant-wide administrator consent to an application」(授予應用程式全租戶管理員同意聲明) 這篇 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 回應。

資訊清單檔案：

前往「Manifest」分頁。
在 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
點按導覽選單中的「Data Stores」(資料儲存庫)。
點按「 Create Data Store」(建立資料儲存庫)。
在「Select a data source」(選取資料來源) 頁面中，捲動或搜尋「OneDrive」以連線至第三方來源。
在「Authentication settings」(驗證設定) 下方，選取要使用的驗證方式。
1. 輸入驗證資訊。
2. 按一下「繼續」。
  
  選取驗證方式並提供驗證資訊。
從下列選項中選取要同步處理的實體：
- 檔案
如要從索引中篩除實體，或確定實體已納入索引，請點按「Filter」(篩選)。
- 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。
指定篩選器來納入或排除實體
按一下「繼續」。
選取「Full sync」(完整同步) 的「Sync frequency」(同步頻率)，以及「Incremental data sync」(增量資料同步) 的「Incremental sync frequency」(增量同步頻率)。詳情請參閱同步時間表的相關說明。

如要分別排定實體和身分資料的完整同步作業，請展開「Full sync」(完整同步) 下方的選單，然後選取「Custom options」(自訂選項)。

為完整實體同步和完整身分同步個別排程。
選取資料儲存庫的地區。
輸入資料儲存庫的名稱。
點按「Create」(建立)。Gemini Enterprise 會隨即建立資料儲存庫，並在「Data stores」(資料儲存庫) 頁面上顯示。
接著需要檢查擷取狀態，請前往「Data Stores」(資料儲存庫) 頁面，點選資料儲存庫名稱，即可在相應的「Data」(資料) 頁面查看該儲存庫的詳細資料。開始同步處理資料時，「Connector state」(連接器狀態) 會從「Creating」(建立中) 轉為「Running」(執行中)。擷取完成後，狀態會變更為「Active」(運作中)，表示資料來源連線設定完成，正在等待執行下個排定的同步作業。

視資料大小而定，擷取作業可能需要數分鐘至數小時才能完成。

啟用即時同步處理

按照下列步驟操作，為資料儲存庫啟用即時同步處理功能。

前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

Gemini Enterprise
點按導覽選單中的「Data Stores」(資料儲存庫)。
點按要啟用即時同步處理功能的 OneDrive 資料儲存庫名稱。
在資料儲存庫的「Data」(資料) 頁面上，等待「Connector state」(連接器狀態) 變更為「Active」(運作中)。
在「Real-time sync」(即時同步處理) 欄位中，點按「View/edit」(查看/編輯)。

查看及編輯即時同步處理設定。
將「Enable real-time sync」(啟用即時同步處理) 切換鈕設為開啟。
在「Client secret」(用戶端密鑰) 提供值。這個值將用來驗證 OneDrive Webhook 事件。建議使用長度為 20 個字元的字串。

啟用即時同步處理功能並提供用戶端密鑰。
按一下 [儲存]。

等待「Real-time sync」(即時同步處理) 欄位變更為「Running」(執行中)。

錯誤代碼

下表列出 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 無效或沒有 ACL。
ONEDRIVE_TOO_MANY_REQUESTS	傳送至 OneDrive 的 HTTP 要求過多。收到 HTTP 429 回應。

後續步驟

如要將資料儲存庫連結至應用程式，請按照「建立應用程式」中的步驟，建立應用程式並選取資料儲存庫。
如要在設定應用程式和資料儲存庫後，預覽搜尋結果的顯示方式，請參閱「預覽搜尋結果」。