通过

Microsoft Graph 连接器代理

  • 项目

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

安装

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

检查执行策略

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

Get-ExecutionPolicy -List

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

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

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

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/

注意

不支持代理身份验证。 如果环境具有需要身份验证的代理，我们建议允许连接器代理绕过代理。

升级

可通过两种方式升级 Graph 连接器代理：

  1. 从安装部分提供的链接手动下载和安装 Graph 连接器代理。

  2. 单击连接窗格中可用的“升级”按钮，如下图所示： 如何在连接窗格中单击一下即可升级 GCA 的示例快照。

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

  1. 从安装部分中提供的链接下载安装程序。

  2. 安装程序会要求你安装 .NET 8 桌面运行时（如果尚未安装）。

  3. 允许与终结点 *.office.com 通信。

  4. 安装后，GCA 配置应用将重启。 如果未注册 GCA，请登录并继续注册。

  5. 如果已注册 GCA，GCA 配置应用会显示以下成功消息： GCA 登录页上运行状况检查成功的示例快照。

  6. 如果观察到任何错误，请按照错误消息中建议的缓解步骤操作，并关闭 & 重新打开 GCA 配置应用。

  7. 如果错误消息显示“无法确定代理的运行状况。 如果错误仍然存在，请联系支持人员。“ () 故障排除部分中提到的步骤重启 GcaHostService，然后再次打开 GCA 配置应用。

  8. 可以随时运行检查，方法是关闭并打开 GCA 配置应用，或使用注册详细信息屏幕中的“编辑”按钮旁边的“运行状况检查”按钮。 GCA 注册页上运行状况检查成功的示例快照。

为代理创建和配置应用

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

创建应用

  1. 转到 Azure 门户 ，并使用租户的管理员凭据登录。

  2. 从导航窗格中导航到 Microsoft Entra ID ->App 注册 ，然后选择“ 新建注册”。

  3. 提供应用的名称，然后选择“ 注册”。

  4. 记下应用程序 (客户端) ID。

  5. 从导航窗格中打开 API 权限 ，然后选择 “添加权限”。

  6. 选择 “Microsoft Graph ”，然后选择“ 应用程序权限”。

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

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

  8. 选择“ 为 [TenantName] 授予管理员同意” ，然后选择“ 是”进行确认。

  9. 检查权限是否处于“已授予”状态。

    右侧列中以绿色显示的权限显示为“授予”。

配置身份验证

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

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

  1. 转到 Azure 门户 ，并使用租户的管理员凭据登录。

  2. 从导航窗格中打开 “应用注册 ”，然后转到相应的应用。 在 “管理”下，选择“ 证书和机密”。

  3. 选择“ 新建客户端密码 ”，然后选择机密的到期期限。 复制生成的机密并保存，因为它不会再次显示。

  4. 使用此客户端密码和应用程序 ID 配置代理。 接受字母数字字符。 不能在代理的 “名称” 字段中使用空格。

使用证书进行身份验证

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

  1. 创建或获取证书
  2. 将证书上传到 Azure 门户
  3. 将证书分配给代理
步骤 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 门户

  1. 打开应用程序并导航到左窗格中的“证书和机密”部分。

  2. 选择“ 上传证书 ”并上传.cer文件。

  3. 打开 “应用注册 ”，然后从导航窗格中选择“ 证书和机密 ”。 复制证书指纹。

在左窗格中选择“证书”和“机密”时，指纹证书的列表。

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

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

  1. 将证书 pfx 文件下载到代理计算机上。

  2. 双击 pfx 文件以启动证书安装对话框。

  3. 安装证书时，选择“ 本地计算机 ”用于存储位置。

  4. 安装证书后，通过“开始”菜单打开“管理计算机证书”。

  5. 在“个人>证书”下选择新安装的证书。

  6. 选择并按住 (或右键单击证书上的) ，然后选择“ 所有任务>管理私钥 ”选项。

  7. 在“权限”对话框中，选择“添加”选项。 此时会弹出一个新窗口。 选择其中“位置”选项。 在列出的位置中选择安装代理的计算机，然后选择 “确定”。

  8. 在用户选择对话框中，写入： NT Service\GcaHostService ，然后选择 “确定”。 不要选择“ 检查名称” 按钮。

  9. 在“权限”对话框中选择“确定”。 代理计算机现在已配置为使用证书生成令牌。

疑难解答

安装失败

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

如果错误无法解决，请通过 MicrosoftGraphConnectorsFeedback@service.microsoft.com 向支持人员发送包含日志的电子邮件。

注册失败

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

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

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

注册后失败

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

代理处于脱机状态

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

  1. 检查代理是否正在运行 - 登录到安装了代理的计算机，并检查它是否正在运行。 在“任务管理器”中，转到“服务”选项卡，检查 GcaHostService 是否处于运行状态。 如果没有，请右键单击并启动服务。

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

  2. 检查是否可以访问域 gcs.office.com。 (对于 GCC 租户，请替换 gcsgcc.office.com，对于 GCCHigh 租户，请替换 gcs.office365.us，如初始表所示。) 请执行以下步骤：

    • 在 PowerShell 中运行以下命令：
    tnc gcs.office.com -Port 443

    响应应包含输出“TcpTestSucceeded： True”，如下所示：

    tnc 的屏幕截图。

    如果为 false，请验证代理/防火墙中是否允许该域，并且请求正在通过代理。

    • 对于更具体的测试，或者如果由于 ICMP ping 在网络中被阻止而无法运行 tnc，请运行以下命令：
    wget https://gcs.office.com/v1.0/admin/AdminDataSetCrawl/healthcheck

    输出应包含“StatusCode： 200”。

    wget 200 的屏幕截图。

    如果不是 200，请验证代理/防火墙中是否允许该域，并且请求正在通过代理。

  3. 如果步骤已成功通过，并且代理仍处于脱机状态，请检查 GCA 日志中是否存在任何网络代理问题。

    • 可以在给定的位置找到 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. 请与网络/代理团队联系，以允许虚拟帐户 (NT Service\GcaHostService) 将流量发送到此域。
      3. 如果日志文件不再包含这些错误，则可以验证问题是否已解决。

  4. 如果这些步骤都不能解决问题，请通过发送电子邮件到 MicrosoftGraphConnectorsFeedback@service.microsoft.com联系支持人员，并提供上述位置的两个最新日志文件。

无法访问代理

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

代理无法访问的屏幕截图

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

  1. 在 PowerShell 中运行以下命令：

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

    响应应包含输出“TcpTestSucceeded： True”：

    tnc 2 的屏幕截图。

    如果为 false，请验证代理/防火墙中是否允许该域，并且请求正在通过代理。

  2. 如果由于 ICMP Ping 在网络中被阻止而无法运行 tnc，请在 PowerShell 中运行以下命令：

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

    输出应包含“StatusCode： 200”：

    wget 2 的屏幕截图。

    如果为 false，请验证代理/防火墙中是否允许该域，并且请求正在通过代理。

  3. 如果这些步骤都不能解决问题，请通过发送电子邮件到 MicrosoftGraphConnectorsFeedback@service.microsoft.com联系支持人员，并提供上述位置的两个最新日志文件。

更新正在进行中

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

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

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

  1. 检查代理是否正在运行 - 登录到安装了代理的计算机，并检查它是否正在运行。 在“任务管理器”中，转到“服务”选项卡，检查 GcaHostService 是否处于运行状态。 如果没有，请右键单击并启动服务。 任务管理器 2 中服务的屏幕截图。

  2. 如果问题仍然存在，请通过向 发送电子邮件联系 MicrosoftGraphConnectorsFeedback@service.microsoft.com支持人员，并提供两个最新的日志文件。 手动遍历到访问日志的位置，并与团队共享相同的日志 - C：\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

连接失败

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