Agente connettore Microsoft Graph

L'uso di connettori locali richiede l'installazione del software dell'agente connettore Microsoft Graph . Consente il trasferimento sicuro dei dati tra i dati locali e le API del connettore. Questo articolo illustra come installare e configurare l'agente.

Installazione

Scaricare la versione più recente dell'agente connettore Microsoft Graph e installare il software usando la configurazione di installazione assistente. Le note sulla versione del software dell'agente connettore sono disponibili qui

Controllare i criteri di esecuzione

I criteri di esecuzione devono essere impostati per consentire l'esecuzione di script firmati remoti. Se i criteri a livello di computer o di gruppo limitano lo stesso, l'installazione di GCA ha esito negativo. Eseguire il comando seguente per ottenere i criteri di esecuzione:

Get-ExecutionPolicy -List

Per altre informazioni e impostare i criteri di esecuzione corretti, vedere Criteri di esecuzione.

Usando la configurazione consigliata del computer, l'istanza dell'agente connettore può gestire fino a tre connessioni. Eventuali connessioni successive potrebbero compromettere le prestazioni di tutte le connessioni nell'agente. Ecco la configurazione consigliata:

Se i server proxy o i firewall dell'organizzazione bloccano la comunicazione con domini sconosciuti, aggiungere le regole seguenti all'elenco 'consenti':

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/

Nota

L'autenticazione proxy non è supportata. Se l'ambiente ha un proxy che richiede l'autenticazione, è consigliabile consentire all'agente del connettore di ignorare il proxy.

Aggiornamento

Graph Connector Agent può essere aggiornato in due modi:

  1. Download e installazione manuale di Graph Connector Agent dal collegamento fornito nella sezione di installazione.

  2. Facendo clic sul pulsante "Aggiorna" disponibile nel riquadro di connessione, come illustrato nell'immagine: Snapshot di esempio di come aggiornare GCA con un clic dal riquadro di connessione.

Il pulsante di aggiornamento non è disponibile per gli agenti che aggiornano dalla versione 1.x alla versione 2.x. Seguire questa procedura se l'agente esegue l'aggiornamento dalla versione 1.x alla versione 2.x:

  1. Scaricare il programma di installazione dal collegamento fornito nella sezione di installazione.

  2. Il programma di installazione chiede di installare .NET 7 Desktop runtime, se non è già installato.

  3. Consentire la comunicazione con l'endpoint *.office.com.

  4. Dopo l'installazione, l'app di configurazione GCA viene riavviato. Se GCA non è registrato, accedere e procedere con la registrazione.

  5. Se GCA è già registrato, l'app di configurazione GCA visualizza il messaggio di esito positivo seguente: Snapshot di esempio dell'esito positivo del controllo integrità nella pagina di accesso GCA.

  6. Se si osservano errori, seguire i passaggi di mitigazione suggeriti nel messaggio di errore e chiudere & riaprire l'app di configurazione GCA.

  7. Se il messaggio di errore indica che non è possibile determinare l'integrità dell'agente. Se l'errore persiste, contattare il supporto tecnico.", riavviare GcaHostService (passaggi indicati nella sezione relativa alla risoluzione dei problemi) e aprire di nuovo l'app di configurazione GCA.

  8. È possibile eseguire i controlli in qualsiasi momento chiudendo e aprendo l'app di configurazione GCA o usando il pulsante "Controllo integrità" accanto al pulsante "Modifica" nella schermata dei dettagli di registrazione. Snapshot di esempio dell'esito positivo del controllo integrità nella pagina di registrazione GCA.

Creare e configurare un'app per l'agente

Prima di tutto, accedere e notare che il privilegio minimo richiesto per l'account è l'amministratore della ricerca. L'agente chiede quindi di fornire i dettagli di autenticazione. Usare la procedura per creare un'app e generare i dettagli di autenticazione necessari.

Creare un'app

  1. Passare alla portale di Azure e accedere con le credenziali di amministratore per il tenant.

  2. Passare a Microsoft Entra ID ->Registrazioni app dal riquadro di spostamento e selezionare Nuova registrazione.

  3. Specificare un nome per l'app e selezionare Registra.

  4. Prendere nota dell'ID applicazione (client).

  5. Aprire autorizzazioni API dal riquadro di spostamento e selezionare Aggiungi un'autorizzazione.

  6. Selezionare Microsoft Graph e quindi Autorizzazioni applicazione.

  7. Cercare le autorizzazioni seguenti e selezionare Aggiungi autorizzazioni.

    Autorizzazione Quando è necessaria l'autorizzazione
    ExternalItem.ReadWrite.OwnedBy o ExternalItem.ReadWrite.All Sempre
    ExternalConnection.ReadWrite.OwnedBy Sempre
    Directory.Read.All Obbligatorio per i connettori Condivisione file, MS SQL e Oracle SQL
  8. Selezionare Concedi consenso amministratore per [TenantName] e confermare selezionando .

  9. Verificare che le autorizzazioni siano nello stato "concesso".

    Autorizzazioni visualizzate come concesse in verde sulla colonna a destra.

Configurare l'autenticazione

È possibile fornire i dettagli di autenticazione usando un segreto client o un certificato. Seguire i passaggi di propria scelta.

Configurazione del segreto client per l'autenticazione

  1. Passare alla portale di Azure e accedere con le credenziali di amministratore per il tenant.

  2. Aprire Registrazione app dal riquadro di spostamento e passare all'app appropriata. In Gestisci selezionare Certificati e segreti.

  3. Selezionare Nuovo segreto client e selezionare un periodo di scadenza per il segreto. Copiare il segreto generato e salvarlo perché non viene visualizzato di nuovo.

  4. Usare questo segreto client e l'ID applicazione per configurare l'agente. I caratteri alfanumerici vengono accettati. Non è possibile usare spazi vuoti nel campo Nome dell'agente.

Uso di un certificato per l'autenticazione

L'uso dell'autenticazione basata su certificato prevede tre semplici passaggi:

  1. Creare o ottenere un certificato
  2. Caricare il certificato nel portale di Azure
  3. Assegnare il certificato all'agente
Passaggio 1: Ottenere un certificato

È possibile usare lo script per generare un certificato autofirma. L'organizzazione potrebbe non consentire certificati autofirmati. In tal caso, usare queste informazioni per comprendere i requisiti e acquisire un certificato in base ai criteri dell'organizzazione.

$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
Passaggio 2: Caricare il certificato nel portale di Azure
  1. Aprire l'applicazione e passare alla sezione certificati e segreti dal riquadro sinistro.

  2. Selezionare Carica certificato e caricare il file .cer.

  3. Aprire Registrazione app e selezionare Certificati e segreti nel riquadro di spostamento. Copiare l'identificazione personale del certificato.

Elenco dei certificati di identificazione personale quando vengono selezionati certificati e segreti nel riquadro sinistro.

Passaggio 3: Assegnare il certificato all'agente

L'uso dello script di esempio per generare un certificato salverebbe il file PFX nel percorso identificato nello script.

  1. Scaricare il file pfx del certificato nel computer agent.

  2. Fare doppio clic sul file pfx per avviare la finestra di dialogo di installazione del certificato.

  3. Selezionare Computer locale per il percorso dell'archivio durante l'installazione del certificato.

  4. Dopo aver installato il certificato, aprire Gestisci certificati computer tramite il menu Start .

  5. Selezionare il certificato appena installato in Certificati personali>.

  6. Selezionare e tenere premuto (o fare clic con il pulsante destro del mouse) sul certificato e selezionare Tutte le attività>Gestisci chiavi private opzione.

  7. Nella finestra di dialogo autorizzazioni selezionare aggiungi opzione. Viene visualizzata una nuova finestra. Selezionare l'opzione "Posizioni". Selezionare il computer in cui è installato l'agente tra le posizioni elencate e selezionare Ok.

  8. Nella finestra di dialogo di selezione dell'utente scrivere: NT Service\GcaHostService e selezionare Ok. Non selezionare il pulsante Controlla nomi .

  9. Selezionare OK nella finestra di dialogo delle autorizzazioni. Il computer dell'agente è ora configurato per consentire all'agente di generare token usando il certificato.

Risoluzione dei problemi

Errore di installazione

Se si verifica un errore di installazione, controllare i log di installazione eseguendo: msiexec /i "< path to msi >\GcaInstaller.msi" /L*V " destination< path >\install.log". Assicurarsi di non ricevere alcuna eccezione di sicurezza. In genere, queste eccezioni si verificano a causa di impostazioni dei criteri errate. I criteri di esecuzione devono essere firmati in remoto. Per altre informazioni, vedere la sezione "Installazione" di questo documento.

Se gli errori non sono risolvibili, inviare un messaggio di posta elettronica per il supporto tramite MicrosoftGraphConnectorsFeedback@service.microsoft.com con i log.

Errore di registrazione

Se l'accesso per configurare l'applicazione non riesce e viene visualizzato l'errore "Accesso non riuscito, selezionare il pulsante di accesso per riprovare", anche dopo l'autenticazione del browser, aprire services.msc e verificare se GcaHostService è in esecuzione. Se non viene avviato, avviarlo manualmente. In Gestione attività passare alla scheda Servizi, controllare se GcaHostService è in esecuzione. In caso contrario, fare clic con il pulsante destro del mouse e avviare il servizio.

Screenshot dei servizi in Gestione attività.

Quando il servizio non viene avviato con l'errore "Il servizio non è stato avviato a causa di un errore di accesso", verificare se l'account virtuale: "NT Service\GcaHostService" dispone dell'autorizzazione per l'accesso come servizio nel computer. Per istruzioni, vedere questo collegamento . Se l'opzione per aggiungere un utente o un gruppo è disattivata in Criteri locali\Assegnazione diritti utente, significa che l'utente che tenta di aggiungere questo account non dispone di privilegi di amministratore nel computer o che è stato sostituito da criteri di gruppo. I criteri di gruppo devono essere aggiornati per consentire al servizio host di accedere come servizio.

Errore post registrazione

Dopo la registrazione, alcune impostazioni locali possono influire sulla connettività dell'agente.

L'agente è offline

L'agente viene considerato offline se non è in grado di contattare i servizi del connettore Graph. In questi casi, seguire questa procedura:

  1. Controllare se l'agente è in esecuzione: accedere al computer in cui è installato l'agente e verificare se è in esecuzione. In Gestione attività passare alla scheda Servizi, controllare se GcaHostService è in esecuzione. In caso contrario, fare clic con il pulsante destro del mouse e avviare il servizio. Screenshot dei servizi in Gestione attività.

  2. Verificare se il gcs.office.com di dominio è raggiungibile. attenersi alla seguente procedura:

    • Da PowerShell eseguire il comando seguente:
    tnc gcs.office.com -Port 443
    

    La risposta deve contenere l'output "TcpTestSucceeded: True" come illustrato di seguito:

    Screenshot di tnc.

    Se è false, verificare che il dominio sia consentito nel proxy/firewall e che le richieste stiano passando attraverso il proxy.

    • Se non è possibile eseguire tnc perché il ping ICMP è bloccato nella rete, eseguire il comando seguente:
    wget https://gcs.office.com/v1.0/admin/AdminDataSetCrawl/healthcheck
    

    L'output deve contenere "StatusCode: 200".

    Screenshot di wget 200.

    Se non è 200, verificare che il dominio sia consentito nel proxy/firewall e che le richieste stiano passando attraverso il proxy.

  3. Se i passaggi sono stati superati correttamente e l'agente è ancora offline, controllare i log GCA per eventuali problemi relativi al proxy di rete.If the steps have successfully and the agent is still offline, check the GCA logs for any network proxy issues.

    • I log GcaHostService sono disponibili nel percorso specificato (potrebbe essere necessario passare manualmente a questo percorso- copia incolla in Esplora file potrebbe non funzionare):
      1. Per Windows Server 2016 sistema operativo: C:\Users\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
      2. Per tutte le altre versioni supportate del sistema operativo Windows: C:\Windows\ServiceProfiles\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
    • Ordinare i file di log nella cartella in ordine inverso di "Ora modifica" e aprire i due file più recenti.
    • Verificare la presenza di eventuali messaggi di errore con il testo seguente: "Impossibile effettuare alcuna connessione perché il computer di destinazione l'ha rifiutata attivamente".
      1. Ciò indica che si è verificato un problema con le impostazioni di rete che impedisce all'account virtuale GcaHostService di contattare "https://gcs.office.com" Endpoint.
      2. Rivolgersi al team di rete/proxy per consentire all'account virtuale (NT Service\GcaHostService) di inviare il traffico a questo dominio.
      3. È possibile verificare che il problema venga risolto se il file di log non contiene più questi errori.
  4. Se nessuno dei passaggi risolve il problema, contattare il supporto tecnico inviando un messaggio di posta elettronica a MicrosoftGraphConnectorsFeedback@service.microsoft.come fornire i due file di log più recenti dal percorso indicato in precedenza.

L'agente non è raggiungibile

Durante la configurazione della connessione se l'agente non è raggiungibile, viene visualizzata questa schermata:

Screenshot dell'agente non raggiungibile

Usando lo spazio dei nomi del bus di servizio fornito nei dettagli dell'errore, seguire questa procedura per risolvere i problemi:

  1. Da PowerShell eseguire il comando seguente:

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

    La risposta deve contenere l'output "TcpTestSucceeded: True":

    Screenshot di tnc 2.

    Se è false, verificare che il dominio sia consentito nel proxy/firewall e che le richieste stiano passando attraverso il proxy.

  2. Se non è possibile eseguire tnc perché il ping ICMP è bloccato nella rete, eseguire il comando seguente in PowerShell:

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

    L'output deve contenere "StatusCode: 200":

    Screenshot di wget 2.

    Se è false, verificare che il dominio sia consentito nel proxy/firewall e che le richieste stiano passando attraverso il proxy.

  3. Se nessuno dei passaggi risolve il problema, contattare il supporto tecnico inviando un messaggio di posta elettronica a MicrosoftGraphConnectorsFeedback@service.microsoft.come fornire i due file di log più recenti dal percorso indicato in precedenza.

Aggiornamento in corso

Questo errore viene visualizzato quando è già in corso un aggiornamento e l'errore dovrebbe sparire dopo un massimo di 30 minuti.

Screenshot dell'aggiornamento in corso.

Se l'errore persiste dopo 30 minuti, seguire questa procedura:

  1. Controllare se l'agente è in esecuzione: accedere al computer in cui è installato l'agente e verificare se è in esecuzione. In Gestione attività passare alla scheda Servizi, controllare se GcaHostService è in esecuzione. In caso contrario, fare clic con il pulsante destro del mouse e avviare il servizio. Screenshot dei servizi in Gestione attività 2.
  2. Se il problema persiste, contattare il supporto tecnico inviando un messaggio di posta elettronica a MicrosoftGraphConnectorsFeedback@service.microsoft.come fornire i due file di log più recenti. Passare manualmente al percorso per accedere ai log e condividere lo stesso con il team - C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

Errore di connessione

Se l'azione "Test connessione" ha esito negativo durante la creazione di una connessione e mostra l'errore "Verificare nome utente/password e il percorso dell'origine dati", anche quando il nome utente e la password specificati sono corretti, assicurarsi che l'account utente disponga dei diritti di accesso interattivi al computer in cui è installato l'agente del connettore. È possibile esaminare la documentazione sulla gestione dei criteri di accesso per controllare i diritti di accesso. Assicurarsi inoltre che l'origine dati e il computer agente si trovino nella stessa rete.