Freigeben über

Microsoft Graph-Connector-Agent

  • Artikel

Die Verwendung lokaler Connectors erfordert die Installation von Microsoft Graph-Connector-Agent-Software . Es ermöglicht eine sichere Datenübertragung zwischen lokalen Daten und den Connector-APIs. Dieser Artikel führt Sie durch die Installation und Konfiguration des Agents.

Installation

Laden Sie die neueste Version des Microsoft Graph-Connector-Agents herunter, und installieren Sie die Software mithilfe des Installationskonfigurations-Assistenten. Versionshinweise zur Connector-Agent-Software finden Sie hier.

Überprüfen der Ausführungsrichtlinie

Die Ausführungsrichtlinie muss festgelegt werden, um die Ausführung von remote signierten Skripts zu ermöglichen. Wenn eine Richtlinie auf Computer- oder Gruppenebene dasselbe einschränkt, schlägt die Installation von GCA fehl. Führen Sie den folgenden Befehl aus, um die Ausführungsrichtlinie abzurufen:

Get-ExecutionPolicy -List

Weitere Informationen und das Festlegen der richtigen Ausführungsrichtlinie finden Sie unter Ausführungsrichtlinie.

Mit der empfohlenen Konfiguration des Computers kann die Connector-Agent-Instanz bis zu drei Verbindungen verarbeiten. Alle darüber hinausgehend betreffenden Verbindungen können die Leistung aller Verbindungen auf dem Agent beeinträchtigen. Dies ist die empfohlene Konfiguration:

Wenn die Proxyserver oder Firewalls Ihrer Organisation die Kommunikation mit unbekannten Domänen blockieren, fügen Sie der Zulassungsliste die folgenden Regeln hinzu:

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/

Hinweis

Die Proxyauthentifizierung wird nicht unterstützt. Wenn Ihre Umgebung über einen Proxy verfügt, der eine Authentifizierung erfordert, wird empfohlen, dass der Connector-Agent den Proxy umgehen kann.

Upgraden

Der Graph-Connector-Agent kann auf zwei Arten aktualisiert werden:

  1. Manuelles Herunterladen und Installieren des Graph-Connector-Agents über den Link im Installationsabschnitt.

  2. Klicken Sie auf die Schaltfläche "Upgrade", die im Verbindungsbereich verfügbar ist, wie in der Abbildung gezeigt: Beispielmomentaufnahme zum Aktualisieren von GCA mit einem Klick im Verbindungsbereich.

Die Upgradeschaltfläche ist für Agents, die von Version 1.x auf Version 2.x aktualisieren, nicht verfügbar. Führen Sie die folgenden Schritte aus, wenn der Agent von version 1.x auf 2.x aktualisiert wird:

  1. Laden Sie das Installationsprogramm über den Link im Installationsabschnitt herunter.

  2. Das Installationsprogramm fordert Sie auf, die .NET 8 Desktop-Runtime zu installieren, falls sie noch nicht installiert ist.

  3. Zulassen der Kommunikation mit dem Endpunkt *.office.com.

  4. Nach der Installation wird die GCA-Konfigurations-App neu gestartet. Wenn GCA nicht registriert ist, melden Sie sich an, und fahren Sie mit der Registrierung fort.

  5. Wenn GCA bereits registriert ist, zeigt die GCA-Konfigurations-App die folgende Erfolgsmeldung an: Beispielmomentaufnahme der erfolgreichen Integritätsprüfung auf der GCA-Anmeldeseite.

  6. Wenn Sie Fehler feststellen, führen Sie die vorgeschlagenen Schritte zur Entschärfung in der Fehlermeldung aus, und schließen Sie & öffnen Sie die GCA-Konfigurations-App erneut.

  7. Wenn die Fehlermeldung lautet: "Die Integrität des Agents kann nicht bestimmt werden. Wenn der Fehler weiterhin auftritt, wenden Sie sich an den Support.", starten Sie GcaHostService neu (Schritte im Abschnitt zur Problembehandlung), und öffnen Sie die GCA-Konfigurations-App erneut.

  8. Sie können die Überprüfungen jederzeit ausführen, indem Sie die GCA-Konfigurations-App schließen und öffnen oder die Schaltfläche "Integritätsprüfung" neben der Schaltfläche "Bearbeiten" im Bildschirm mit den Registrierungsdetails verwenden. Beispielmomentaufnahme der erfolgreichen Integritätsprüfung auf der GCA-Registrierungsseite.

Erstellen und Konfigurieren einer App für den Agent

Melden Sie sich zunächst an, und beachten Sie, dass die mindestens erforderliche Berechtigung für das Konto der Suchadministrator ist. Der Agent fordert Sie dann auf, Authentifizierungsdetails anzugeben. Führen Sie die Schritte aus, um eine App zu erstellen und die erforderlichen Authentifizierungsdetails zu generieren.

App erstellen

  1. Wechseln Sie zum Azure-Portal , und melden Sie sich mit Administratoranmeldeinformationen für den Mandanten an.

  2. Navigieren Sie im Navigationsbereich zu Microsoft Entra ID ->App-Registrierungen , und wählen Sie Neue Registrierung aus.

  3. Geben Sie einen Namen für die App an, und wählen Sie Registrieren aus.

  4. Notieren Sie sich die Anwendungs-ID (Client-ID).

  5. Öffnen Sie API-Berechtigungen im Navigationsbereich, und wählen Sie Berechtigung hinzufügen aus.

  6. Wählen Sie Microsoft Graph und dann Anwendungsberechtigungen aus.

  7. Suchen Sie nach den folgenden Berechtigungen, und wählen Sie Berechtigungen hinzufügen aus.

    Berechtigung Wann ist die Erforderliche Berechtigung?
    ExternalItem.ReadWrite.OwnedBy oder ExternalItem.ReadWrite.All Immer
    ExternalConnection.ReadWrite.OwnedBy Immer
    Directory.Read.All Erforderlich für Dateifreigabe-, MS SQL- und Oracle SQL-Connectors

  8. Wählen Sie Administratoreinwilligung für [TenantName] erteilen aus, und bestätigen Sie, indem Sie Ja auswählen.

  9. Überprüfen Sie, ob sich die Berechtigungen im Status "Gewährt" befinden.

    Berechtigungen, die in der rechten Spalte grün als erteilt angezeigt werden.

Konfigurieren einer Authentifizierung

Sie können Authentifizierungsdetails mithilfe eines geheimen Clientschlüssels oder zertifikats angeben. Führen Sie die Schritte Ihrer Wahl aus.

Konfigurieren des geheimen Clientschlüssels für die Authentifizierung

  1. Wechseln Sie zum Azure-Portal , und melden Sie sich mit Administratoranmeldeinformationen für den Mandanten an.

  2. Öffnen Sie die App-Registrierung im Navigationsbereich, und wechseln Sie zur entsprechenden App. Wählen Sie unter Verwalten die Option Zertifikate und Geheimnisse aus.

  3. Wählen Sie Neuer geheimer Clientschlüssel und dann einen Ablaufzeitraum für das Geheimnis aus. Kopieren Sie das generierte Geheimnis, und speichern Sie es, da es nicht erneut angezeigt wird.

  4. Verwenden Sie diesen geheimen Clientschlüssel und die Anwendungs-ID, um den Agent zu konfigurieren. Alphanumerische Zeichen werden akzeptiert. Sie können keine Leerzeichen im Feld Name des Agents verwenden.

Verwenden eines Zertifikats für die Authentifizierung

Für die Verwendung der zertifikatbasierten Authentifizierung gibt es drei einfache Schritte:

  1. Erstellen oder Abrufen eines Zertifikats
  2. Hochladen des Zertifikats in das Azure-Portal
  3. Zuweisen des Zertifikats zum Agent
Schritt 1: Abrufen eines Zertifikats

Sie können das Skript verwenden, um ein selbstsigniertes Zertifikat zu generieren. Ihre Organisation lässt möglicherweise keine selbstsignierten Zertifikate zu. Verwenden Sie in diesem Fall diese Informationen, um die Anforderungen zu verstehen und ein Zertifikat gemäß den Richtlinien Ihrer Organisation zu erwerben.

$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
Schritt 2: Hochladen des Zertifikats in das Azure-Portal

  1. Öffnen Sie die Anwendung, und navigieren Sie im linken Bereich zum Abschnitt Zertifikate und Geheimnisse.

  2. Wählen Sie Zertifikat hochladen aus, und laden Sie die .cer-Datei hoch.

  3. Öffnen Sie die App-Registrierung , und wählen Sie im Navigationsbereich Zertifikate und Geheimnisse aus. Kopieren Sie den Zertifikatfingerabdruck.

Liste der Fingerabdruckzertifikate, wenn Zertifikate und Geheimnisse im linken Bereich ausgewählt sind.

Schritt 3: Zuweisen des Zertifikats zum Agent

Die Verwendung des Beispielskripts zum Generieren eines Zertifikats würde die PFX-Datei an dem im Skript angegebenen Speicherort speichern.

  1. Laden Sie die Pfx-Zertifikatdatei auf den Agent-Computer herunter.

  2. Doppelklicken Sie auf die pfx-Datei, um das Dialogfeld für die Zertifikatinstallation zu starten.

  3. Wählen Sie lokaler Computer als Speicherort bei der Installation des Zertifikats aus.

  4. Öffnen Sie nach der Installation des Zertifikats über das StartmenüComputerzertifikate verwalten.

  5. Wählen Sie unter Persönliche> Zertifikate das neu installierte Zertifikataus.

  6. Halten Sie das Zertifikat gedrückt (oder klicken Sie mit der rechten Maustaste darauf), und wählen Sie Die Option Alle Aufgaben>Private Schlüssel verwalten aus.

  7. Wählen Sie im Dialogfeld "Berechtigungen" die Option hinzufügen aus. Es wird ein neues Fenster geöffnet. Wählen Sie darin die Option "Standorte" aus. Wählen Sie unter den angezeigten Speicherorten den Computer aus, auf dem der Agent installiert ist, und klicken Sie auf OK.

  8. Geben Sie im Dialogfeld für die Benutzerauswahl Folgendes ein: NT Service\GcaHostService , und wählen Sie OK aus. Wählen Sie nicht die Schaltfläche Namen überprüfen aus.

  9. Klicken Sie im Dialogfeld "Berechtigungen" auf OK. Der Agent-Computer ist jetzt so konfiguriert, dass der Agent Token mithilfe des Zertifikats generiert.

Problembehandlung

Installationsfehler

Wenn ein Installationsfehler auftritt, überprüfen Sie die Installationsprotokolle, indem Sie folgendes ausführen: msiexec /i "< path to msi >\GcaInstaller.msi" /L*V "< destination path >\install.log". Stellen Sie sicher, dass sie keine Sicherheits exception erhalten. Im Allgemeinen treten diese Ausnahmen aufgrund falscher Richtlinieneinstellungen auf. Die Ausführungsrichtlinie muss remote signiert sein. Weitere Informationen finden Sie im Abschnitt "Installation" dieses Dokuments.

Wenn die Fehler nicht behebt werden können, senden Sie eine E-Mail an den Support über MicrosoftGraphConnectorsFeedback@service.microsoft.com mit den Protokollen.

Registrierungsfehler

Wenn bei der Anmeldung zum Konfigurieren der Anwendung ein Fehler auftritt und der Fehler "Fehler bei der Anmeldung, wählen Sie die Anmeldeschaltfläche aus, um es erneut zu versuchen", auch nach erfolgreicher Browserauthentifizierung, öffnen Sie services.msc, und überprüfen Sie, ob GcaHostService ausgeführt wird. Wenn es nicht gestartet wird, starten Sie es manuell. Wechseln Sie im Task-Manager zur Registerkarte Dienste, und überprüfen Sie, ob GcaHostService den Status "Wird ausgeführt" aufweist. Andernfalls klicken Sie mit der rechten Maustaste, und starten Sie den Dienst.

Screenshot der Dienste im Task-Manager.

Wenn der Dienst nicht mit dem Fehler "Der Dienst wurde aufgrund eines Anmeldefehlers nicht gestartet" gestartet werden kann, überprüfen Sie, ob das virtuelle Konto "NT Service\GcaHostService" über die Berechtigung zum Anmelden als Dienst auf dem Computer verfügt. Anweisungen finden Sie unter diesem Link . Wenn die Option zum Hinzufügen eines Benutzers oder einer Gruppe unter Lokale Richtlinien\Zuweisung von Benutzerrechten ausgegraut ist, bedeutet dies, dass der Benutzer, der versucht, dieses Konto hinzuzufügen, keine Administratorrechte auf diesem Computer hat oder dass eine Gruppenrichtlinie dies außer Kraft setzt. Die Gruppenrichtlinie muss aktualisiert werden, damit sich der Hostdienst als Dienst anmelden kann.

Fehler nach der Registrierung

Nach der Registrierung können sich einige lokale Einstellungen auf die Konnektivität des Agents auswirken.

Agent ist offline

Der Agent gilt als offline, wenn er keine Verbindung mit Graph-Connectordiensten herstellen kann. Führen Sie in solchen Fällen die folgenden Schritte aus:

  1. Überprüfen Sie, ob der Agent ausgeführt wird: Melden Sie sich bei dem Computer an, auf dem der Agent installiert ist, und überprüfen Sie, ob er ausgeführt wird. Wechseln Sie im Task-Manager zur Registerkarte Dienste, und überprüfen Sie, ob GcaHostService den Status "Wird ausgeführt" aufweist. Andernfalls klicken Sie mit der rechten Maustaste, und starten Sie den Dienst.

    Screenshot der Dienste im Task-Manager.

  2. Überprüfen Sie, ob gcs.office.com der Domäne erreichbar ist. (Ersetzen Sie für einen GCC-Mandanten gcsgcc.office.com, und ersetzen Sie für einen GCCHigh-Mandanten gcs.office365.us, wie in der ausgangstabelle gezeigt.) Führen Sie die folgenden Schritte aus:

    • Führen Sie in PowerShell den folgenden Befehl aus:
    tnc gcs.office.com -Port 443

    Die Antwort sollte die Ausgabe "TcpTestSucceeded: True" wie gezeigt enthalten:

    Screenshot von tnc.

    Wenn es false ist, überprüfen Sie, ob die Domäne in Ihrem Proxy/Ihrer Firewall zulässig ist und Anforderungen den Proxy durchlaufen.

    • Führen Sie für einen spezifischeren Test oder wenn Sie tnc nicht ausführen können, weil DER ICMP-Ping in Ihrem Netzwerk blockiert ist, den folgenden Befehl aus:
    wget https://gcs.office.com/v1.0/admin/AdminDataSetCrawl/healthcheck

    Die Ausgabe sollte "StatusCode: 200" enthalten.

    Screenshot von wget 200.

    Wenn es nicht 200 ist, überprüfen Sie, ob die Domäne in Ihrem Proxy/Ihrer Firewall zulässig ist und Anforderungen den Proxy durchlaufen.

  3. Wenn die Schritte erfolgreich ausgeführt wurden und der Agent weiterhin offline ist, überprüfen Sie die GCA-Protokolle auf Netzwerkproxyprobleme.

    • GcaHostService-Protokolle befinden sich am angegebenen Speicherort (Möglicherweise müssen Sie manuell zu diesem Pfad navigieren – kopieren Sie die Einfügevorgänge im Datei-Explorer funktioniert möglicherweise nicht):
      1. Für Windows Server 2016-Betriebssystem: C:\Users\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
      2. Für alle anderen unterstützten Windows-Betriebssystemversionen: C:\Windows\ServiceProfiles\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
    • Sortieren Sie die Protokolldateien im Ordner in umgekehrter Reihenfolge von "Änderungszeit", und öffnen Sie die letzten beiden Dateien.
    • Suchen Sie nach Fehlermeldungen mit folgendem Text: "Es konnte keine Verbindung hergestellt werden, da der Zielcomputer dies aktiv abgelehnt hat."
      1. Dies weist darauf hin, dass ein Problem mit den Netzwerkeinstellungen vorliegt, das verhindert, dass das virtuelle GcaHostService-Konto den https://gcs.office.com Endpunkt kontaktiert.
      2. Wenden Sie sich an Ihr Netzwerk-/Proxyteam, um zuzulassen, dass das virtuelle Konto (NT Service\GcaHostService) Datenverkehr an diese Domäne senden kann.
      3. Sie können überprüfen, ob das Problem behoben ist, wenn die Protokolldatei diese Fehler nicht mehr enthält.

  4. Wenn ihr Problem durch keinen der Schritte behoben wird, wenden Sie sich an den Support, indem Sie eine E-Mail an MicrosoftGraphConnectorsFeedback@service.microsoft.comsenden, und stellen Sie die beiden neuesten Protokolldateien am oben genannten Speicherort bereit.

Agent ist nicht erreichbar

Beim Einrichten der Verbindung, wenn der Agent nicht erreichbar ist, wird dieser Bildschirm angezeigt:

Screenshot: Agent nicht erreichbar

Führen Sie die folgenden Schritte aus, um die Problembehandlung zu beheben, indem Sie den in den Fehlerdetails angegebenen Service Bus-Namespace verwenden:

  1. Führen Sie in PowerShell den folgenden Befehl aus:

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

    Die Antwort sollte die Ausgabe "TcpTestSucceeded: True" enthalten:

    Screenshot von tnc 2.

    Wenn es false ist, überprüfen Sie, ob die Domäne in Ihrem Proxy/Ihrer Firewall zulässig ist und Anforderungen den Proxy durchlaufen.

  2. Wenn Sie tnc nicht ausführen können, weil ICMP-Ping in Ihrem Netzwerk blockiert ist, führen Sie den folgenden Befehl in PowerShell aus:

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

    Die Ausgabe sollte "StatusCode: 200" enthalten:

    Screenshot von wget 2.

    Wenn es false ist, überprüfen Sie, ob die Domäne in Ihrem Proxy/Ihrer Firewall zulässig ist und Anforderungen den Proxy durchlaufen.

  3. Wenn ihr Problem durch keinen der Schritte behoben wird, wenden Sie sich an den Support, indem Sie eine E-Mail an MicrosoftGraphConnectorsFeedback@service.microsoft.comsenden, und stellen Sie die beiden neuesten Protokolldateien am oben genannten Speicherort bereit.

Update wird ausgeführt

Dieser Fehler tritt auf, wenn bereits ein Update ausgeführt wird und der Fehler nach maximal 30 Minuten verschwinden sollte.

Screenshot: Laufendes Update.

Wenn der Fehler nach 30 Minuten weiterhin auftritt, führen Sie die folgenden Schritte aus:

  1. Überprüfen Sie, ob der Agent ausgeführt wird: Melden Sie sich bei dem Computer an, auf dem der Agent installiert ist, und überprüfen Sie, ob er ausgeführt wird. Wechseln Sie im Task-Manager zur Registerkarte Dienste, und überprüfen Sie, ob GcaHostService den Status "Wird ausgeführt" aufweist. Andernfalls klicken Sie mit der rechten Maustaste, und starten Sie den Dienst. Screenshot der Dienste im Task-Manager 2.

  2. Wenn das Problem weiterhin angezeigt wird, wenden Sie sich an den Support, indem Sie eine E-Mail an MicrosoftGraphConnectorsFeedback@service.microsoft.comsenden, und geben Sie die beiden neuesten Protokolldateien an. Manuelles Durchlaufen des Speicherorts für den Zugriff auf die Protokolle und Freigeben desSelben für das Team: C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

Verbindungsfehler

Wenn die Aktion "Verbindung testen" beim Erstellen einer Verbindung fehlschlägt und den Fehler "Bitte überprüfen Sie Benutzername/Kennwort und den Datenquellenpfad" anzeigt, auch wenn der angegebene Benutzername und das Kennwort korrekt sind, stellen Sie sicher, dass das Benutzerkonto über interaktive Anmelderechte für den Computer verfügt, auf dem der Connector-Agent installiert ist. Sie können die Dokumentation zur Verwaltung von Anmelderichtlinien lesen, um Anmelderechte zu überprüfen. Stellen Sie außerdem sicher, dass sich die Datenquelle und der Agent-Computer im selben Netzwerk befinden.