Configuration de Passerelle de données Qlik - Accès direct sur un serveur Windows

Bonnes pratiques lors de l'utilisation de Passerelle de données Qlik - Accès direct

Pour une expérience concluante lors de l'utilisation de Passerelle de données Qlik - Accès direct, il est vivement recommandé de suivre les bonnes pratiques suivantes :

• N'utilisez pas la même Direct Access gateway pour le développement, les tests d'acceptation utilisateur et la production, car cela augmenterait le risque de surcharge des ressources disponibles et aurait un impact sur la stabilité du système. D'un point de vue commercial, la combinaison de ressources insuffisantes et d'une stabilité réduite peut entraîner des retards de mise à jour des données des applications de production.

• Pour des performances optimales, installez la Direct Access gateway sur un serveur aussi proche que possible de votre source de données.
• La Direct Access gateway doit être installée sur un Window Server dédié, comme stipulé dans la configuration système requise ci-dessous. Ne l'installez pas sur le serveur de base de données réel ou avec d'autres produits Qlik, y compris, sans s'y limiter, Qlik DataTransfer, Qlik Sense Desktop et Qlik Sense Enterprise.

Conditions préalables requises du système

Cette section décrit le logiciel, les ports et les conditions matérielles pour utiliser Passerelle de données Qlik - Accès direct sur un serveur Windows.

Installation de Passerelle de données Qlik - Accès direct

La configuration de Direct Access gateway implique des procédures à réaliser dans le centre d'activités Administration et sur le serveur Direct Access gateway.

Étape un : téléchargez Passerelle de données Qlik - Accès direct

1. Dans le centre d'activités Administration, sélectionnez Passerelles de données.

   Toutes les passerelles de données existantes seront répertoriées dans un tableau indiquant des informations de base sur chacune.

2. Cliquez sur le bouton de barre d'outils Déployer.

   La boîte de dialogue Déployer la passerelle de données s'ouvre.

3. Sélectionnez Passerelle de données - Accès direct (Windows), acceptez le Contrat client Qlik, puis cliquez sur Télécharger. Le fichier de configuration Direct Access gateway (qlik-data-gateway-direct-access.exe) sera téléchargé sur votre poste.

Étape deux : installez Direct Access gateway sur un serveur derrière le pare-feu protégeant vos sources de données

Cette étape implique l'installation de Direct Access gateway. Vous pouvez installer Direct Access gateway de manière interactive ou en mode silencieux.

Installation interactive de Direct Access gateway

1. Une fois le téléchargement terminé, copiez le fichier de configuration sur un poste Windows Server derrière le pare-feu. Assurez-vous que le poste peut communiquer avec vos sources de données.

2. Ouvrez le fichier qlik data gateway-direct-access.exe pour lancer l'assistant d'installation.

   Note Informations

   • Direct Access gateway nécessite Microsoft .NET 6.x et .NET 8.x. Si la configuration détecte qu'une version précédente est installée, vous serez invité à installer la version requise. Une fois l'installation de .NET terminée, vous devrez redémarrer le poste Direct Access gateway, puis exécuter de nouveau la configuration de Direct Access gateway.

   • Lors de la configuration, il vous sera demandé d'installer Microsoft Visual C++ 2015-2022 Redistributable (x64), si le système qu'il n'est pas installé.

   Note Informations

   • Lors de l'installation, vous pouvez éventuellement remplacer les valeurs par défaut suivantes :
     • Le chemin d'installation (C:\Program Files\Qlik\ConnectorAgent).

     • Le compte de service Windows sous lequel Direct Access gateway sera installé (LocalSystem). Le compte de service spécifié doit disposer à la fois du droit « Se connecter en tant que service » et de l'autorisation « Accès en écriture » sur le dossier d'installation Direct Access gateway.

3. Continuez en cliquant sur Suivant jusqu’à la fin de la configuration.
   

Installation, mise à niveau et désinstallation en mode silencieux de Direct Access gateway

L'installation de Direct Access gateway en mode silencieux s'avère utile si vous devez installer Direct Access gateway sur plusieurs postes au sein de votre entreprise. Si nécessaire, vous pouvez également remplacer le compte de service Windows par défaut (LocalSystem).

Conditions préalables requises

Assurez-vous d'installer les versions correctes conformément aux Conditions préalables requises des logiciels avant de démarrer l'installation en mode silencieux, car, contrairement à l'installation interactive, cela ne peut pas être effectué lors de l'installation.

Installation ou mise à niveau de Direct Access gateway

Ouvrez une invite CMD en tant qu'administrateur et exécutez la commande suivante depuis le dossier contenant l'exécutable Direct Access gateway :

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

Où full-path doit être remplacé par le chemin d'accès à l'installation réel entre guillemets, par exemple, "C:\TMP\Qlik".

Remplacement du compte de service Windows par défaut

Par défaut, Direct Access gateway est installé sous le compte de service Windows LocalSystem.

Pour installer Direct Access gateway sous un autre compte, incluez les paramètres suivants dans votre commande :

• ServiceAccount : nom du compte de service.

  Note InformationsLe compte de service spécifié doit disposer à la fois du droit « Se connecter en tant que service » et de l'autorisation « Accès en écriture » sur le dossier d'installation Direct Access gateway.
• ServicePassword : mot de passe du compte de service spécifié.

Exemple de commande avec des paramètres pour remplacer le compte de service Windows

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

Désinstallation de Direct Access gateway

Ouvrez une invite CMD en tant qu'administrateur et exécutez la commande suivante depuis le dossier contenant l'exécutable Direct Access gateway :

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

Dépannage de l'installation

Les fichiers journaux d'installation peuvent être utiles pour résoudre les problèmes liés à l'installation ou à la mise à niveau :

À partir de Direct Access gateway 1.7.7, le chemin d'accès complet aux fichiers journaux est le suivant :

<dossier d'installation de Direct Access gateway>\data\logs\Passerelle de données Qlik - Accès direct_<Horodatage>.log

Si votre version de Direct Access gateway est antérieure à la version 1.7.7, le chemin complet aux fichiers journaux est le suivant :

C:\Users\<user>\AppData\Local\Temp\Passerelle de données Qlik - Accès direct_<Timestamp>.log

Étape quatre : Enregistrer la passerelle de données

L’étape suivante consiste à enregistrer la passerelle de données. Cela peut être fait soit via le centre d’activités Administration, soit via la ligne de commande.

Option 1 : via le centre d’activités Administration

Vous pouvez enregistrer la passerelle à l’aide du centre d’activités Administration. Consultez Option 1 : via le centre d’activités Administration.

Option 2 : enregistrement automatique à l’aide de la ligne de commande

Vous pouvez également enregistrer automatiquement Direct Access gateway depuis la ligne de commande sans utiliser le centre d’activités Administration. Cette méthode utilise un jeton de session de courte durée généré à partir d’un client OAuth.

Note InformationsL’enregistrement automatique est supporté uniquement via la ligne de commande. Il n’existe actuellement pas d’API REST pour l’enregistrement automatique de la passerelle.

Conditions préalables requises

Une clé API avec l’autorisation d’administrateur de clients pour créer et gérer des clients OAuth.

Enregistrement de la passerelle avec l’enregistrement automatique

1. Générez une clé JSON Web Key (JWK) sur le poste Direct Access gateway. Cette commande crée des clés privées sur le poste Direct Access gateway :

   ConnectorAgent.exe qcs generate_jwk

2. Copiez la clé JWK renvoyée par la commande.

3. À l’aide de la clé API, créez un client OAuth pour la passerelle via l’API Tenant Admin, en fournissant la clé JWK que vous avez copiée à l’étape précédente.

   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. Copiez la valeur client_id renvoyée dans la réponse.

5. Définissez la méthode de consentement du client OAuth sur approuvé.

   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. Créez une assertion d’enregistrement sur le poste Direct Access gateway :

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

7. Demandez un jeton d’accès. Cela déclenche également la création automatique du compte d’utilisateur bot utilisé par la passerelle.

   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. Recherchez l’utilisateur bot automatiquement créé.

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

9. Copiez l’ID de my-bot-client.

10. Créez un rôle « Enregistrement DAG ».

    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. Affectez des rôles au niveau du client à l’utilisateur bot.

    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. Obtenez l’espace Direct Access gateway.

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

13. Copiez l’ID d’espace Direct Access gateway.

14. Ajoutez l’utilisateur bot à l’espace avec l’autorisation Accès en écriture.

    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. Si l’assertion existante a expiré, générez-en une nouvelle.

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

16. Enregistrez la passerelle :

    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>

Suppression d’une passerelle automatiquement enregistrée

Suivez les étapes suivantes pour annuler l’enregistrement d’une passerelle qui a été enregistrée à l’aide de la méthode automatique basée sur un jeton de session décrite ci-dessus. Ces étapes suppriment également le client OAuth, l’utilisateur bot et le rôle qui ont été créés pour la passerelle.

1. Générez une assertion, comme décrit à l’étape six de l’Enregistrement de passerelle automatique à l’aide d’un jeton de session.

2. Supprimez la passerelle :

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

3. Supprimez la clé JWK.

   ConnectorAgent.exe qcs delete_jwk

4. Recherchez le compte d’utilisateur bot créé pour la passerelle.

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

5. Copiez l’ID de bot.

6. Supprimez ce compte d’utilisateur bot.

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

7. Recherchez le rôle « Enregistrement DAG » qui a été créé pour la passerelle.

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

8. Copiez l’ID de rôle.

9. Supprimez ce rôle.

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

10. Supprimez le client OAuth.

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

Étape cinq : démarrez le service Passerelle de données Qlik - Accès direct sur le serveur Direct Access gateway

Sur le serveur de la passerelle Accès direct, effectuez l'une des opérations suivantes pour démarrer le service :

• Ouvrez la console Services Windows et démarrez le service Passerelle de données Qlik - Accès direct.

• Ouvrez une invite de commande en tant qu'administrateur et définissez le répertoire de travail sur le sous-dossier ConnectorAgent (C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent avec une installation par défaut). Ensuite, exécutez la commande suivante :

  connectoragent service start

  Une confirmation que le service a correctement démarré s'affiche.

Consultez également : Exécution du service sous un autre compte

Étape six : ajoutez une connexion à votre source de données

Consultez Étape six : ajoutez une connexion à votre source de données.

Sources de données supportées

Les connecteurs ODBC suivants sont supportés pour les installations sur le serveur Windows :

• Sources ODBC. Pour plus d'informations, consultez Bases de données ODBC ‒ Qlik Cloud (uniquement en anglais).
• Sources REST. Pour plus d'informations, consultez Sources REST ‒ Qlik Cloud (uniquement en anglais).

• Sources SAP BW, SAP SQL et SAP ODP. Requiert Direct Access gateway 1.2.0 ou une version ultérieure.

  Pour des informations sur la configuration de la connectivité à ces sources, voir SAP NetWeaver (uniquement en anglais).