共用方式為

Microsoft Graph 連接器代理程式

使用本地連接器需要安裝 Microsoft Graph 連接器代理 軟體。 它允許本地資料與連接器 API 之間安全傳輸資料。 本文將引導你安裝與設定代理程式。

安裝

下載最新版本的 Microsoft Graph 連接器代理程式，並使用安裝設定助理安裝軟體。 連接器代理軟體的發布說明可在此取得

注意事項

請保持 GCA 版本的最新，以確保功能完整。

檢查執行策略

執行策略必須設定為允許執行遠端簽署腳本。 若任何機器或群組層級政策限制相同，GCA 安裝即告失敗。 執行以下指令以取得執行策略：

Get-ExecutionPolicy -List

欲了解更多資訊，請參閱 執行政策。

必要條件

在進行安裝和設定前，請確認你擁有每個步驟所需的 RBAC 角色。

步驟 RBAC 的角色
本地安裝代理程式 搜尋管理員、全域管理員、副駕駛管理員。
在 Entra ID 註冊應用程式 全球 管理員、Azure App 管理員、Azure 管理員。
在目標伺服器上建立服務帳號 請參考連接器的設定頁面。

依照機器建議的配置，連接器代理實例最多可處理三個連線。 超過這個範圍的連線可能會降低代理所有連線的效能。 以下是建議的配置：

如果您的組織代理伺服器或防火牆阻擋了與未知網域的通訊，請將以下規則加入「允許」清單：

M365企業號 M365 GCC M365 GCCH
1. *.servicebus.windows.net 1. *.servicebus.usgovcloudapi.net 1. *.servicebus.usgovcloudapi.net
2. *.events.data.microsoft.com 2. *.events.data.microsoft.com 2. *.events.data.microsoft.com
3. *.office.com 3. *.office.com 3. *.office.com， *.office365.us
4. https://login.microsoftonline.com 4. https://login.microsoftonline.com 4. https://login.microsoftonline.com， https://login.microsoftonline.us
5. https://gcs.office.com/ 5. https://gcsgcc.office.com 5. https://gcs.office365.us/
6. https://graph.microsoft.com/ 6. https://graph.microsoft.com 6. https://graph.microsoft.com/， https://graph.microsoft.us/

注意事項

代理驗證不被支援。 如果您的環境有需要驗證的代理，我們建議允許連接器代理繞過該代理。

升級

Microsoft Graph 連接器代理程式可透過兩種方式升級：

  1. 請從安裝區段提供的連結手動下載並安裝 Microsoft Graph 連接器代理程式。

  2. 點擊連線面板中的 升級 按鈕，如圖片所示： 從連接面板一鍵升級 GCA 的範例快照。

    從 1.x 版本升級到 2.x 版本的客服人員無法使用升級按鈕。 如果代理從 1.x 升級到 2.x 版本，請依照以下步驟操作：

  3. 請從安裝區提供的連結下載安裝程式。

  4. 安裝程式會要求你安裝 .NET 8 Desktop 執行時，如果還沒安裝的話。

  5. 允許與端點的通訊 *.office.com。

  6. 安裝後，GCA 設定應用程式會重新啟動。 如果GCA尚未註冊，請登入並繼續註冊。

  7. 若 GCA 已註冊，GCA 設定應用程式會顯示以下成功訊息： GCA 登入頁面健康檢查成功範例快照。

  8. 如果發現任何錯誤，請依照錯誤訊息中建議的緩解步驟操作，關閉 & 重新開啟 GCA 設定應用程式。

  9. 如果錯誤訊息顯示「無法判斷代理的健康狀況。 如果錯誤依舊，請聯絡客服。」) ， (故障排除部分提到的步驟重新啟動 GcaHostService，並重新開啟 GCA 設定應用程式。

  10. 你可以隨時透過關閉並開啟 GCA 設定應用程式，或在註冊詳情頁面中「編輯」按鈕旁的「健康檢查」按鈕來執行檢查。 GCA註冊頁面健康檢查成功範例。

注意事項

如果 Microsoft Graph 連接器代理程式被卸載並重新安裝，所有現有連線都必須重新建立。 舊連線變得無法使用，無法重建。 重新安裝代理程式後，刪除舊連線並建立新的。

建立並設定代理的應用程式

首先，登入並注意該帳號的最低權限是搜尋管理員。 接著客服會要求你提供認證資料。 請依照步驟建立應用程式並產生所需的驗證資料。

建立應用程式

  1. 進入 Azure 入口網站，並用租戶的管理員憑證登入。

  2. 從導覽窗格中導覽到 Microsoft Entra ID ->應用程式註冊，並選擇新註冊。

  3. 請提供應用程式名稱並選擇 註冊。

  4. 請記錄申請 (客戶) ID。

  5. 從導覽窗格開啟 API 權限 ，選擇 新增權限。

  6. 選擇 Microsoft Graph ，然後選擇 應用程式權限。

  7. 搜尋以下權限，選擇 新增權限。

    Permission 何時需要取得許可
    外部項目.ReadWrite.OwnedBy 或 ExternalItem.ReadWrite.All 需要一直連線
    外部連線。讀寫。擁有者 需要一直連線
    Directory.Read.All Confluence DC、Github 伺服器、檔案分享、MS SQL 及 Oracle SQL 連接器皆為必要

  8. 選擇 [TenantName] 授予管理員同意 ，並選擇 「是」確認。

  9. 檢查權限是否處於「已授權」狀態。

    右側欄綠色顯示授權。

設定驗證

你可以用客戶端秘密或憑證提供認證細節。 依照你選擇的步驟走。

設定用戶端秘密以進行認證

  1. 進入 Azure 入口網站，並用租戶的管理員憑證登入。

  2. 從導覽面板開啟 應用程式註冊 ，然後前往相應的應用程式。 在 管理中，選擇 憑證與秘密。

  3. 選擇 新客戶端秘密 ，並設定秘密的有效期限。 複製產生的秘密並存起來，因為它不會再顯示。

  4. 使用這個客戶端秘密和應用程式 ID 來設定代理程式。 接受字母數字字元。 你不能在代理人 的名稱 欄位使用空白。

使用憑證進行認證

使用憑證認證有三個簡單步驟：

  1. 建立或取得證書
  2. 將憑證上傳到 Azure 入口網站
  3. 將憑證指派給代理人
步驟一：取得證書

你可以用腳本產生自簽憑證。 您的組織可能不允許自簽證書。 在這種情況下，請利用這些資訊了解需求，並依照貴組織的政策取得證書。

$dnsName = "<TenantDomain like agent.onmicrosoft.com>" # Your DNS name
$password = "<password>" # Certificate password
$folderPath = "D:\New folder\" # Where do you want the files to get saved to? The folder needs to exist.
$fileName = "agentcert" # What do you want to call the cert files? without the file extension
$yearsValid = 10 # Number of years until you need to renew the certificate
$certStoreLocation = "cert:\LocalMachine\My"
$expirationDate = (Get-Date).AddYears($yearsValid)
$certificate = New-SelfSignedCertificate -DnsName $dnsName -CertStoreLocation $certStoreLocation -NotAfter $expirationDate -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
$certificatePath = $certStoreLocation + '\' + $certificate.Thumbprint
$filePath = $folderPath + '\' + $fileName
$securePassword = ConvertTo-SecureString -String $password -Force -AsPlainText
Export-Certificate -Cert $certificatePath -FilePath ($filePath + '.cer')
Export-PfxCertificate -Cert $certificatePath -FilePath ($filePath + '.pfx') -Password $securePassword
步驟 2：將憑證上傳到 Azure 入口網站

  1. 打開應用程式，並進入 「憑證與秘密」選項。

  2. 選擇 上傳憑證 並上傳.cer檔案。

  3. 開啟 應用程式註冊 並選擇 憑證與秘密。 複製證書的指紋。

    當在左側窗格選擇憑證與秘密時，拇指印章憑證清單。

步驟 3：將憑證指派給代理人

使用範例腳本產生憑證，PFX 檔案會儲存在腳本中指定的位置。

  1. 將憑證 pfx 檔案下載到 Agent 機器上。

  2. 雙擊 pfx 檔案即可啟動憑證安裝對話框。

  3. 安裝憑證時，選擇「 本地機器 」作為儲存地點。

  4. 安裝憑證後，請透過開始選單開啟「管理電腦憑證」。

  5. 在 個人>憑證中選擇新安裝的憑證。

  6. 選擇並長按 (或右鍵點擊憑證上的) ，然後選擇 「所有任務>」「管理私鑰」。

  7. 在權限對話框中，選擇 新增。 它會跳出一個新視窗。 選擇「地點」。 在列出的位置中選擇安裝代理程式的機器，並選擇 確定。

  8. 在使用者選擇對話框中，寫入： NT Service\GcaHostService ，並選擇 Ok。 不要選擇 「支票名稱」。

  9. 在權限對話框中選擇 確定 。 代理機器現在已設定讓代理能利用憑證產生憑證。

疑難排解

安裝失敗

如果安裝失敗，請執行以下操作：msiexec /i “< path to msi >\GcaInstaller.msi” /L*V “< destination path >\install.log”。 確保你沒有遇到任何安全例外。 通常，這些例外是因為政策設定錯誤所致。 執行政策需要遠端簽署。 欲了解更多，請參閱本文件的「安裝」部分。

如果錯誤無法解決，請寄信給 Microsoft Graph |用日誌來支援 。

註冊失敗

如果登入設定應用程式失敗，且出現錯誤訊息「登入失敗，請選擇登入按鈕再試一次」，即使瀏覽器認證成功後，請打開 services.msc 並檢查 GcaHostService 是否正在執行。 如果發不動，就手動啟動。 在工作管理員中，前往 服務區，檢查 GcaHostService 是否處於執行狀態。 如果沒有，請右鍵點擊並開始服務。

工作管理員中服務的截圖。

當服務因登入失敗而無法啟動時，請檢查虛擬帳號「NT Service\GcaHostService」是否有權限以服務身份登入該機器。 請點 此連結 查看說明。 如果在本地政策\使用者權限指派中新增使用者或群組的選項是灰色的，表示嘗試新增該帳號的使用者在這台機器上沒有管理員權限，或者有群組政策覆蓋了它。 群組政策需要更新，才能讓主機服務以服務身份登入。

註冊後失敗

註冊後，某些本地設定可能會影響代理的連線。

客服人員離線

如果代理無法聯絡 Microsoft Graph 連接器服務，則視為離線狀態。 在這種情況下，請遵循以下步驟：

  1. 檢查代理程式是否正在運行——登入安裝代理程式的機器，確認是否在運行。 在工作管理員中，前往 服務，檢查 GcaHostService 是否處於執行狀態。 如果沒有，請右鍵點擊並開始服務。

    工作管理員中服務的截圖。

  2. 檢查網域 gcs.office.com 是否可聯繫。 (GCC租戶可 gcsgcc.office.com 替代，GCCHigh租戶則可 gcs.office365.us，如初始表格所示。) 請依照以下步驟操作：

  • 從 PowerShell 執行以下指令：

    tnc gcs.office.com -Port 443

    回應應包含輸出「TcpTestSucceeded： True」，如圖所示：

    TNC 的截圖。

    如果是錯誤的，請確認該網域是否被你的代理/防火牆允許，且請求是否透過代理伺服器進行。

    • 若要進行更具體的測試，或是因為網路阻擋了 ICMP ping，無法執行 tnc，請執行以下指令：

      wget https://gcs.office.com/v1.0/admin/AdminDataSetCrawl/healthcheck

      輸出應該包含「StatusCode： 200」。

      WGET 200 的截圖。

      如果不是 200，請確認該網域是否被你的代理/防火牆允許，且請求是否透過代理伺服器進行。

  1. 如果步驟成功通過且代理仍離線，請檢查 GCA 日誌是否有網路代理問題。

    • GcaHostService 的日誌可以在指定位置找到 (你可能需要手動導航到這條路徑——檔案總管裡的複製貼上可能無法) ：
      1. 針對 Windows Server 2016 作業系統：C：\Users\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
      2. 其他支援的 Windows 作業系統版本：C：\Windows\ServiceProfiles\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
    • 將資料夾中的日誌檔案依照「修改時間」的倒序排序，並打開最新的兩個檔案。
    • 檢查是否有錯誤訊息，文字如下：「無法建立連線，因為目標機器主動拒絕。」
      1. 表示網路設定出了問題，導致 GcaHostService 虛擬帳號無法聯絡端 https://gcs.office.com 點。
      2. 請向你的網路/代理團隊確認，允許虛擬帳號 (NT Service\GcaHostService) ，將流量傳送到該網域。
      3. 如果日誌檔不再包含這些錯誤，你可以驗證問題是否已解決。

  2. 如果這些步驟都無法解決問題，請寄信給 Microsoft Graph |支援並提供上述兩個最新的日誌檔。

代理人無法聯繫

在設定連線時，如果客服無法聯繫，你會看到這個畫面：

無法聯繫的特工截圖

利用錯誤細節中提供的服務匯流排命名空間，請依照以下步驟進行故障排除：

  1. 從 PowerShell 執行以下指令：

    tnc `<yournamespacename>.servicebus.windows.net` -port 443

    回應應包含輸出「TcpTestSucceeded： True」：

    TNC 2 的截圖。

    如果是錯誤的，請確認該網域是否被你的代理/防火牆允許，且請求是否透過代理伺服器進行。

  2. 如果你無法執行 tnc，因為 ICMP Ping 在你的網路中被封鎖，請在 PowerShell 中執行以下指令：

    wget https://`<yournamespacename>`.servicebus.windows.net/

    輸出應該包含「StatusCode： 200」：

    WGET 2 的截圖。

    如果是錯誤的，請確認該網域是否被你的代理/防火牆允許，且請求是否透過代理伺服器進行。

  3. 如果這些步驟都無法解決問題，請寄信給 Microsoft Graph |支援並提供上述兩個最新的日誌檔。

更新進行中

這個錯誤會在已有更新進行時出現，且最多 30 分鐘後應該會消失。

更新進行中的截圖。

如果錯誤在30分鐘後依然存在，請依照以下步驟操作：

  1. 檢查代理程式是否正在運行——登入安裝代理程式的機器，確認是否在運行。 在工作管理員中，前往 服務，檢查 GcaHostService 是否處於執行狀態。 如果沒有，請右鍵點擊並開始服務。 工作管理員 2 中服務的截圖。

  2. 如果問題仍然存在，請寄信給 Microsoft Graph |支援並提供兩個最新的日誌檔。 手動前往存取日誌的位置，並與團隊分享 - C：\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs+

連線故障

如果「測試連線」動作在建立連線時失敗，且出現錯誤訊息「請檢查使用者名稱/密碼及資料來源路徑」，即使提供的使用者名稱和密碼正確，請確保使用者帳號對安裝連接代理程式的機器擁有互動式登入權限。 你可以查看有關 登入政策管理 的文件，檢查登入權限。 同時，確保資料來源與代理機器在同一網路上。

  • Last updated on