Microsoft Graph 连接器代理

项目
02/04/2025

使用本地连接器需要安装 Microsoft Graph 连接器代理 软件。它允许在本地数据和连接器 API 之间安全传输数据。本文将指导你安装和配置代理。

安装

下载最新版本的 Microsoft Graph 连接器代理，并使用安装配置助手安装软件。此处提供了连接器代理软件的发行说明

检查执行策略

必须设置执行策略以允许执行远程签名脚本。如果任何计算机或组级策略限制相同，GCA 安装将失败。运行以下命令以获取执行策略：

Get-ExecutionPolicy -List

若要了解详细信息并设置正确的执行策略，请参阅执行策略。

建议的配置

使用建议的计算机配置，连接器代理实例最多可以处理三个连接。超出此范围的任何连接都可能会降低代理上所有连接的性能。下面是建议的配置：

Windows 10、Windows Server 2016 R2 及更高版本
.NET Framework 4.7.2
.NET Core 桌面运行时 8.0 (x64)
8 核，3 GHz
16 GB RAM，2 GB 磁盘空间
通过 443 网络访问数据源和 Internet

如果组织的代理服务器或防火墙阻止与未知域的通信，请将以下规则添加到“允许”列表：

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 连接器代理：

从安装部分中提供的链接手动下载并安装 Microsoft Graph 连接器代理。
单击连接窗格中可用的“升级”按钮，如图所示：

升级按钮不适用于从 1.x 版本升级到 2.x 版本的代理。如果代理从 1.x 升级到 2.x 版本，请执行以下步骤：

从安装部分中提供的链接下载安装程序。
安装程序会要求你安装 .NET 8 桌面运行时（如果尚未安装）。
允许与终结点 *.office.com 通信。
安装后，GCA 配置应用将重启。如果未注册 GCA，请登录并继续注册。
如果已注册 GCA，GCA 配置应用会显示以下成功消息：GCA
如果观察到任何错误，请按照错误消息中建议的缓解步骤作，并关闭 & 重新打开 GCA 配置应用。
如果错误消息显示“无法确定代理的运行状况。 如果错误仍然存在，请联系支持人员。“ () 故障排除部分中提到的步骤重启 GcaHostService，然后再次打开 GCA 配置应用。
可以随时运行检查，方法是关闭并打开 GCA 配置应用，或使用注册详细信息屏幕中的“编辑”按钮旁边的“运行状况检查”按钮。

注意

如果卸载并重新安装 Microsoft Graph 连接器代理，则需要重新创建所有现有连接。旧连接不可用，无法重新创建。重新安装代理后，删除旧连接并创建新连接。

为代理创建和配置应用

首先，登录并注意帐户所需的最低权限是搜索管理员。然后，代理会要求你提供身份验证详细信息。按照步骤创建应用并生成所需的身份验证详细信息。

创建应用

转到Azure 门户并使用租户的管理员凭据登录。
从导航窗格中导航到 Microsoft Entra ID ->应用注册，然后选择“新建注册”。
提供应用的名称，然后选择“ 注册”。
记下应用程序 (客户端) ID。
从导航窗格中打开 API 权限 ，然后选择 “添加权限”。
选择 “Microsoft Graph ”，然后选择“ 应用程序权限”。

搜索以下权限，然后选择“ 添加权限”。

权限	何时需要权限
ExternalItem.ReadWrite.OwnedBy 或 ExternalItem.ReadWrite.All	始终
ExternalConnection.ReadWrite.OwnedBy	始终
Directory.Read.All	文件共享、MS SQL 和 Oracle SQL 连接器需要

选择“ 为 [TenantName] 授予管理员同意” ，然后选择“ 是”进行确认。
检查权限是否处于“已授予”状态。

配置身份验证

可以使用客户端密码或证书提供身份验证详细信息。按照所选步骤进行作。

配置用于身份验证的客户端密码

转到Azure 门户并使用租户的管理员凭据登录。
从导航窗格中打开 “应用注册 ”，然后转到相应的应用。在 “管理”下，选择“ 证书和机密”。
选择“ 新建客户端密码 ”，然后选择机密的到期期限。复制生成的机密并保存，因为它不会再次显示。
使用此客户端密码和应用程序 ID 配置代理。接受字母数字字符。不能在代理的 “名称” 字段中使用空格。

使用证书进行身份验证

使用基于证书的身份验证有三个简单步骤：

创建或获取证书
将证书上传到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 -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 门户

打开应用程序并导航到左窗格中的“证书和机密”部分。
选择“ 上传证书 ”并上传.cer文件。
打开 “应用注册 ”，然后从导航窗格中选择“ 证书和机密 ”。复制证书指纹。

步骤 3：将证书分配给代理

使用示例脚本生成证书会将 PFX 文件保存在脚本中标识的位置。

将证书 pfx 文件下载到代理计算机上。
双击 pfx 文件以启动证书安装对话框。
安装证书时，选择“ 本地计算机 ”以获取存储位置。
安装证书后，通过“开始”菜单打开“管理计算机证书”。
在“个人>证书”下选择新安装的证书。
选择并按住 (或右键单击证书上的) ，然后选择“ 所有任务>管理私钥”。
在权限对话框中，选择 “添加”。此时会弹出一个新窗口。选择“位置”。在列出的位置中选择安装代理的计算机，然后选择“ 确定”。
在用户选择对话框中，写入： NT Service\GcaHostService ，然后选择 “确定”。不要选择“ 检查名称”。
在“权限”对话框中选择“确定”。代理计算机现在已配置为使用证书生成令牌。

疑难解答

安装失败

如果安装失败，请运行 msiexec /i “msi\GcaInstaller.msi 路径>”</L*V “目标路径 >\install.log”<来检查安装日志。请确保未收到任何安全异常。通常，由于策略设置错误，会出现这些异常。需要对执行策略进行远程签名。若要了解详细信息，检查本文档的“安装”部分。

如果错误无法解决，请发送电子邮件到 Microsoft Graph |对日志的支持。

注册失败

如果登录配置应用程序失败并显示错误“登录失败，请选择登录按钮重试”，即使在浏览器身份验证成功后，打开 services.msc 并检查 GcaHostService 正在运行。如果未启动，请手动启动。在任务管理器中，转到“服务”，检查 GcaHostService 是否处于运行状态。如果没有，请右键单击并启动服务。

任务管理器中服务的屏幕截图。

当服务无法启动并出现错误“由于登录失败，服务未启动”时，如果虚拟帐户“NT Service\GcaHostService”有权在计算机上以服务身份登录，则检查。有关说明，请查看此链接。如果“本地策略”\“用户权限分配”中“添加用户或组”选项灰显，则表示尝试添加此帐户的用户在此计算机上没有管理员权限，或者有一个组策略替代它。需要更新组策略，以允许主机服务作为服务登录。

注册后失败

注册后，某些本地设置可能会影响代理的连接。

代理处于脱机状态

如果代理无法联系 Microsoft Graph 连接器服务，则代理被视为脱机。在这种情况下，请执行以下步骤：

检查代理是否正在运行 - 登录到安装了代理的计算机，并检查它是否正在运行。在任务管理器中，转到“服务”，检查 GcaHostService 是否处于运行状态。如果没有，请右键单击并启动服务。
检查域 gcs.office.com 是否可以访问。 (对于 GCC 租户，请替换 gcsgcc.office.com，对于 GCCHigh 租户，请替换 gcs.office365.us，如初始表所示。) 请执行以下步骤：
- 在 PowerShell 中运行以下命令：
```
tnc gcs.office.com -Port 443
```
响应应包含输出“TcpTestSucceeded： True”，如下所示：

如果为 false，请验证代理/防火墙中是否允许该域，以及请求是否通过代理。
- 对于更具体的测试，或者如果由于 ICMP ping 在网络中被阻止而无法运行 tnc，请运行以下命令：
```
wget https://gcs.office.com/v1.0/admin/AdminDataSetCrawl/healthcheck
```
输出应包含“StatusCode： 200”。

如果不是 200，请验证代理/防火墙中是否允许域，以及请求是否通过代理。
如果步骤已成功通过，并且代理仍处于脱机状态，检查 GCA 日志中是否存在任何网络代理问题。
- 可以在给定的位置找到 GcaHostService 日志， (可能需要手动导航到此路径 - 在文件资源管理器中复制粘贴可能无法) ：
  1. 对于Windows Server 2016作系统：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. 请与网络/代理团队联系，以允许虚拟帐户 (NT Service\GcaHostService) 将流量发送到此域。
  3. 如果日志文件不再包含这些错误，则可以验证问题是否已解决。
如果这些步骤都无法解决问题，请发送电子邮件至 Microsoft Graph |支持，并提供来自上述位置的两个最新日志文件。

无法访问代理

在设置连接（如果代理无法访问）时，会看到以下屏幕：

代理无法访问的屏幕截图

使用错误详细信息中提供的服务总线命名空间，按照以下步骤进行故障排除：

在 PowerShell 中运行以下命令：
```
tnc <yournamespacename>.servicebus.windows.net -port 443
```
响应应包含输出“TcpTestSucceeded： True”：

如果为 false，请验证代理/防火墙中是否允许该域，以及请求是否通过代理。
如果由于 ICMP Ping 在网络中被阻止而无法运行 tnc，请在 PowerShell 中运行以下命令：
```
wget https://<yournamespacename>.servicebus.windows.net/
```
输出应包含“StatusCode： 200”：

如果为 false，请验证代理/防火墙中是否允许该域，以及请求是否通过代理。
如果这些步骤都无法解决问题，请发送电子邮件至 Microsoft Graph |支持，并提供来自上述位置的两个最新日志文件。

更新正在进行中

如果更新已在进行中，并且错误应在最多 30 分钟后消失，则会出现此错误。

正在进行更新的屏幕截图。

如果错误在 30 分钟后仍然存在，请执行以下步骤：

检查代理是否正在运行 - 登录到安装了代理的计算机，并检查它是否正在运行。在任务管理器中，转到“服务”，检查 GcaHostService 是否处于运行状态。如果没有，请右键单击并启动服务。
如果问题仍然存在，请向 Microsoft Graph 发送电子邮件 |支持并提供两个最新的日志文件。手动遍历到访问日志的位置，并与团队共享相同的日志 - C：\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

连接失败

如果在创建连接时“测试连接”作失败并显示错误“请检查用户名/密码和数据源路径”（即使提供的用户名和密码正确），请确保用户帐户具有对安装了连接器代理的计算机的交互式登录权限。可以查看有关登录策略管理的文档，以检查登录权限。此外，请确保数据源和代理计算机位于同一网络上。

通过