Ce document a été traduit automatiquement depuis l’anglais par Claude AI. Les termes du domaine WMO/météorologique doivent être vérifiés par un locuteur natif avant toute utilisation en production. Consultez le lien:../en/[document original en anglais] pour la version faisant autorité.

1. Vue d’ensemble

WIS2 Downloader expose une REST API pour gérer les abonnements et surveiller le système.

2. Authentification

Actuellement, l’API ne nécessite pas d’authentification. En production, envisagez de la placer derrière un proxy inverse avec authentification.

3. API des abonnements

3.1. Lister les abonnements

Retourne tous les abonnements actifs.

GET /subscriptions

3.1.1. Réponse

Statut Description

200

Succès — retourne la correspondance entre les topics et les détails des abonnements

503

Redis indisponible

3.1.2. Exemple

curl http://localhost:5002/subscriptions
{
  "cache/a/wis2/+/data/core/weather/surface-based-observations/#": {
    "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
    "save_path": "surface-obs",
    "filters": {
      "accepted_media_types": ["application/bufr", "application/grib"]
    }
  }
}

3.2. Créer un abonnement

Crée un nouvel abonnement à un topic WIS2.

POST /subscriptions
Content-Type: application/json

3.2.1. Corps de la requête

Champ Type Requis Description

topic

string

Oui

Modèle de topic MQTT WIS2. Prend en charge les caractères génériques + (niveau unique) et # (niveaux multiples).

target

string

Non

Sous-répertoire sous /data où les fichiers seront enregistrés.

filters

objet

Non

Configuration du filtre.

filters.accepted_media_types

tableau

Non

Liste des types MIME autorisés. Prend en charge les caractères génériques (ex. application/x-grib*).

3.2.2. Réponse

Statut Description

202

Accepté — abonnement mis en file d’attente pour traitement

400

Requête incorrecte — topic manquant ou invalide

503

Service indisponible — connexion Redis échouée

3.2.3. En-têtes de réponse

En-tête Description

Location

URL pour récupérer les détails de l’abonnement

3.2.4. Exemple

curl -X POST http://localhost:5002/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
    "target": "surface-obs",
    "filters": {
      "accepted_media_types": ["application/bufr", "application/grib"]
    }
  }'
{
  "status": "accepted",
  "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
  "target": "surface-obs"
}

3.3. Obtenir un abonnement

Retourne les détails d’un abonnement spécifique.

GET /subscriptions/{topic}

3.3.1. Paramètres de chemin

Paramètre Type Description

topic

string

Topic WIS2 (seul # nécessite l’encodage en %23)

3.3.2. Encodage URL

Seul le caractère # nécessite un encodage URL :

Caractère Encodé Raison

#

%23

Sinon interprété comme un fragment d’URL
Les barres obliques (/) et + ne nécessitent pas d’encodage dans le chemin.

3.3.3. Réponse

Statut Description

200

Succès

400

Topic invalide

404

Abonnement introuvable

503

Redis indisponible

3.3.4. Exemple

curl "http://localhost:5002/subscriptions/cache/a/wis2/+/data/core/weather/surface-based-observations/%23"
{
  "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
  "save_path": "surface-obs",
  "filters": {
    "accepted_media_types": ["application/bufr", "application/grib"]
  }
}

3.4. Supprimer un abonnement

Supprime un abonnement.

DELETE /subscriptions/{topic}

3.4.1. Paramètres de chemin

Paramètre Type Description

topic

string

Topic WIS2 encodé URL

3.4.2. Réponse

Statut Description

200

Supprimé avec succès

400

Topic invalide

503

Redis indisponible

3.4.3. Exemple

curl -X DELETE "http://localhost:5002/subscriptions/cache/a/wis2/+/data/core/weather/surface-based-observations/%23"
{
  "status": "deleted",
  "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#"
}

4. API de surveillance

4.1. Vérification de l’état de santé

Retourne l’état de santé du service.

GET /health

4.1.1. Réponse

Retourne toujours 200. Vérifiez le champ status pour connaître l’état réel.

Champ Valeurs

status

healthy ou unhealthy

4.1.2. Exemple

curl http://localhost:5002/health
{"status": "healthy"}

4.2. Métriques Prometheus

Retourne les métriques au format texte Prometheus.

GET /metrics

4.2.1. Réponse

Statut Description

200

Métriques au format texte Prometheus

500

Erreur lors de la génération des métriques

4.2.2. Métriques disponibles

Métrique Type Labels Description

wis2downloader_notifications_total

Counter

status

Total des notifications traitées

wis2downloader_downloads_total

Counter

cache, media_type

Fichiers téléchargés avec succès

wis2downloader_downloads_bytes_total

Counter

cache, media_type

Total des octets téléchargés

wis2downloader_skipped_total

Counter

reason

Notifications ignorées par raison

wis2downloader_failed_total

Counter

cache, reason

Téléchargements échoués

wis2downloader_celery_queue_length

Gauge

queue_name

Tâches actuellement dans la file d’attente Celery

4.2.3. Exemple

curl http://localhost:5002/metrics
# HELP wis2downloader_downloads_total Total number of files downloaded.
# TYPE wis2downloader_downloads_total counter
wis2downloader_downloads_total{cache="example.cache.com",media_type="application/bufr"} 42.0

# HELP wis2downloader_notifications_total Total notifications processed.
# TYPE wis2downloader_notifications_total counter
wis2downloader_notifications_total{status="success"} 42.0
wis2downloader_notifications_total{status="skipped"} 5.0

4.3. Spécification OpenAPI

Retourne la spécification OpenAPI 3.0 au format JSON.

GET /openapi

4.4. Interface Swagger

Documentation API interactive.

GET /
GET /swagger

5. Réponses d’erreur

Toutes les réponses d’erreur suivent ce format :

{
  "error": "Error message describing the problem"
}

5.1. Messages d’erreur courants

Statut Erreur Cause

400

"No topic provided"

POST /subscriptions sans champ topic

400

"No topic passed"

GET/DELETE avec topic vide

404

"Subscription for topic X not found"

Topic non abonné

503

"Failed to connect to Redis: …​"

Redis indisponible

503

"Failed to queue subscription command…​"

Redis pub/sub échoué

503

"Failed to persist subscription…​"

Écriture Redis échouée

6. Schémas de données

6.1. Abonnement

{
  "topic": "string (required) - WIS2 MQTT topic pattern",
  "save_path": "string | null - Subdirectory for downloads",
  "filters": {
    "accepted_media_types": ["array of MIME type strings"]
  }
}

6.2. Filtres

{
  "accepted_media_types": [
    "application/bufr",
    "application/grib",
    "application/x-netcdf*"
  ]
}

6.2.1. Types de médias acceptés par défaut

Lorsqu’aucun filtre n’est spécifié, ces types sont acceptés :

[
  "image/gif", "image/jpeg", "image/png", "image/tiff",
  "application/pdf", "application/postscript",
  "application/bufr", "application/grib",
  "application/x-hdf", "application/x-hdf5",
  "application/x-netcdf", "application/x-netcdf4",
  "text/plain", "text/html", "text/xml", "text/csv",
  "text/tab-separated-values"
]

7. Référence des modèles de topics

7.1. Structure des topics WIS2

{origin|cache}/a/wis2/{centre-id}/data/{data-policy}/{earth-system-domain}/{category}/...

  • origin — Données originales provenant du fournisseur de données

  • cache — Copie mise en cache depuis un Global Cache (recommandé pour la fiabilité)

  • {centre-id} — Code pays/organisation, précédé du code pays ISO2C (ex. de-dwd)

  • {data-policy} — Politique de données unifiée WMO : core ou recommended

  • {earth-system-domain} — Domaine du système terrestre issu de la politique de données unifiée WMO

7.2. Caractères génériques

Modèle Symbole Description

Niveau unique

+

Correspond exactement à un niveau

Niveaux multiples

#

Correspond à zéro ou plusieurs niveaux (doit être en fin de topic)

7.3. Exemples

Modèle Correspond à

cache/a/wis2/de-dwd/data/#

Toutes les données du Deutscher Wetterdienst

cache/a/wis2/+/data/core/weather/surface-based-observations/#

Observations de surface de tous les centres

cache/a/wis2/+/data/core/#

Toutes les données de base de n’importe quel centre

cache/a/wis2//data//weather/#

Toutes les données météorologiques (toute politique) de n’importe quel centre