Microsoft Graph 連接器代理程式

發行項
06/19/2024

使用內部部署連接器需要安裝 Microsoft Graph 連接器代理 程式軟體。它允許在內部部署數據與連接器 API 之間進行安全的數據傳輸。本文會引導您安裝和設定代理程式。

安裝

下載最新版的 Microsoft Graph 連接器代理程式，並使用安裝組態助理安裝軟體。這裡提供連接器代理程式軟體的版本資訊

檢查執行原則

執行原則必須設定為允許執行遠端簽署的腳本。如果有任何機器或組層級原則限制相同，則 GCA 安裝會失敗。執行下列命令以取得執行原則：

Get-ExecutionPolicy -List

若要深入瞭解並設定正確的執行原則，請參閱執行原則。

建議的設定

使用機器的建議設定，連接器代理程序實例最多可以處理三個連線。超過此範圍的任何連線都可能會降低代理程式上所有連線的效能。以下是建議的設定：

Windows 10、Windows Server 2016 R2 和更新版本
.NET Framework 4.7.2
.NET Core Desktop Runtime 8.0 (x64)
8 核心，3 GHz
16 GB RAM、2 GB 磁碟空間
透過 443 對數據源和因特網的網路存取

如果您組織的 Proxy 伺服器或防火牆封鎖對未知網域的通訊，請將下列規則新增至 [允許] 清單：

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/`

注意事項

不支援 Proxy 驗證。如果您的環境有需要驗證的 Proxy，建議您允許連接器代理程式略過 Proxy。

升級

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

從安裝區段中提供的鏈接手動下載並安裝 Graph 連接器代理程式。
單擊 [連線] 窗格中可用的 [升級] 按鈕，如圖所示：

升級按鈕不適用於從 1.x 版升級至 2.x 版的代理程式。如果代理程式從 1.x 升級至 2.x 版，請遵循下列步驟：

從安裝區段中提供的鏈接下載安裝程式。
如果尚未安裝，安裝程式會要求您安裝 .NET 8 Desktop 運行時間。
允許與端點 *.office.com 通訊。
安裝後，GCA 組態應用程式會重新啟動。如果未註冊 GCA，請登入並繼續進行註冊。
如果 GCA 已註冊，GCA 組態應用程式會顯示下列成功訊息：
如果您發現任何錯誤，請遵循錯誤訊息中的建議風險降低步驟，並關閉 & 重新開啟 GCA 組態應用程式。
如果錯誤訊息顯示「無法判斷代理程式的健康情況。 如果錯誤持續發生，請連絡支持人員。」，請重新啟動 GcaHostService () 疑難解答一節中所述的步驟，然後再次開啟 GCA 組態應用程式。
您可以隨時關閉並開啟 GCA 組態應用程式，或使用註冊詳細數據畫面中 [編輯] 按鈕旁的 [健康情況檢查] 按鈕來執行檢查。

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

首先，登入並注意帳戶的最低必要許可權是搜尋系統管理員。代理程序接著會要求您提供驗證詳細數據。使用步驟來建立應用程式並產生必要的驗證詳細數據。

建立應用程式

移至 Azure 入口網站，並使用租用戶的系統管理員認證登入。
從瀏覽窗格流覽至 Microsoft Entra ID ->App registrations ]，然後選取 [ 新增註冊]。
提供應用程式的名稱，然後選取 [ 註冊]。
記下應用程式 (用戶端) 識別碼。
從瀏覽窗格開啟 API 許可權，然後選取 [ 新增許可權]。
選 取 [Microsoft圖形 ]，然後選取 [ 應用程式許可權]。

搜尋下列許可權，然後選取 [新增許可權]。

Permission	當是所需的許可權時
ExternalItem.ReadWrite.OwnedBy 或 ExternalItem.ReadWrite.All	需要一直連線
ExternalConnection.ReadWrite.OwnedBy	需要一直連線
Directory.Read.All	檔案共用、MS SQL 和 Oracle SQL 連接器的必要專案

選 取 [TenantName] 的 [授與系統管理員同意] ，然後選取 [ 是] 來確認。
檢查許可權是否處於「已授與」狀態。

設定驗證

您可以使用客戶端密碼或憑證來提供驗證詳細資料。請遵循您選擇的步驟。

設定客戶端密碼以進行驗證

移至 Azure 入口網站，並使用租用戶的系統管理員認證登入。
從瀏覽窗格開啟 [應用程式註冊 ]，然後移至適當的應用程式。在 [ 管理] 底下，選 取 [憑證和秘密]。
選 取 [新增客戶端密碼 ]，然後選取秘密的到期期間。複製產生的秘密並儲存它，因為它不會再次顯示。
使用此客戶端密碼和應用程式識別碼來設定代理程式。接受英數位元。您無法在代理程式的 [ 名稱 ] 字段中使用空白。

使用憑證進行驗證

使用憑證式驗證有三個簡單的步驟：

建立或取得憑證
將憑證上傳至 Azure 入口網站
將憑證指派給代理程式

步驟 1：取得憑證

您可以使用腳本來產生自我簽署憑證。您的組織可能不允許自我簽署憑證。在此情況下，請使用此資訊來瞭解需求，並根據組織的原則取得憑證。

$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
$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 入口網站

開啟應用程式，然後從左窗格流覽至 [憑證和秘密] 區段。
選 取 [上傳憑證 ] 並上傳.cer檔案。
開 啟 [應用程式註冊 ]，然後從瀏覽窗格中選取 [ 憑證和秘密 ]。複製憑證指紋。

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

使用範例腳本來產生憑證，會將 PFX 檔案儲存在腳本中識別的位置。

將憑證 pfx 檔案下載到代理程式計算機。
按兩下 pfx 檔案以啟動憑證安裝對話框。
安裝憑證時，選取 [ 本機計算機 ] 作為存放區位置。
安裝憑證之後，請透過 [開始] 功能表開啟 [管理計算機憑證]。
選取 [個人>憑證] 底下新安裝的憑證。
選取並按住 (，或以滑鼠右鍵按兩下憑證上的 [) ]，然後選取 [ 所有工作>管理私鑰 選項]。
在 [許可權] 對話框中，選取 [新增選項]。它會彈出新的視窗。選取其中的 [位置] 選項。選取代理程式安裝在所顯示位置中的計算機，然後選取 [ 確定]。
在用戶選取對話框中，寫入： NT Service\GcaHostService ，然後選取 [確定]。請勿選取 [ 檢查名稱] 按鈕。
在 [許可權] 對話框中選取 [確定]。代理程式計算機現在已設定為代理程式使用憑證產生令牌。

疑難排解

安裝失敗

如果安裝失敗，請執行：msiexec /i “< msi >\GcaInstaller.msi 的路徑” /L*V “< 目的地路徑 >\install.log” 來檢查安裝記錄。請確定您未收到任何安全性例外狀況。一般而言，這些例外狀況是因為原則設定錯誤所造成。執行原則必須是遠程簽署。若要深入瞭解，請參閱本檔的一節。

如果無法解決錯誤，請透過記錄傳送電子郵件給支持 MicrosoftGraphConnectorsFeedback@service.microsoft.com 人員。

註冊失敗

如果登入以設定應用程式失敗，並顯示錯誤：「登入失敗，請選取登入按鈕再試一次」，即使在瀏覽器驗證成功之後，仍開啟 services.msc 並檢查 GcaHostService 是否正在執行。如果未啟動，請手動啟動。在 [任務管理器] 中，移至 [服務] 索引標籤，檢查 GcaHostService 是否處於執行中狀態。如果沒有，請以滑鼠右鍵按下並啟動服務。

任務管理器中服務的螢幕快照。

當服務無法啟動，並出現錯誤「服務因為登入失敗而無法啟動」錯誤時，請檢查虛擬帳戶 “NT Service\GcaHostService” 是否有許可權在計算機上以服務身分登入。請檢查此連結以取得指示。如果 [本機原則\使用者權力指派] 中新增使用者或群組的選項呈現灰色，表示嘗試新增此帳戶的使用者在此計算機上沒有系統管理員許可權，或是有組策略覆寫它。必須更新組策略，才能讓主機服務以服務身分登入。

註冊失敗后

註冊之後，某些本機設定可能會影響代理程式的連線能力。

代理程序離線

如果代理程式無法連絡圖形連接器服務，則會將其視為離線。在這種情況下，請遵循下列步驟：

檢查代理程式是否正在執行 - 登入安裝代理程式的計算機，並檢查其是否正在執行。在 [任務管理器] 中，移至 [服務] 索引標籤，檢查 GcaHostService 是否處於執行中狀態。如果沒有，請以滑鼠右鍵按下並啟動服務。
檢查網域 gcs.office.com 是否可連線。 (針對 GCC 租使用者，請將 gcsgcc.office.com 取代為 GCCHigh 租使用者，並替代 gcs.office365.us，如初始數據表所示。) 請遵循下列步驟：
- 從 PowerShell 執行下列命令：
```
tnc gcs.office.com -Port 443
```
回應應該包含輸出「TcpTestSucceeded： True」，如下所示：

如果為 false，請確認您的 Proxy/防火牆中允許網域，且要求正在通過 Proxy。
- 如需更具體的測試，或如果您因為網路中的ICMP ping遭到封鎖而無法執行 tnc，請執行下列命令：
```
wget https://gcs.office.com/v1.0/admin/AdminDataSetCrawl/healthcheck
```
輸出應該包含「StatusCode： 200」。

如果不是 200，請確認您的 Proxy/防火牆中允許網域，且要求正在通過 Proxy。
如果步驟成功通過，且代理程式仍然離線，請檢查 GCA 記錄中是否有任何網路 Proxy 問題。
- 您可以在指定的位置找到 GcaHostService 紀錄 (您可能需要手動瀏覽至此路徑 - 在檔案總管中複製貼上可能無法運作) ：
  1. 針對 Windows Server 2016 OS：C：\Users\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
  2. 針對所有其他支援的 Windows OS 版本：C：\Windows\ServiceProfiles\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
- 以「修改時間」的反向順序排序資料夾中的記錄檔，並開啟最新的兩個檔案。
- 檢查是否有下列文字的錯誤訊息：「無法進行連線，因為目標計算機主動拒絕。」
  1. 這表示網路設定發生問題，導致 GcaHostService 虛擬帳戶無法連絡 https://gcs.office.com 端點。
  2. 請洽閱您的網路/Proxy 小組，以允許NT Service\GcaHostService) (虛擬帳戶將流量傳送至此網域。
  3. 如果記錄檔不再包含這些錯誤，您可以確認問題已解決。
如果沒有任何步驟可修正您的問題，請透過傳送電子郵件給來 MicrosoftGraphConnectorsFeedback@service.microsoft.com連絡支持人員，並從上述位置提供兩個最新的記錄檔。

無法連線到代理程式

如果代理程式無法連線，則在設定連線時，您會看到此畫面：

無法連線到代理程式的螢幕快照

使用錯誤詳細數據中提供的服務總線命名空間，請遵循下列步驟進行疑難解答：

從 PowerShell 執行下列命令：
```
tnc <yournamespacename>.servicebus.windows.net -port 443
```
回應應該包含輸出「TcpTestSucceeded： True」：

如果為 false，請確認您的 Proxy/防火牆中允許網域，且要求正在通過 Proxy。
如果您因為網路中的 ICMP Ping 遭到封鎖而無法執行 tnc，請在 PowerShell 中執行下列命令：
```
wget https://<yournamespacename>.servicebus.windows.net/
```
輸出應該包含「StatusCode： 200」：

如果為 false，請確認您的 Proxy/防火牆中允許網域，且要求正在通過 Proxy。
如果沒有任何步驟可修正您的問題，請透過傳送電子郵件給來 MicrosoftGraphConnectorsFeedback@service.microsoft.com連絡支持人員，並從上述位置提供兩個最新的記錄檔。

更新進行中

當更新已在進行中，且錯誤應該在最多 30 分鐘後消失時，就會出現此錯誤。

進行中更新的螢幕快照。

如果錯誤在 30 分鐘後持續發生，請遵循下列步驟：

檢查代理程式是否正在執行 - 登入安裝代理程式的計算機，並檢查其是否正在執行。在 [任務管理器] 中，移至 [服務] 索引標籤，檢查 GcaHostService 是否處於執行中狀態。如果沒有，請以滑鼠右鍵按下並啟動服務。
如果仍然看到問題，請傳送電子郵件給來 MicrosoftGraphConnectorsFeedback@service.microsoft.com連絡支持人員，並提供兩個最新的記錄檔。手動周遊至位置以存取記錄，並與小組共用相同的專案 - C：\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

線上失敗

如果「測試連線」動作在建立連線時失敗，並顯示錯誤「請檢查使用者名稱/密碼和數據源路徑」，即使提供的使用者名稱和密碼正確，也請確定用戶帳戶具有連接器代理程式安裝所在計算機的互動式登入許可權。您可以檢閱登入原則管理的相關文件，以檢查登入許可權。此外，請確定數據源和代理程式計算機位於相同的網路上。

共用方式為