Agente do conector do Microsoft Graph

  • Artigo

O uso de conectores locais requer a instalação do software do agente conector do Microsoft Graph . Ele permite a transferência segura de dados entre dados locais e as APIs do conector. Este artigo orienta você a instalar e configurar o agente.

Instalação

Baixe a versão mais recente do agente conector do Microsoft Graph e instale o software usando a configuração de instalação assistente. Notas de versão do software do agente de conector estão disponíveis aqui

Verificar política de execução

A política de execução precisa ser definida para permitir a execução de scripts com assinatura remota. Se qualquer política de nível de máquina ou grupo estiver restringindo o mesmo, a instalação do GCA falhará. Execute o seguinte comando para obter a política de execução:

Get-ExecutionPolicy -List

Para saber mais e definir a política de execução correta, consulte Política de Execução.

Usando a configuração recomendada do computador, a instância do agente do conector pode lidar com até três conexões. Qualquer conexão além disso pode degradar o desempenho de todas as conexões no agente. Aqui está a configuração recomendada:

Se os servidores proxy ou firewalls da sua organização bloquearem a comunicação com domínios desconhecidos, adicione as seguintes regras à lista 'permitir':

M365 Enterprise 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/

Observação

Não há suporte para autenticação de proxy. Se o ambiente tiver um proxy que exija autenticação, recomendamos permitir que o agente conector ignore o proxy.

Atualizar

O Graph Connector Agent pode ser atualizado de duas maneiras:

  1. Baixar e instalar manualmente o Graph Connector Agent no link fornecido na seção de instalação.

  2. Clicando no botão "Atualizar" disponível no painel de conexão, conforme mostrado na imagem: Exemplo instantâneo de como atualizar o GCA com um clique no painel de conexão.

O botão de atualização não está disponível para agentes que atualizam da versão 1.x para a versão 2.x. Siga estas etapas se o agente estiver atualizando da versão 1.x para 2.x:

  1. Baixe o instalador do link fornecido na seção de instalação.

  2. O instalador pede que você instale o runtime do .NET 7 Desktop, se ainda não estiver instalado.

  3. Permitir comunicação para o ponto de extremidade *.office.com.

  4. Após a instalação, o aplicativo de configuração GCA é reiniciado. Se O GCA não estiver registrado, entre e prossiga com o registro.

  5. Se o GCA já estiver registrado, o aplicativo de configuração GCA mostrará a seguinte mensagem de sucesso: Exemplo instantâneo de integridade marcar sucesso na página de entrada do GCA.

  6. Se você observar erros, siga as etapas de mitigação sugeridas na mensagem de erro e feche & reabra o aplicativo de configuração GCA.

  7. Se a mensagem de erro diz: "Não é possível determinar a integridade do agente. Se o erro persistir, entre em contato com support.", reinicie GcaHostService(etapas mencionadas na seção de solução de problemas) e abra o aplicativo de configuração GCA novamente.

  8. Você pode executar as verificações a qualquer momento fechando e abrindo o aplicativo GCA Config ou usando o botão "Verificação de Integridade" ao lado do botão "Editar" na tela de detalhes do registro. Exemplo instantâneo de êxito do marcar de Integridade na página de registro do GCA.

Criar e configurar um aplicativo para o agente

Primeiro, entre e observe que o privilégio mínimo necessário na conta é o administrador de pesquisa. Em seguida, o agente pede que você forneça detalhes de autenticação. Use as etapas para criar um aplicativo e gerar os detalhes de autenticação necessários.

Criar um aplicativo

  1. Acesse o portal do Azure e entre com credenciais de administrador para o locatário.

  2. Navegue até Microsoft Entra ID ->Registros de aplicativo no painel de navegação e selecione Novo registro.

  3. Forneça um nome para o aplicativo e selecione Registrar.

  4. Anote a ID do aplicativo (cliente).

  5. Abra permissões de API no painel de navegação e selecione Adicionar uma permissão.

  6. Selecione Microsoft Graph e, em seguida , permissões de aplicativo.

  7. Pesquisa para as permissões a seguir e selecione Adicionar permissões.

    Permissão Quando é necessária a permissão
    ExternalItem.ReadWrite.OwnedBy ou ExternalItem.ReadWrite.All Sempre
    ExternalConnection.ReadWrite.OwnedBy Sempre
    Directory.Read.All Necessário para o compartilhamento de arquivos, conectores SQL e Oracle SQL da MS

  8. Selecione Conceder consentimento de administrador para [TenantName] e confirme selecionando Sim.

  9. Verifique se as permissões estão no estado "concedido".

    Permissões mostradas como concedidas em verde na coluna à direita.

Configurar autenticação

Você pode fornecer detalhes de autenticação usando um segredo do cliente ou um certificado. Siga as etapas de sua escolha.

Configurando o segredo do cliente para autenticação

  1. Acesse o portal do Azure e entre com credenciais de administrador para o locatário.

  2. Abra o Registro de Aplicativo no painel de navegação e acesse o Aplicativo apropriado. Em Gerenciar, selecione Certificados e segredos.

  3. Selecione Novo Segredo do Cliente e selecione um período de expiração para o segredo. Copie o segredo gerado e salve-o porque ele não é mostrado novamente.

  4. Use esse segredo do cliente e a ID do aplicativo para configurar o agente. Caracteres alfanuméricos são aceitos. Você não pode usar espaços em branco no campo Nome do agente.

Usando um certificado para autenticação

Há três etapas simples para usar a autenticação baseada em certificado:

  1. Criar ou obter um certificado
  2. Carregar o certificado no portal do Azure
  3. Atribuir o certificado ao agente
Etapa 1: Obter um certificado

Você pode usar o script para gerar um certificado autoassinado. Sua organização pode não permitir certificados autoassinados. Nesse caso, use essas informações para entender os requisitos e adquirir um certificado de acordo com as políticas da sua organização.

$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
Etapa 2: carregar o certificado no portal do Azure

  1. Abra o aplicativo e navegue até a seção certificados e segredos do painel esquerdo.

  2. Selecione Carregar certificado e carregar o arquivo .cer.

  3. Abra o registro do aplicativo e selecione Certificados e segredos no painel de navegação. Copie a impressão digital do certificado.

Lista de certificados de impressão digital quando certificados e segredos são selecionados no painel esquerdo.

Etapa 3: Atribuir o certificado ao agente

Usar o script de exemplo para gerar um certificado salvaria o arquivo PFX no local identificado no script.

  1. Baixe o arquivo pfx de certificado no computador Agent.

  2. Clique duas vezes no arquivo pfx para iniciar a caixa de diálogo de instalação do certificado.

  3. Selecione Máquina Local para o local da loja durante a instalação do certificado.

  4. Depois de instalar o certificado, abra Gerenciar certificados de computador por meio do menu Iniciar .

  5. Selecione o certificado recém-instalado emCertificadosPessoais>.

  6. Selecione e segure (ou clique com o botão direito do mouse) no certificado e selecione Todas as tarefas>gerenciar chaves privadas .

  7. Na caixa de diálogo permissões, selecione adicionar opção. Ele aparece em uma nova janela. Selecione a opção 'Locais' nele. Selecione o computador em qual agente está instalado entre os locais listados mostrados e selecione Ok.

  8. Na caixa de diálogo seleção do usuário, escreva: NT Service\GcaHostService e selecione Ok. Não selecione o botão Verificar Nomes .

  9. Selecione ok na caixa de diálogo permissões. O computador do agente agora está configurado para que o agente gere tokens usando o certificado.

Solução de problemas

Falha na instalação

Se houver uma falha de instalação, marcar os logs de instalação executando: msiexec /i "< caminho para msi >\GcaInstaller.msi" /L*V "< caminho >de destino \install.log". Verifique se você não está recebendo nenhuma exceção de segurança. Geralmente, essas exceções surgem devido a configurações de política erradas. A política de execução precisa ser assinada remotamente. Para saber mais, marcar a seção "Instalação" deste documento.

Se os erros não forem solucionados, envie um email para dar suporte por meio MicrosoftGraphConnectorsFeedback@service.microsoft.com dos logs.

Falha no registro

Se a entrada para configurar o aplicativo falhar e mostrar o erro, "Falha ao entrar, selecione o botão de entrada para tentar novamente", mesmo depois que a autenticação do navegador for bem-sucedida, abra services.msc e marcar se gcaHostService estiver em execução. Se ele não começar, inicie-o manualmente. Na guia Gerenciador de Tarefas, acesse a guia Serviços, marcar se GcaHostService estiver no estado em execução. Caso contrário, clique com o botão direito do mouse e inicie o serviço.

Captura de tela dos serviços no Gerenciador de Tarefas.

Quando o serviço não começa com o erro "O serviço não foi iniciado devido a uma falha de logon", marcar se a conta virtual: "NT Service\GcaHostService" tem permissão para entrar como um serviço no computador. Verifique este link para obter instruções. Se a opção de adicionar um usuário ou grupo estiver acinzentado na Atribuição Políticas Locais\Direitos do Usuário, isso significa que o usuário que tenta adicionar essa conta não tem privilégios de administrador neste computador ou há uma política de grupo substituindo-a. A política de grupo precisa ser atualizada para permitir que o serviço host faça logon como serviço.

Falha de registro pós-registro

Após o registro, algumas configurações locais podem afetar a conectividade do agente.

O agente está offline

O agente será considerado offline se não conseguir contatar serviços de conector de grafo. Nesses casos, siga estas etapas:

  1. Verifique se o agente está em execução – entre no computador em que o agente está instalado e marcar se ele está em execução. Na guia Gerenciador de Tarefas, acesse a guia Serviços, marcar se GcaHostService estiver no estado em execução. Caso contrário, clique com o botão direito do mouse e inicie o serviço.

    Captura de tela dos serviços no Gerenciador de Tarefas.

  2. Verifique se o gcs.office.com de domínio é acessível. (Para um locatário do GCC, substitua gcsgcc.office.com e por um locatário GCCHigh, substitua gcs.office365.us, conforme mostrado na tabela inicial.) Siga estas etapas:

    • No PowerShell, execute o seguinte comando:
    tnc gcs.office.com -Port 443

    A resposta deve conter a saída "TcpTestSucceededed: True", conforme mostrado:

    Captura de tela do tnc.

    Se for falso, verifique se o domínio é permitido em seu proxy/firewall e as solicitações estão passando pelo proxy.

    • Para um teste mais específico ou se você não puder executar o tnc porque o ping ICMP está bloqueado em sua rede, execute o seguinte comando:
    wget https://gcs.office.com/v1.0/admin/AdminDataSetCrawl/healthcheck

    A saída deve conter "StatusCode: 200".

    Captura de tela do wget 200.

    Se não for 200, verifique se o domínio é permitido em seu proxy/firewall e as solicitações estão passando pelo proxy.

  3. Se as etapas tiverem passado com êxito e o agente ainda estiver offline, marcar os logs de GCA para quaisquer problemas de proxy de rede.

    • Os logs do GcaHostService podem ser encontrados no local determinado (talvez seja necessário navegar manualmente até esse caminho – copiar colar no gerenciador de arquivos pode não funcionar):
      1. Para Windows Server 2016 sistema operacional: C:\Users\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
      2. Para todas as outras versões compatíveis do sistema operacional Windows: C:\Windows\ServiceProfiles\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
    • Classifique os arquivos de log na pasta na ordem inversa de "Tempo Modificado" e abra os dois arquivos mais recentes.
    • Verifique se há mensagens de erro com o seguinte texto: "Nenhuma conexão pode ser feita porque o computador de destino recusou ativamente.".
      1. Isso indica que há um problema com as configurações de rede que está impedindo a conta virtual do GcaHostService de entrar em contato com o https://gcs.office.com ponto de extremidade.
      2. Verifique com sua equipe de rede/proxy para permitir que a conta virtual (NT Service\GcaHostService) envie tráfego para esse domínio.
      3. Você pode verificar se o problema está resolvido se o arquivo de log não contiver mais esses erros.

  4. Se nenhuma das etapas corrigir o problema, entre em contato com o suporte enviando um email para MicrosoftGraphConnectorsFeedback@service.microsoft.come forneça os dois arquivos de log mais recentes do local mencionado acima.

O agente é inacessível

Ao configurar a conexão se o agente estiver inacessível, você verá esta tela:

Captura de tela do Agente inacessível

Usando o namespace do barramento de serviço fornecido nos detalhes do erro, siga estas etapas para solucionar problemas:

  1. No PowerShell, execute o seguinte comando:

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

    A resposta deve conter a saída "TcpTestSucceededed: True":

    Captura de tela do tnc 2.

    Se for falso, verifique se o domínio é permitido em seu proxy/firewall e as solicitações estão passando pelo proxy.

  2. Se você não puder executar o tnc porque o ICMP Ping está bloqueado em sua rede, execute o seguinte comando no PowerShell:

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

    A saída deve conter "StatusCode: 200":

    Captura de tela do wget 2.

    Se for falso, verifique se o domínio é permitido em seu proxy/firewall e as solicitações estão passando pelo proxy.

  3. Se nenhuma das etapas corrigir o problema, entre em contato com o suporte enviando um email para MicrosoftGraphConnectorsFeedback@service.microsoft.come forneça os dois arquivos de log mais recentes do local mencionado acima.

Atualização em andamento

Esse erro aparece quando já há uma atualização em andamento e o erro deve desaparecer após um máximo de 30 minutos.

Captura de tela da atualização em andamento.

Se o erro persistir após 30 minutos, siga estas etapas:

  1. Verifique se o agente está em execução – entre no computador em que o agente está instalado e marcar se ele está em execução. Na guia Gerenciador de Tarefas, acesse a guia Serviços, marcar se GcaHostService estiver no estado em execução. Caso contrário, clique com o botão direito do mouse e inicie o serviço. Captura de tela dos serviços no Gerenciador de Tarefas 2.

  2. Se o problema ainda for visto, entre em contato com o suporte enviando um email para MicrosoftGraphConnectorsFeedback@service.microsoft.come forneça os dois arquivos de log mais recentes. Atravesse manualmente até o local para acessar os logs e compartilhar o mesmo com a equipe - C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

Falha de conexão

Se a ação "Testar conexão" falhar ao criar uma conexão e mostrar o erro, "Por favor, marcar nome de usuário/senha e o caminho da fonte de dados", mesmo quando o nome de usuário e a senha fornecidos estiverem corretos, verifique se a conta de usuário tem direitos de entrada interativos para o computador em que o agente conector está instalado. Você pode examinar a documentação sobre o gerenciamento de políticas de logon para marcar direitos de entrada. Além disso, verifique se a fonte de dados e o computador agente estão na mesma rede.