Partilhar 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 o assistente de configuração de instalação. 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: Instantâneo de exemplo 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: Instantâneo de exemplo da verificação de estado de funcionamento bem-sucedida 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. Instantâneo de exemplo da Verificação de estado de funcionamento bem-sucedida na página de registo do GCA.

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 ao portal do Azure e inicie sessão com as credenciais de administrador do inquilino.

  2. Navegue para Microsoft Entra ID ->Registos de aplicações no 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 ao 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 na instalação, verifique 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, consulte 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 verifique se o GcaHostService está em execução. Se não iniciar, inicie-o manualmente. No Gestor de Tarefas, aceda ao separador Serviços, verifique se GcaHostService está 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", verifique se a conta virtual: "Serviço NT\GcaHostService" tem 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 verifique se está em execução. No Gestor de Tarefas, aceda ao separador Serviços, verifique se GcaHostService está 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, verifique se existem problemas com o proxy de rede nos registos do GCA.

    • 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 o SO Windows Server 2016: 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 verifique se está em execução. No Gestor de Tarefas, aceda ao separador Serviços, verifique se GcaHostService está 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 "Verifique o nome de utilizador/palavra-passe e o caminho da origem de dados", mesmo quando o nome de utilizador e a palavra-passe fornecidos estiverem 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 verificar os 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.