Téléchargement avec WIS2 Downloader

Objectifs d'apprentissage !

À la fin de cette session pratique, vous serez capable de :

trouver et vous abonner à des ensembles de données
utiliser des filtres pour contrôler les fichiers téléchargés
utiliser l'authentification pour télécharger des ensembles de données protégés par un contrôle d'accès
modifier la configuration par défaut de WIS2 Downloader pour des cas d'utilisation avancés

Introduction

Dans WIS2, tous les ensembles de données disposent d'un fichier de métadonnées qui peut être trouvé dans les Global Discovery Catalogues. Ainsi, il est prévu que les utilisateurs consultent toujours ces services pour trouver les données partagées sur WIS2.

WIS2 Downloader utilise ce principe en recherchant tous les enregistrements disponibles dans ces GDCs et en les combinant en interne pour permettre à l'utilisateur de naviguer dans les données disponibles sur WIS2. Étant donné le grand nombre d'enregistrements à afficher, il est essentiel de fournir un moyen permettant à l'utilisateur de les filtrer et de trouver l'enregistrement correct. Même après avoir trouvé et s'être abonné à l'enregistrement correct, il peut y avoir des ensembles de données où le nombre de fichiers dépasse les besoins actuels de l'utilisateur. Pour cette raison, un deuxième niveau de filtrage est nécessaire — celui qui opère au moment de décider si un fichier doit être téléchargé.

Utilisation dans la vue Catalogue

La vue Catalogue est l'une des deux façons de trouver et de s'abonner à des ensembles de données dans WIS2 Downloader. Elle regroupe les enregistrements des Global Discovery Catalogues et les présente dans une interface consultable et filtrable — similaire à la navigation directe dans un portail GDC.

Naviguez vers la vue Catalogue dans la barre latérale gauche.

WIS2 Downloader Catalogue View

En haut de la page, vous trouverez une barre de recherche et un ensemble de filtres. Vous pouvez les utiliser pour réduire la liste des enregistrements disponibles par mot-clé, Centre ID ou politique de données (core vs. recommended).

Vous pouvez également filtrer spatialement en définissant une bounding box à l'aide de quatre entrées de coordonnées — Nord, Ouest, Sud et Est — exprimées en valeurs décimales de latitude et de longitude. Lorsqu'une bounding box est définie, vous pouvez choisir entre deux modes de correspondance :

Intersects — retourne les enregistrements dont l'étendue spatiale chevauche la bounding box de quelque manière que ce soit.
Within — retourne uniquement les enregistrements dont l'étendue spatiale se trouve entièrement à l'intérieur de la bounding box.

Recharger le catalogue

Le catalogue est chargé à partir des GDCs lorsque WIS2 Downloader démarre. Si vous pensez que la liste est obsolète, vous pouvez forcer un rechargement depuis la section Paramètres dans la barre latérale gauche.

Exercice : trouver et s'abonner à un ensemble de données

Trouver un ensemble de données d'observation de surface

Utilisez les filtres dans la vue Catalogue pour trouver un ensemble de données core d'observation de surface lié à la température et aux précipitations.

Tapez surface dans la barre de recherche et observez comment la liste des enregistrements est filtrée.
Définissez le filtre de politique de données sur core.
Définissez les mots-clés pour inclure temperature, precipitation et observez comment les résultats changent.
Sélectionnez un enregistrement parmi les résultats pour développer ses détails.
Examinez les métadonnées affichées — notez le sujet, le centre d'origine et la politique de données.
Définissez le dossier de destination sur surface-obs.
Cliquez sur Subscribe pour créer l'abonnement.

Après vous être abonné, naviguez vers Manage Subscriptions pour confirmer que le nouvel abonnement apparaît dans la liste.

Cliquez pour révéler la réponse

Tout enregistrement dont le sujet contient surface-based-observations et dont la politique de données est core est un choix valide. L'application du filtre de mots-clés pour temperature, precipitation réduira davantage les résultats aux ensembles de données pertinents pour ces variables.

Une fois abonné, la vue Manage Subscriptions affichera l'abonnement actif avec son sujet et son dossier cible. Les fichiers commenceront à se télécharger au fur et à mesure que de nouvelles notifications arrivent sur le broker.

Se désabonner et supprimer les fichiers téléchargés

Accédez à la vue Manage Subscriptions et cliquez sur Unsubscribe pour le sujet sélectionné dans l'exercice précédent.

Ensuite, nettoyez le dossier de téléchargements :

rm -fr /home/<username>/wis2-downloads/surface-obs

Utilisation de la vue Arborescence

La vue Arborescence présente la hiérarchie des sujets WIS2 sous forme d'arborescence repliable, permettant de parcourir les sujets disponibles niveau par niveau — similaire à la navigation des sujets dans MQTT Explorer. Elle est conçue pour une exploration de haut niveau, de manière descendante, des données disponibles sur WIS2, en commençant par la racine de la hiérarchie et en approfondissant. Cela contraste avec la vue Catalogue, qui vous mène directement aux enregistrements individuels des ensembles de données et convient mieux lorsque vous savez déjà ce que vous recherchez.

Naviguez vers la vue Arborescence dans la barre latérale gauche.

WIS2 Downloader Tree View

L'arborescence est organisée selon la hiérarchie des sujets WIS2. Développez chaque niveau en cliquant sur un nœud pour révéler ses enfants. À n'importe quel niveau, vous pouvez vous abonner en sélectionnant un nœud et en cliquant sur Subscribe — en utilisant un caractère générique (#) pour capturer tous les sujets sous ce nœud.

S'abonner à différents niveaux

S'abonner plus haut dans l'arborescence (par exemple au niveau du Centre ID) capturera tous les ensembles de données publiés par ce centre. S'abonner plus bas offre un contrôle plus granulaire. Utilisez le suffixe # ajouté automatiquement par WIS2 Downloader lors de l'abonnement depuis la vue Arborescence.

Exercice : trouver et s'abonner via la vue Arborescence

S'abonner à un ensemble de données via la vue Arborescence

Utilisez la vue Arborescence pour trouver et vous abonner aux données d'observation de surface provenant d'un centre spécifique.

Développez l'arborescence en partant du nœud cache, puis naviguez à travers a → wis2.
Sélectionnez un Centre ID de votre choix et continuez à développer jusqu'à atteindre un sujet lié à surface-based-observations.
Examinez le chemin complet du sujet affiché — confirmez qu'il correspond à l'ensemble de données souhaité.
Définissez le dossier de destination sur surface-obs-tree.
Cliquez sur Subscribe pour créer l'abonnement.

Naviguez vers Manage Subscriptions pour confirmer que l'abonnement est actif.

Cliquez pour révéler la réponse

Tout chemin de sujet suivant le modèle cache/a/wis2/<centre-id>/data/core/weather/surface-based-observations/# est un choix valide. Le segment Centre ID variera en fonction du centre que vous avez sélectionné dans l'arborescence.

La vue Manage Subscriptions affichera le nouvel abonnement aux côtés de ceux créés précédemment.

Se désabonner et supprimer les fichiers téléchargés

Accédez à la vue Manage Subscriptions et cliquez sur Unsubscribe pour le sujet sélectionné dans l'exercice précédent.

Ensuite, nettoyez le dossier de téléchargements :

rm -fr /home/<username>/wis2-downloads/surface-obs-tree

Utilisation de la vue Abonnement manuel

La vue Abonnement manuel vous permet de créer un abonnement en saisissant directement un sujet, sans dépendre des Global Discovery Catalogues. Contrairement aux vues Catalogue et Arborescence — qui tirent leurs sujets des GDCs — l'abonnement manuel est utile lorsque vous connaissez déjà le sujet exact auquel vous souhaitez vous abonner et que vous souhaitez le configurer sans parcourir le catalogue, avec plus de liberté sur le WTH à utiliser.

Naviguez vers la vue Abonnement manuel dans la barre latérale gauche.

WIS2 Downloader Manual Subscribe

Le formulaire vous permet de spécifier :

Sujet — le sujet MQTT complet auquel s'abonner, y compris les caractères génériques (par exemple # & +).
Dossier de destination — le sous-répertoire local où les fichiers téléchargés seront enregistrés.
Filtre — un objet de filtre optionnel sous forme de texte pour contrôler les notifications téléchargées.
File d'attente prioritaire — contrôle la priorité de téléchargement attribuée aux notifications de cet abonnement.
Authentification — les identifiants requis pour les ensembles de données protégés par un contrôle d'accès.

Quand utiliser l'abonnement manuel

Utilisez l'abonnement manuel lorsque vous connaissez déjà le sujet exact souhaité et que vous souhaitez le configurer rapidement sans parcourir le catalogue, lorsque le sujet n'est pas inclus dans le catalogue, ou lorsque vous devez fournir des identifiants pour un ensemble de données protégé par un contrôle d'accès.

Téléchargement à partir d'un ensemble de données protégé par un contrôle d'accès

Certains ensembles de données sur WIS2 sont protégés par un contrôle d'accès, ce qui signifie qu'ils nécessitent des identifiants valides avant que les fichiers puissent être téléchargés. WIS2 Downloader prend en charge deux méthodes d'authentification dans la vue Abonnement manuel :

Authentification HTTP basique — fournissez un nom d'utilisateur et un mot de passe associés à vos identifiants d'accès.
Token Bearer — fournissez un token émis par le fournisseur de données à la place d'un nom d'utilisateur et d'un mot de passe.

Ces identifiants sont enregistrés par abonnement et appliqués automatiquement lors du téléchargement des fichiers pour ce sujet.

Exercice : s'abonner à un ensemble de données protégé par un contrôle d'accès sur votre wis2box

Dans cet exercice, vous configurerez un ensemble de données protégé par un contrôle d'accès sur votre instance wis2box, configurerez WIS2 Downloader pour s'abonner à son broker, et vérifierez que les fichiers sont téléchargés correctement lorsqu'un token Bearer est fourni.

Configurer et s'abonner à un ensemble de données protégé par un contrôle d'accès

Étape 1 — Créer un ensemble de données protégé par un contrôle d'accès sur wis2box

Sur votre instance wis2box, créez un ensemble de données avec le contrôle d'accès activé et notez le sujet et le token Bearer généré pour celui-ci. Si vous ne l'avez pas encore fait, consultez la session pratique Datasets with access control pour les étapes complètes de configuration.

Étape 2 — Configurer WIS2 Downloader pour écouter le broker de wis2box

Par défaut, WIS2 Downloader écoute le Global Broker. Pour recevoir des notifications directement depuis votre instance de wis2box, vous devez ajouter un abonné dans le fichier compose de WIS2 Downloader qui pointe vers le broker MQTT interne de wis2box.

Ouvrez le fichier docker-compose.yml dans le répertoire de WIS2 Downloader et ajoutez la configuration suivante pour l'abonné, en remplaçant WIS2BOX_URL par l'URL de votre instance de wis2box :

  subscriber-test:
container_name: subscriber-test
restart: always
build:
  context: .
  dockerfile: ./containers/subscriber/Dockerfile
  args:
    WIS2DOWNLOADER_UID: ${WIS2DOWNLOADER_UID:-10001}
    WIS2DOWNLOADER_GID: ${WIS2DOWNLOADER_GID:-988}
env_file: *default-env
environment:
  GLOBAL_BROKER_HOST: WIS2BOX_URL
  GLOBAL_BROKER_PORT: 443
  GLOBAL_BROKER_USERNAME: everyone
  GLOBAL_BROKER_PASSWORD: everyone
  MQTT_PROTOCOL: websockets
depends_on:
  - redis
networks:
  - redis-net
logging: *loki-logging
healthcheck:
  test: ["CMD", "pgrep", "-f", "subscriber_start"]
  interval: 30s
  timeout: 5s
  retries: 3

Redémarrez la stack pour appliquer les modifications :

docker compose down
docker compose up -d

Étape 3 — S'abonner au dataset dans WIS2 Downloader

Accédez à Manual Subscribe dans l'interface utilisateur de WIS2 Downloader.
Configurez le topic avec celui défini pour votre dataset à accès contrôlé sur wis2box.
Définissez le dossier de destination sur restricted-data.
Entrez le bearer token généré à l'étape 1 dans le champ Authentication.
Cliquez sur Subscribe pour créer l'abonnement.

Étape 4 — Pousser des données vers le dataset sur wis2box

Sur votre instance de wis2box, publiez un fichier dans le dataset à accès contrôlé. Consultez la session pratique Ingesting data for publication pour les étapes d'ingestion des données.

Étape 5 — Vérifier le téléchargement

Vérifiez que le fichier a été téléchargé par WIS2 Downloader :

ls /home/<username>/wis2-downloads/restricted-data

Cliquez pour révéler la réponse

Avec un bearer token valide, WIS2 Downloader s'authentifiera lors du téléchargement des fichiers pour le topic restreint. Le fichier publié à l'étape 4 devrait apparaître dans le dossier restricted-data peu après son ingestion par wis2box.

Si l'authentification échoue, les fichiers ne seront pas téléchargés, même si l'abonnement semble actif dans la vue Manage Subscriptions. Vérifiez que le bearer token correspond à celui configuré sur le dataset dans wis2box.

Se désabonner et supprimer les fichiers téléchargés

Accédez à la vue Manage Subscriptions et cliquez sur Unsubscribe pour le topic, puis nettoyez le dossier des téléchargements :

rm -fr /home/<username>/wis2-downloads/restricted-data

Filtrage des téléchargements

Les filtres permettent de contrôler quels fichiers sont téléchargés à partir d'un abonnement au niveau des notifications — c'est le deuxième niveau de filtrage mentionné dans l'introduction. Plutôt que de télécharger tous les fichiers publiés sur un topic, vous pouvez définir un filtre pour que seules les notifications correspondant à des critères spécifiques déclenchent un téléchargement.

Après avoir sélectionné un dataset dans la Catalogue View ou la Tree View, un panneau de filtre apparaît sur le côté droit de l'écran avant de s'abonner. Ici, vous pouvez remplir les valeurs de filtre que vous souhaitez appliquer. WIS2 Downloader génère automatiquement l'objet filtre à partir de vos entrées.

Dans la vue Manual Subscribe, vous pouvez entrer cet objet filtre manuellement en remplissant le champ Filter (JSON) dans le formulaire.

Entrées de filtre disponibles

Type de média — restreindre les téléchargements à des types de contenu spécifiques (par exemple, application/bufr).
Dataset — restreindre les téléchargements à un dataset spécifique via son identifiant de métadonnées.
Bounding box — restreindre les téléchargements aux notifications dont les données se situent dans une zone spatiale définie par les valeurs north, south, east et west.
Plage de date et heure — restreindre les téléchargements aux notifications publiées dans une plage de temps spécifique.
Filtres personnalisés — filtrer sur toute autre propriété de notification définie dans l'enregistrement de métadonnées en spécifiant la valeur de la propriété (par exemple, filtrer par wigos_station_identifier pour ne télécharger que les données d'une station spécifique).

Voici un exemple d'objet filtre généré à partir de ces entrées :

{
  "rules": [
    {
      "id": "accept",
      "order": 1,
      "match": {
        "all": [
          {
            "any": [
              { "media_type": { "exists": false } },
              { "media_type": { "in": ["application/bufr", "application/x-bufr"] } }
            ]
          },
          { "metadata_id": { "in": ["urn:wmo:md:ir-irimo:core.surface-based-observations.temp"] } },
          { "bbox": { "north": 23.0, "south": 27.0, "east": 25.0, "west": 28.0 } },
          {
            "property": "pubtime",
            "type": "datetime",
            "between": ["2026-06-08T20:00:00+00:00", "2026-06-09T05:00:59+00:00"]
          },
          {
            "property": "wigos_station_identifier",
            "type": "string",
            "in": ["0-20000-0-78338"]
          }
        ]
      },
      "action": "accept"
    },
    {
      "id": "default",
      "order": 999,
      "match": { "always": true },
      "action": "reject",
      "reason": "No filter criteria matched"
    }
  ]
}

Exercice : S'abonner avec un filtre

Utilisez la vue Catalogue pour trouver un dataset d'observations de surface et appliquez un filtre spatial avant de vous abonner.

Accédez à Catalogue View et recherchez un dataset d'observations de surface de votre choix.
Sélectionnez le dataset pour afficher ses détails dans le panneau de droite.
Dans les entrées de filtre, définissez une bounding box pour une région de votre choix.
Optionnellement, définissez un filtre Type de média pour restreindre les téléchargements aux fichiers BUFR.
Définissez le dossier de destination sur filtered-obs.
Cliquez sur Subscribe pour créer l'abonnement.

Attendez l'arrivée des fichiers et vérifiez que seuls les fichiers correspondant à vos critères de filtre sont téléchargés.

Cliquez pour révéler la réponse

Seules les notifications correspondant à toutes les conditions que vous avez définies seront acceptées et téléchargées. Toutes les autres seront rejetées par la règle par défaut.

Se désabonner et supprimer les fichiers téléchargés

Accédez à la vue Manage Subscriptions et cliquez sur Unsubscribe pour le topic, puis nettoyez le dossier des téléchargements :

rm -fr /home/<username>/wis2-downloads/filtered-obs

Conclusion

Félicitations !

Lors de cette session pratique, vous avez appris à :

rechercher et vous abonner à des datasets en utilisant les vues Catalogue et Tree View
vous abonner directement à des topics en utilisant la vue Manual Subscribe
appliquer des filtres pour contrôler quels fichiers sont téléchargés à partir d'un abonnement
utiliser l'authentification pour télécharger des datasets à accès contrôlé