Agente do conector do Microsoft Graph

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.

Configuração Recomendada

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:

• Windows 10, Windows Server 2016 R2 e versões superiores
• .NET Framework 4.7.2
• .NET Core Desktop Runtime 8.0 (x64)
• 8 núcleos, 3 GHz
• 16 GB de RAM, 2 GB de Espaço em Disco
• Acesso de rede à origem de dados e à Internet através da 443

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

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:

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:

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.

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".

   

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.

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.

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.

   

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:

   

   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".

   

   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ã:

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":

   

   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":

   

   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.

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.

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.