Einrichten von Qlik Data Gateway – direkter Zugriff auf einem Windows-Server

Best Practices bei der Verwendung von Qlik Data Gateway – direkter Zugriff

Für eine erfolgreiche Erfahrung bei Verwendung von Qlik Data Gateway – direkter Zugriff wird dringend empfohlen, die folgenden Best Practices einzuhalten:

• Verwenden Sie nicht das gleiche Direct Access Gateway für Entwicklung, Benutzerakzeptanztests und Produktion, da dies die Gefahr einer Überlastung der verfügbaren Ressourcen erhöht und die Systemstabilität beeinträchtigen kann. Aus geschäftlicher Perspektive kann die Kombination aus ungenügenden Ressourcen und verringerter Stabilität zu verzögerten Aktualisierungen von Produktionsanwendungsdaten führen.

• Installieren Sie zum Optimieren der Leistung das Direct Access Gateway auf einem Server, der sich so nah wie möglich an der Datenquelle befindet.
• Direct Access Gateway muss auf einem dedizierten Windows Server wie in den Systemanforderungen unten aufgeführt installiert werden. Installieren Sie es nicht auf dem Datenbankserver selbst oder zusammen mit anderen Qlik Produkten, unter anderem Qlik DataTransfer, Qlik Sense Desktop und Qlik Sense Enterprise.

Systemvoraussetzungen

Dieser Abschnitt beschreibt die Software-, Port- und Hardwareanforderungen für die Verwendung von Qlik Data Gateway – direkter Zugriff auf einem Windows-Server.

Installieren von Qlik Data Gateway – direkter Zugriff

Das Setup des Direct Access Gateway umfasst Verfahren, die sowohl im Aktivitätscenter Administration als auch auf dem Server des Direct Access Gateway durchgeführt werden müssen.

Phase 1: herunterladenQlik Data Gateway – direkter Zugriff

1. Wählen Sie im Aktivitätscenter Administration Daten-Gateways aus.

   Vorhandene Daten-Gateways werden in einer Tabelle mit grundlegenden Informationen zu jedem Gateway aufgelistet.

2. Klicken Sie in der Symbolleiste auf die Schaltfläche Bereitstellen.

   Das Dialogfenster Daten-Gateway bereitstellen wird geöffnet.

3. Wählen Sie Daten-Gateway – Direkter Zugriff (Windows) aus, akzeptieren Sie die Qlik Kundenvereinbarung und klicken Sie auf Herunterladen. Die Setup-Datei für Direct Access Gateway (qlik-data-gateway-direct-access.exe) wird auf Ihren Computer heruntergeladen.

Phase 2: Das Direct Access Gateway auf einen Server hinter der Firewall, die Ihre Datenquellen schützt, herunterladen und einrichten

In dieser Phase wird das Direct Access Gateway installiert. Sie können Direct Access Gateway entweder interaktiv oder im Hintergrund installieren.

Interaktive Installation von Direct Access Gateway

1. Nachdem der Download abgeschlossen ist, kopieren Sie die Setup-Datei auf einen Windows Server-Computer hinter der Firewall. Vergewissern Sie sich, dass der Computer mit Ihren Datenquellen kommunizieren kann.

2. Öffnen Sie die Datei qlik-data-gateway-direct-access.exe, um den Einrichtungsassistenten zu starten.

   Informationshinweis

   • Für Direct Access Gateway ist Microsoft .NET 6.x und .NET 8.x erforderlich. Wenn beim Setup festgestellt wird, dass eine frühere Version installiert ist, werden Sie aufgefordert, die erforderliche Version zu installieren. Nachdem die .NET-Installation abgeschlossen ist, müssen Sie den Direct Access Gateway-Computer neu starten und dann das Setup für Direct Access Gateway erneut ausführen.

   • Das Setup-Programm fordert Sie auf, Microsoft Visual C++ 2015-2022 Redistributable (x64) zu installieren, wenn festgestellt wird, dass die Software aktuell nicht installiert ist.

   Informationshinweis

   • Während der Einrichtung können Sie optional die folgenden Standardeinstellungen überschreiben:
     • Den Installationspfad(C:\Programme\Qlik\ConnectorAgent).

     • Das Windows-Dienstkonto, unter dem Direct Access Gateway installiert werden soll (LocalSystem). Das angegebene Dienstkonto muss sowohl die Berechtigung „Als Dienst anmelden“ als auch die Berechtigung „Schreiben“ für den Installationsordner von Direct Access Gateway haben.

3. Klicken Sie so lange auf Weiter, bis die Einrichtung abgeschlossen ist.
   

Installieren im Hintergrund, Aktualisieren und Deinstallieren von Direct Access Gateway

Die Installation von Direct Access Gateway im Hintergrund ist nützlich, wenn Sie Direct Access Gateway auf mehreren Rechnern in Ihrer Organisation installieren müssen. Falls erforderlich, können Sie auch das Windows-Standarddienstkonto (LocalSystem) überschreiben.

Voraussetzungen

Installieren Sie die korrekte Version jeder erforderlichen Software, bevor Sie mit der Installation im Hintergrund beginnen, da dies anders als bei der interaktiven Installation während des Installationsvorgangs nicht möglich ist.

Installieren oder Upgraden von Direct Access Gateway

Öffnen Sie eine CMD-Befehlseingabe als Administrator und führen Sie den folgenden Befehl über den Ordner mit der Direct Access Gateway-Ausführungsdatei aus:

qlik-data-gateway-direct-access.exe /S InstallPath="full-path" AcceptEula=yes

Dabei muss full-path durch den tatsächlichen Installationspfad in Anführungszeichen ersetzt werden, beispielsweise "C:\TMP\Qlik".

Überschreiben des Windows-Standarddienstkontos

Standardmäßig wird Direct Access Gateway unter dem Windows-Dienstkonto LocalSystem installiert.

Um Direct Access Gateway unter einem anderen Konto zu installieren, fügen Sie die folgenden Parameter in Ihren Befehl ein:

• ServiceAccount: Der Name des Dienstkontobesitzers.

  InformationshinweisDas angegebene Dienstkonto muss sowohl die Berechtigung „Als Dienst anmelden“ als auch die Berechtigung „Schreiben“ für den Installationsordner von Direct Access Gateway haben.
• ServicePassword: Das Passwort für das angegebene Dienstkonto.

Beispielbefehl mit Parametern für das Überschreiben des Windows-Dienstkontos

qlik-data-gateway-direct-access.exe /S InstallPath="C:\TMP\Qlik" AcceptEula=yes ServiceAccount="qliktech.com\user" ServicePassword=kZmbkb8m8BGGz91

Deinstallieren von Direct Access Gateway

Öffnen Sie eine CMD-Befehlseingabe als Administrator und führen Sie den folgenden Befehl über den Ordner mit der Direct Access Gateway-Ausführungsdatei aus:

qlik-data-gateway-direct-access.exe /S /uninstall

Fehlerbehebung für die Installation

Die Installationsprotokolldateien können bei der Fehlersuche im Zusammenhang mit der Installation oder dem Upgrade hilfreich sein:

Ab Direct Access Gateway 1.7.7 lautet der vollständige Pfad zur Protokolldatei:

<Direct Access Gateway-Installationsordner>\data\logs\Qlik Data Gateway – direkter Zugriff_<Zeitstempel>.log

Wenn Ihre Direct Access Gateway-Version älter als 1.7.7 ist, lautet der vollständige Pfad zu den Protokolldateien:

C:\Users\<user>\AppData\Local\Temp\Qlik Data Gateway – direkter Zugriff_<Timestamp>.log

Phase vier: Datengateway registrieren

Der nächste Schritt besteht darin, das Datengateway zu registrieren. Dies kann entweder über das Administration Activity Center oder über die Befehlszeile erfolgen.

Option 1: Über das Administration Aktivitätscenter

Sie können das Gateway über das Aktivitätscenter Administration registrieren. Siehe Option 1: Über das Administration-Aktivitätscenter.

Option 2: Automatische Registrierung über die Befehlszeile

Sie können Direct Access Gateway auch automatisch über die Befehlszeile registrieren, ohne das Administration-Aktivitätscenter zu verwenden. Diese Methode verwendet ein kurzlebiges Session-Token, das von einem OAuth-Client generiert wurde.

InformationshinweisDie automatische Registrierung wird nur über die Befehlszeile unterstützt. Eine REST-API für die automatische Gateway-Registrierung ist derzeit nicht verfügbar.

Voraussetzungen

Ein API-Schlüssel mit Mandantenadministrator-Berechtigung zum Erstellen und Verwalten von OAuth-Clients.

Registrieren des Gateways mit automatischer Registrierung

1. Generieren Sie einen JSON Web Key (JWK) auf der Direct Access Gateway-Maschine. Dieser Befehl erstellt private Schlüssel auf der Direct Access Gateway-Maschine:

   ConnectorAgent.exe qcs generate_jwk

2. Kopieren Sie den vom Befehl zurückgegebenen JWK.

3. Erstellen Sie mithilfe des API-Schlüssels über die Mandanten-Admin-API einen OAuth-Client für das Gateway und geben Sie dabei den im vorherigen Schritt kopierten JWK an.

   curl "https://<tenant-url>/api/v1/oauth-clients" -X POST -H 'accept: application/json' -H 'content-type: application/json' -H 'authorization: Bearer <api-key>' -d '{"appType":"web","clientName":"<client-name>","description":"","allowedScopes":["admin.direct-access-gateways:register_gateway","admin.direct-access-gateways:delete_gateway"],"allowedAuthMethods":["private_key_jwt"],"publicKeys":[<jwk>],"allowedGrantTypes":["client_credentials"]}'

4. Kopieren Sie den in der Antwort zurückgegebenen Wert von client_id.

5. Legen Sie die Einwilligungsmethode des OAuth-Clients auf „trusted“ fest.

   curl "https://<tenant-url>/api/v1/oauth-clients/<client-id>/connection-configs/me" -X PATCH -H 'accept: application/json' -H 'content-type: application/json' -H 'authorization: Bearer <api-key>' -d '[{"op":"replace","path":"/consentMethod","value":"trusted"}]'

6. Erstellen Sie eine Registrierungs-Assertion auf dem Direct Access Gateway-Rechner:

   ConnectorAgent.exe qcs generate_registration_assertion --tenant_url <tenant-url> --client-id <client-id>

7. Fordern Sie ein Zugriffs-Token an. Dies löst auch die automatische Erstellung des vom Gateway verwendeten Bot-Benutzerkontos aus.

   curl "https://<tenant-url>/oauth/token" -X POST -H 'content-type: application/x-www-form-urlencoded' -d "grant_type=client_credentials" -d "client_id=<client-id>" -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" -d "client_assertion=<assertion>" -d "scope=admin.direct-access-gateways:register_gateway admin.direct-access-gateways:delete_gateway"

8. Suchen Sie den automatisch erstellten Bot-Benutzer.

   curl "https://<tenant-url>/api/v1/users" -H 'accept: application/json' -H 'authorization: Bearer <API-key>'

9. Kopieren Sie die ID von my-bot-client.

10. Erstellen Sie eine Rolle "DAG Registration".

    curl "https://<tenant-url>/api/v1/roles" -X POST -H 'accept: application/json' -H 'content-type: application/json' -H  'authorization: Bearer API-key' -d '{"name":"DAG Registration","description":"Role for registering a gateway","assignedScopes":["admin.direct-access-gateways:register_gateway", "admin.direct-access-gateways:delete_gateway"]}'

11. Weisen Sie dem Bot-Benutzer Rollen auf Mandantenebene zu.

    curl "https://<tenant-url>/api/v1/users/<bot-user-ID>" -X PATCH  -H 'accept: application/json' -H 'content-type: application/json' -H  'authorization: Bearer <API-key>' -d ' [ { "op": "replace", "path": "/assignedRoles", "value": [ { "name": "DAG Registration" } ] } ]'

12. Rufen Sie den Bereich des Gateways für direkten Zugriff ab.

    curl "https://<tenant-url>/api/v1/spaces" -H  'authorization: Bearer <API-key>'

13. Kopieren Sie die Direct Access Gateway-Space-ID.

14. Fügen Sie den Bot-Benutzer mit der Berechtigung Kann bearbeiten zum Space hinzu.

    curl "https://<tenant-url>/api/v1/spaces/<DAG-space-ID>/assignments" -X POST -H 'accept: application/json' -H 'content-type: application/json' -H  'authorization: Bearer <API-key>' -d '{"assigneeId": "<Bot-user-ID>","roles": ["consumer","dataconsumer","producer"], "type": "user"}'

15. Falls die vorhandene Assertion abgelaufen ist, generieren Sie eine neue.

    ConnectorAgent.exe qcs generate_registration_assertion --tenant_url <tenant-url> --client-id <client-ID>

16. Registrieren Sie das Gateway:

    ConnectorAgent.exe qcs register_gateway --tenant_url <tenant-url> --gateway_name <gateway-name> --gateway_description <gateway-description> --space_name <space-name> --client-id <client-ID> --assertion <assertion>

Entfernen eines automatisch registrierten Gateways

Führen Sie die folgenden Schritte aus, um die Registrierung eines Gateways aufzuheben, das mit der oben beschriebenen automatischen, auf Sitzungs-Token basierenden Methode registriert wurde. Diese Schritte entfernen auch den OAuth-Client, den Bot-Benutzer und die Rolle, die dafür erstellt wurden.

1. Generieren Sie eine Assertion, wie in Schritt sechs der automatischen Gateway-Registrierung unter Verwendung eines Session-Tokens beschrieben.

2. Löschen Sie das Gateway:

   ConnectorAgent.exe qcs delete_gateway --tenant_url <tenant-url> --gateway_name <gateway-name> --client-id <client-ID> --assertion <assertion>

3. Löschen Sie den JWK.

   ConnectorAgent.exe qcs delete_jwk

4. Suchen Sie nach dem Bot-Benutzerkonto, das für das Gateway erstellt wurde.

   curl "https://<tenant-url>/api/v1/users" -H 'accept: application/json' -H 'authorization: Bearer <api-key>'

5. Kopieren Sie die Bot-ID.

6. Löschen Sie dieses Bot-Benutzerkonto.

   curl -X DELETE "https://<tenant-url>/api/v1/users/<bot-user-ID>" -H "Authorization: Bearer <api-key>"

7. Suchen Sie nach der Rolle „DAG Registration“, die für das Gateway erstellt wurde.

   curl "https://<tenant-url>/api/v1/roles?limit=1&filter=(name eq \"DAG Registration\")" -H "Authorization: Bearer <api-key>"

8. Kopieren Sie die Rollen-ID.

9. Löschen Sie diese Rolle.

   curl -X DELETE "https://<tenant-url>/api/v1/roles/<role-ID>" -H "Authorization: Bearer <api-key>"

10. Löschen Sie den OAuth-Client.

    curl -X DELETE "https://<tenant-url>/api/v1/oauth-clients/<client-ID>" -H "qlik-confirm-delete: <client-ID>" -H "Authorization: Bearer <api-key>"

Phase 5: Den Qlik Data Gateway – direkter Zugriff-Dienst auf dem Server des Direct Access Gateway starten

Führen Sie auf dem Server des Gateways für direkten Zugriff einen der folgenden Schritte aus, um den Dienst zu starten:

• Öffnen Sie die Windows-Dienste-Konsole und starten Sie den Qlik Data Gateway – direkter Zugriff-Dienst.

• Öffnen Sie eine Eingabeaufforderung als Administrator und ändern Sie das Arbeitsverzeichnis in den Unterordner ConnectorAgent (C:\Programme\Qlik\ConnectorAgent\ConnectorAgent für eine Standardinstallation). Führen Sie dann den folgenden Befehl aus:

  connectoragent service start

  Es wird eine Bestätigung angezeigt, dass der Dienst erfolgreich gestartet wurde.

Siehe auch: Ausführen des Dienstes unter einem anderen Konto

Phase 6: Eine Verbindung zu Ihrer Datenquelle hinzufügen

Siehe Phase 6: Eine Verbindung zu Ihrer Datenquelle hinzufügen.

Unterstützte Datenquellen

Die folgenden ODBC-Konnektoren werden für Windows-Serverinstallationen unterstützt:

• ODBC-Quellen. Weitere Informationen finden Sie unter ODBC-Datenbanken – Qlik Cloud (nur auf Englisch).
• REST-Quellen. Weitere Informationen finden Sie unter REST-Quellen ‒ Qlik Cloud (nur auf Englisch).

• SAP BW-, SAP SQL- und SAP ODP-Quellen Erfordert Direct Access Gateway 1.2.0 oder höher.

  Weitere Informationen zum Einrichten der Konnektivität mit diesen Quellen finden Sie unter SAP NetWeaver (nur auf Englisch).