Compartilhar via

Agente do conector do Microsoft Graph

  • Artigo

A utilização de conectores no local requer a instalação do software do agente do conector do Microsoft Graph . Permite a transferência segura de dados entre os dados no local e as APIs do conector. Este artigo orienta-o ao longo da instalação e configuração do agente.

Instalação

Transfira a versão mais recente do agente do conector do Microsoft Graph e instale o software com a configuração de instalação assistente. As notas de versão do software do agente do conector estão disponíveis aqui

Verificar Política de Execução

A política de execução tem de ser definida para permitir a execução de scripts assinados remotamente. Se alguma política de nível de computador ou grupo estiver a restringir 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, veja Política de Execução.

Com a configuração recomendada do computador, a instância do agente do conector pode processar até três ligações. Quaisquer ligações para além dessa ligação podem degradar o desempenho de todas as ligações no agente. Eis 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

A autenticação de proxy não é suportada. Se o seu ambiente tiver um proxy que necessite de autenticação, recomendamos que permita que o agente do conector ignore o proxy.

Atualizar

O Agente do Conector de Grafos pode ser atualizado de duas formas:

  1. Transferir e instalar manualmente o Agente do Conector do Graph a partir da ligação fornecida na secção de instalação.

  2. Clicar no botão "Atualizar" disponível no painel de ligação, conforme mostrado na imagem: Exemplo snapshot de como atualizar o GCA com um clique no painel de ligação.

O botão de atualização não está disponível para agentes que atualizem da versão 1.x para a versão 2.x. Siga estes passos se o agente estiver a atualizar da versão 1.x para a versão 2.x:

  1. Transfira o instalador a partir da ligação fornecida na secção de instalação.

  2. O instalador pede-lhe para instalar o runtime de Ambiente de Trabalho do .NET 8, se ainda não estiver instalado.

  3. Permitir a comunicação com o ponto final *.office.com.

  4. Após a instalação, a aplicação de configuração GCA é reiniciada. Se o GCA não estiver registado, inicie sessão e prossiga com o registo.

  5. Se a GCA já estiver registada, a aplicação de configuração do GCA mostra a seguinte mensagem de êxito: Exemplo snapshot de Estado de Funcionamento marcar êxito na página de início de sessão do GCA.

  6. Se observar erros, siga os passos de mitigação sugeridos na mensagem de erro e feche & reabra a aplicação de configuração do GCA.

  7. Se a mensagem de erro indicar "Não é possível determinar o estado de funcionamento do agente. Se o erro persistir, contacte o suporte.", reinicie GcaHostService (passos mencionados na secção de resolução de problemas) e abra novamente a aplicação de configuração do GCA.

  8. Pode executar as verificações em qualquer altura ao fechar e abrir a aplicação GCA Config ou ao utilizar o botão "Verificação de Estado de Funcionamento" junto ao botão "Editar" no ecrã de detalhes de registo. Exemplo snapshot de estado de funcionamento marcar êxito na página de registo do GCA.

Observação

Se o Agente do Conector do Graph estiver desinstalado e reinstalado, todas as ligações existentes terão de ser recriadas. As ligações antigas tornam-se inutilizáveis e não podem ser recriadas. Após a nova instalação do agente, elimine as ligações mais antigas e crie novas.

Criar e configurar uma aplicação para o agente

Primeiro, inicie sessão e tenha em atenção que o privilégio mínimo necessário na conta é o administrador de pesquisa. Em seguida, o agente pede-lhe para fornecer detalhes de autenticação. Utilize os passos para criar uma aplicação e gerar os detalhes de autenticação necessários.

Criar um aplicativo

  1. Aceda à portal do Azure e inicie sessão com as credenciais de administrador do inquilino.

  2. Navegue para Microsoft Entra ID ->Registros de aplicativo a partir do painel de navegação e selecione Novo registo.

  3. Forneça um nome para a aplicação e selecione Registar.

  4. Anote o ID da aplicação (cliente).

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

  6. Selecione Microsoft Graph e, em seguida , Permissões da aplicação.

  7. Procure as seguintes permissões 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 a Partilha de ficheiros, conectores SQL ms e Oracle SQL

  8. Selecione Conceder consentimento do administrador para [TenantName] e confirme ao selecionar Sim.

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

    Permissões apresentadas como concedidas a verde na coluna da direita.

Configurar autenticação

Pode fornecer detalhes de autenticação com um segredo do cliente ou um certificado. Siga os passos à sua escolha.

Configurar o segredo do cliente para autenticação

  1. Aceda à portal do Azure e inicie sessão com as credenciais de administrador do inquilino.

  2. Abra o Registo de Aplicações a partir do painel de navegação e aceda à Aplicação adequada. Em Gerir, 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 guarde-o porque não é apresentado novamente.

  4. Utilize este Segredo do cliente e o ID da aplicação para configurar o agente. Os carateres alfanuméricos são aceites. Não pode utilizar espaços em branco no campo Nome do agente.

Utilizar um certificado para autenticação

Existem três passos simples para utilizar a autenticação baseada em certificados:

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

Pode utilizar o script para gerar um certificado autoassinado. A sua organização pode não permitir certificados autoassinados. Nesse caso, utilize estas informações para compreender 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 -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
Passo 2: carregar o certificado para o portal do Azure

  1. Abra a aplicação e navegue para a secção certificados e segredos a partir do painel esquerdo.

  2. Selecione Carregar certificado e carregue o ficheiro .cer.

  3. Abra o Registo de aplicações e selecione Certificados e segredos no painel de navegação. Copie o thumbprint do certificado.

Lista de certificados thumbprint quando os Certificados e segredos são selecionados no painel esquerdo.

Passo 3: atribuir o certificado ao agente

Utilizar o script de exemplo para gerar um certificado guardaria o ficheiro PFX na localização identificada no script.

  1. Transfira o ficheiro pfx do certificado para o computador agente.

  2. Faça duplo clique no ficheiro pfx para iniciar a caixa de diálogo de instalação do certificado.

  3. Selecione Computador Local para a localização do arquivo ao instalar o certificado.

  4. Depois de instalar o certificado, abra Gerir certificados de computador através do menu Iniciar .

  5. Selecione o certificado recentemente instalado emCertificadosPessoais>.

  6. Selecione sem soltar (ou clique com o botão direito do rato) no certificado e selecione a opção Todas as TarefasGerir Chaves Privadas>.

  7. Na caixa de diálogo permissões, selecione adicionar opção. Aparece uma nova janela. Selecione a opção "Localizações" na mesma. Selecione o computador no qual o agente está instalado entre as localizações listadas apresentadas e selecione Ok.

  8. Na caixa de diálogo de seleção do utilizador, escreva: Serviço NT\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 está agora configurado para o agente gerar tokens com o certificado.

Solução de problemas

Falha na instalação

Se ocorrer uma falha de instalação, marcar os registos de instalação ao executar: msiexec /i "< caminho para msi >\GcaInstaller.msi" /L*V "< caminho >de destino \install.log". Certifique-se de que não está a receber nenhuma exceção de segurança. Geralmente, estas exceções surgem devido a definições de política erradas. A política de execução tem de ser assinada remotamente. Para saber mais, marcar a secção "Instalação" deste documento.

Se os erros não forem resolvíveis, envie um e-mail para o suporte através MicrosoftGraphConnectorsFeedback@service.microsoft.com dos registos.

Falha no registo

Se o início de sessão para configurar a aplicação falhar e apresentar o erro "O início de sessão falhou, selecione o botão de início de sessão para tentar novamente", mesmo depois de a autenticação do browser ser bem-sucedida, abra services.msc e marcar se o GcaHostService estiver em execução. Se não iniciar, inicie-o manualmente. No Gestor de Tarefas, aceda ao separador Serviços, marcar se GcaHostService estiver no estado em execução. Caso contrário, clique com o botão direito do rato e inicie o serviço.

Captura de ecrã a mostrar os serviços no Gestor de Tarefas.

Quando o serviço não inicia com o erro "O serviço não foi iniciado devido a uma falha de início de sessão", marcar se a conta virtual: "Serviço NT\GcaHostService" tiver permissão para iniciar sessão como um serviço no computador. Consulte esta ligação para obter instruções. Se a opção para adicionar um utilizador ou grupo estiver desativada na Atribuição de Políticas Locais\Direitos de Utilizador, significa que o utilizador que está a tentar adicionar esta conta não tem privilégios de administrador neste computador ou existe uma política de grupo que a substitui. A política de grupo tem de ser atualizada para permitir que o serviço anfitrião inicie sessão como um serviço.

Falha de Registo Pós-registo

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

O agente está offline

O agente é considerado offline se não conseguir contactar os serviços do conector de grafos. Nestes casos, siga estes passos:

  1. Verifique se o agente está em execução – inicie sessão no computador onde o agente está instalado e marcar se estiver em execução. No Gestor de Tarefas, aceda ao separador Serviços, marcar se GcaHostService estiver no estado em execução. Caso contrário, clique com o botão direito do rato e inicie o serviço.

    Captura de ecrã a mostrar os serviços no Gestor de Tarefas.

  2. Verifique se o domínio gcs.office.com está acessível. (Para um inquilino GCC, substitua gcsgcc.office.com e, para um inquilino GCCHigh, substitua gcs.office365.us, conforme mostrado na tabela inicial.) Siga estes passos:

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

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

    Captura de ecrã do tnc.

    Se for falso, verifique se o domínio é permitido no proxy/firewall e se os pedidos estão a passar pelo proxy.

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

    O resultado deve conter "StatusCode: 200".

    Captura de ecrã do wget 200.

    Se não for 200, verifique se o domínio é permitido no proxy/firewall e se os pedidos estão a passar pelo proxy.

  3. Se os passos tiverem sido transmitidos com êxito e o agente ainda estiver offline, marcar os registos do GCA para quaisquer problemas de proxy de rede.

    • Os registos do GcaHostService podem ser encontrados na localização especificada (poderá ter de navegar manualmente para este caminho – copiar a pasta no explorador de ficheiros pode não funcionar):
      1. Para Windows Server 2016 SO: C:\Users\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
      2. Para todas as outras Versões suportadas do SO Windows: C:\Windows\ServiceProfiles\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
    • Ordene os ficheiros de registo na pasta por ordem inversa de "Hora da Modificação" e abra os dois ficheiros mais recentes.
    • Verifique se existem mensagens de erro com o seguinte texto: "Não foi possível efetuar qualquer ligação porque o computador de destino o recusou ativamente".
      1. Isto indica que existe um problema com as definições de rede que está a impedir que a conta virtual do GcaHostService contacte o https://gcs.office.com ponto final.
      2. Contacte a equipa de rede/proxy para permitir que a conta virtual (NT Service\GcaHostService) envie tráfego para este domínio.
      3. Pode verificar se o problema está resolvido se o ficheiro de registo já não contiver estes erros.

  4. Se nenhum dos passos corrigir o problema, contacte o suporte ao enviar um e-mail para MicrosoftGraphConnectorsFeedback@service.microsoft.come forneça os dois ficheiros de registo mais recentes a partir da localização acima mencionada.

O agente está inacessível

Ao configurar a ligação se o agente estiver inacessível, verá este ecrã:

Captura de ecrã a mostrar o Agente inacessível

Com o espaço de nomes do service bus fornecido nos detalhes do erro, siga estes passos para resolver o problema:

  1. No PowerShell, execute o seguinte comando:

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

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

    Captura de ecrã do tnc 2.

    Se for falso, verifique se o domínio é permitido no proxy/firewall e se os pedidos estão a passar pelo proxy.

  2. Se não conseguir executar o tnc porque o Ping ICMP está bloqueado na sua rede, execute o seguinte comando no PowerShell:

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

    O resultado deve conter "StatusCode: 200":

    Captura de ecrã a mostrar o wget 2.

    Se for falso, verifique se o domínio é permitido no proxy/firewall e se os pedidos estão a passar pelo proxy.

  3. Se nenhum dos passos corrigir o problema, contacte o suporte ao enviar um e-mail para MicrosoftGraphConnectorsFeedback@service.microsoft.come forneça os dois ficheiros de registo mais recentes a partir da localização acima mencionada.

Atualização em curso

Este erro é apresentado quando já existe uma atualização em curso e o erro deverá desaparecer após um máximo de 30 minutos.

Captura de ecrã a mostrar a atualização em curso.

Se o erro persistir após 30 minutos, siga estes passos:

  1. Verifique se o agente está em execução – inicie sessão no computador onde o agente está instalado e marcar se estiver em execução. No Gestor de Tarefas, aceda ao separador Serviços, marcar se GcaHostService estiver no estado em execução. Caso contrário, clique com o botão direito do rato e inicie o serviço. Captura de ecrã a mostrar os serviços no Gestor de Tarefas 2.

  2. Se o problema ainda estiver a ser visto, contacte o suporte ao enviar um e-mail para MicrosoftGraphConnectorsFeedback@service.microsoft.come forneça os dois ficheiros de registo mais recentes. Percorra manualmente a localização para aceder aos registos e partilhar os mesmos com a equipa – C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

Falha na ligação

Se a ação "Testar ligação" falhar ao criar uma ligação e mostrar o erro "Por favor, marcar nome de utilizador/palavra-passe e o caminho da origem de dados", mesmo quando o nome de utilizador e a palavra-passe fornecidos estão corretos, certifique-se de que a conta de utilizador tem direitos de início de sessão interativos no computador onde o agente do conector está instalado. Pode rever a documentação sobre a gestão de políticas de início de sessão para marcar direitos de início de sessão. Além disso, certifique-se de que a origem de dados e o computador do agente estão na mesma rede.