Le service de Données Directes vous permet de télécharger des fichiers directement des archives du CCDA avec une adresse URL. Vous pouvez télécharger directement un fichier à partir de votre navigateur, automatiser le téléchargement de plusieurs fichiers depuis un terminal, ou encore avec un programme en python. Si le fichier est en format FITS, le service peut également récupérer uniquement des parties des fichiers, telles que les en-têtes, des découpes, ou encore des HDU uniques d'un fichier à HDU multiples.

Vous trouverez dans ce document comment accéder au service de Données Directes de plusieurs manières:

• directement depuis une adresse URL
• avec l'aide des exécutables depuis la ligne de commandes, et du client cadc-data
• en programmant avec l'aide de l'interface API du service

Pour utiliser le service, vous aurez besoin au minimum du nom de l'archive et de l'identifiant du fichier.

Adresse URL du service de Données Directes

La forme la plus simplifiée de l'adresse URL du service de Données Directes accepte le format suivant:

    https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/{ARCHIVE}/{fileID}[OPTIONS]

Exemple: https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/1722795p.fits.fz&fhead=true

Déterminer le nom de l'archive et l'identifiant du fichier

En règle générale, le service de Données Directes est destiné à être utilisé à la suite d'un autre service du CCDA, comme par exemple avec le résultat d'une requête du service de Recherche Avancée. Le résultat de la recherche contiendra l'adresse URL complète du service de Données Directes, avec le nom de l'archive et les identifiants de fichier que vous pouvez utiliser à partir de la ligne de commande.

• Si vous connaissez l'identifiant du fichier à l'avance, par exemple si vous l'avez reçu d'un observatoire, ou bien si vous le devinez après des années d'utilisation du service, vous pouvez utiliser le service directement. Les identifiants de fichier représentent ce que le fournisseur de données d'origine a utilisé au moment de l'ingestion dans l'archive au CCDA. La manière dont les identifiants de fichier sont produits va donc dépendre de l'archive.

• Les noms des archives disponibles peut être obtenue sur ce lien. Un nom d'archive représente généralement le nom d'un observatoire ou le nom d'un relevé du ciel.

• Remarque : pour les fichiers FITS, les noms de fichiers (par exemple 1722795p.fits.fz) ou les identifiants de fichiers (par exemple 1722795p) fonctionnent, mais ce n'est pas toujours le cas.

Utilisation avec Navigateur

Si vous avez juste besoin de télécharger un seul fichier à partir d'une archive du CCDA, le moyen le plus simple est d'ouvrir votre navigateur et de copier l'adresse URL dans la barre d'adresse du navigateur.

Exemple:

• En cliquant sur l'URL ci-dessous, vous lancerez le téléchargement du fichier FITS compressé de 350 Mo 7000000o.fits.fz avec l'identifiant 7000000o de l'archive CFHT:

  https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/700000o.fits.fz

Interface en ligne de commande

Le service de Données Directes peut être utilisé à partir d'un exécutable en ligne de commande. Des clients en ligne de commande comme wget, curl ou httpie peuvent être utilisés, et le CCDA fournit un client de ligne de commande légèrement plus évolué: cadc-data. Nous détaillons leur utilisation ci-dessous.

Avec wget ou curl

wget et curl sont des interfaces en ligne de commande pour accéder des services sur la toile, et sont souvent pré-installés (Mac et Linux).

• Exemple: télécharger des données depuis l'archive HLADR2:

    $ wget https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/HLADR2/hst_05476_4r_wfpc2_total_pc_drz.fits.gz
    $ curl -O -J -L https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/HLADR2/hst_05476_4r_wfpc2_total_pc_drz.fits.gz

Afin que curl se comporte comme wget, on doit spécifier:

• les options -O -J enregistreront le fichier localement (en utilisant le Content-Disposition filename spécifié par le serveur si disponible, sinon extraira un nom de fichier depuis l'adresse URL) au lieu de l'écrire en sortie standard (STDOUT).
• l'option -L assurera de rediriger l'adresse URL à une adresse temporaire du service de transfert

Si vous désirez télécharger des données propriétaires, vous aurez besoin de votre nom d'utilisateur CCDA ainsi que votre mot de passe.

Exemple:

    $ wget --user=fred --password=passwd123 https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/HLADR2/hst_05476_4r_wfpc2_total_pc_drz.fits.gz
    $ curl -u fred:passwd123 -O -J -L https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/HLADR2/hst_05476_4r_wfpc2_total_pc_drz.fits.gz

Programmation de scripts:

wget ou curl peuvent également être utilisé dans des scripts. Lors de l'exécution du script, si une erreur se produit, l'état de sortie sera différent de zéro.

Exemple:

• Recherchez les images de M101 avec le service de Recherche Avancée du CCDA, prises avec Megaprime sur le TCFH. Marquez toutes les images et cliquez sur Télécharger, en sélectionnant la liste d'adresses URLs que vous sauvegardez dans un fichier cadcUrlList.txt. Ensuite, exécutez la commande ci-dessous pour télécharger automatiquement tous les fichiers répertoriés dans la requête, accéléré avec 3 téléchargements en parallèle:

     $ cat cadcUrlList.txt | xargs -P3 wget --content-disposition

Remarque: vous pouvez également automatiser la recherche avec le module python cadctap.

Les deux lignes de commande ont de nombreuses options. Utilisez wget --help, curl --help pour les afficher. Nous énumérons ci-dessous quelques-unes des plus courantes.

Options courantes avec wget:

• --user=username --password=password : précisent le nom d'utilisateur et le mot de passe.
• -nv : exécute la commande en mode texte non affiché. La commande wget envoie beaucoup de données à STDOUT. Si vous utilisez wget dans un script, cette option est préférable.
• -q : exécute la commande en arrière-plan.
• -t, --tries=NUMBER : fixe le nombre de tentatives jusqu'à la valeur précisée par NUMBER (nous recommandons 5 tentatives).
• --waitretry=SECONDS : nombre de secondes d'attente entre deux récupérations. Par défaut, wget utilise une valeur de 10 secondes.
• -N, --timestamping : active l'horodatage et télécharge seulement les fichiers manquants ou mis à jour.
• --content-disposition : force wget à attribuer le nom approprié au fichier téléchargé.
• --certificate=file : utilise le certificat d'authentification dans le fichier.

Options courantes avec curl:

• -O : enregistre localement le fichier sous le même nom que la version distante.
• -J : utilise le nom de fichier spécifié dans le serveur comme Content-Disposition.
• -L : suit les réacheminements.
• -u : username:password précise un nom d'utilisateur et un mot de passe. Si vous précisez seulement le nom d'utilisateur, curl vous invite à saisir le mot de passe.
• -s : exécute curl en arrière-plan. Si vous ajoutez curl à un script, utilisez cette option de préférence.
• --retry N : fixe le nombre de tentatives jusqu'à la valeur précisée par N (nous recommandons 5 tentatives).
• --data-urlencode : encode des chaines de caractères non-compatibles dans l'URL, utiles pour les découpes.

Télécharger des données avec cadc-data

cadc-data permet d'accéder au service de Données Directes du CCDA. Il inclut la ligne de commande du même nom. Il est écrit en python et peut être installé avec pip:

    $ pip install cadcdata

Commande cadc-data :

La ligne de commande cadc-data peut effectuer les actions suivantes:

• récupérer un ou plusieurs fichiers depuis une archive du CCDA.
• télécharger des fichiers dans une archive.
• montrer des informations sur des fichiers spécifiques.
• découvrir automatiquement les adresses URL du service de Données Directes, et basculer vers une autre adresse URL si une erreur se produit lors du transfert d'un fichier.
• réessayer automatiquement en cas d'erreur lorsqu'un téléchargement est interrompu.
• vérifier que la somme de contrôle MD5 du fichier téléchargé correspond à la somme de contrôle MD5 stockée avec au CCDA, pour assurer l'intégrité du fichier.

Utilisation:

    $ cadc-data get {ARCHIVE} {fileID}

Exemple:

• Télécharger le fichier hst_05476_4r_wfpc2_total_pc_drz.fits.gz de l'archive CCDA de HLADR2 sur le répertoire courant:

    $ cadc-data get HLADR2 hst_05476_4r_wfpc2_total_pc_drz.fits.gz

Options courantes de cadc-data :

Vous pouvez adapter cadc-data à votre cas d'utilisation avec des options. Vous trouverez ci-dessous une liste de quelques options utiles lors du téléchargement de données.

• -u, --user=UTILISATEUR : Si les données ne sont pas publiques, cette option permet de spécifier l'UTILISATEUR CCDA pour accéder aux données propriétaires. La commande vous demandera votre mot de passe CCDA. Exemple:

L'utilisatrice Nathalie Tremblay avec le nom d'utilisateur CCDA ntremblay télécharge le fichier propriétaire hst_05476_4r_wfpc2_total_pc_drz.fits.gz :

    $ cadc-data get --user=ntremblay HLADR2 hst_05476_4r_wfpc2_total_pc_drz.fits.gz
    ntremblay@ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca
    Mot de passe: ********

Pour éviter d'être invité à saisir un mot de passe, utilisez plutôt les options --cert ou -n.

• --cert=/chemin/du/certificat : spécifie le chemin d'un certificat proxy temporaire X509 à utiliser pour l'authentification. Obtenez un certificat proxy une fois, et réutilisez-le plusieurs fois ou envoyez-le à vos collaborateurs de confiance. Exemple:

    $ cadc-get-cert -u ntremblay
    ntremblay@ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca
    Mot de passe: ********
  
    $ cadc-data get --cert ~/.ssl/cadcproxy.pem HLADR2 hst_05476_4r_wfpc2_total_pc_drz.fits.gz

• -n, --netrc-file=/chemin/du/netrc : autorise le format de fichier hérité .netrc pour l'authentification du service . Le fichier contient le nom d'utilisateur et le mot de passe du CCDA en clair, donc à utiliser avec prudence. Son emplacement par défaut est $HOME/.netrc. Exemple:

    $ cadc-data get -n CFHT 7000000o.fits.fz

• --fhead : téléchargera les informations d'en-tête FITS. Exemple:

    $ cadc-data get -v -n --fhead GEMINI 00aug02_002.fits

• -z, --decompress : décompresse les données (uniquement en gzip) sur le serveur, et en enregistre une version locale décompressée.

• -o, --output=OUTPUT : liste des fichiers de destination séparés par des espaces (guillemets requis pour plusieurs éléments).

• --cutout [CUTOUT [CUTOUT ...]] : spécifie une ou plusieurs opérations de découpe d'extension et/ou de plage de pixels à effectuer. Utilisez une syntaxe cfitsio minimale. Exemple:

    $ cadc-data get --cert ~/.ssl/cadcproxy.pem -o /tmp/700000o-cutout.fits --cutout [1] CFHT 700000o

• -q, --quiet : effectuera l'opération silencieusement

• -v, --verbose : affichera plus de dialogues et une barre de progression pour les téléchargements.

Vous pouvez trouver la liste complète des options en exécutant cadc-data get --help depuis un terminal.

Scripts avec cadc-data :

cadc-data peut également être utilisé dans les scripts. Il renvoie un état de sortie différent de zéro lorsqu'une erreur se produit lors de l'exécution.

Exemples:

• Téléchargez les fichiers I001B3H0.fits, I016B4H0.fits de l'archive IRIS

  #!/bin/bash
  archive=IRIS
  for file in I001B3H0.fits I016B4H0.fits; do
    echo "getting $archive $file"
    cadc-data get $archive $file && echo "succes" || echo "echec"
  done

• Recherchez les images de M101 avec le service de Recherche Avancée du CCDA, prises avec Megaprime sur le TCFH. Téléchargez le résultat de la requête dans un fichier de type TSV (ici le résultat est enregistré dans le fichier result_r140a9bqf8diqk82.tsv), Ensuite, exécutez la commande ci-dessous pour télécharger automatiquement tous les fichiers répertoriés dans la requête avec 3 téléchargements en parallèle:

    $ awk 'NR>1 {print $2,$4}' result_r140a9bqf8diqk82.tsv | xargs -P3 -n2 cadc-data get -v

Découpes de fichiers FITS

Si vous utilisez des fichiers FITS et vous êtes seulement intéressé par une ou plusieurs sous-parties de ces fichiers, vous pouvez limiter les téléchargements à des découpes. Un certain nombre de paramètres de découpe peuvent être inclus dans une requête au service, en utilisant un sous-ensemble de la spécification de section d'image CFITSIO. Les découpes doivent être paramétrées et encodées avec l'option cutout=<value> dans une addresse URL, ou avec l'option --cutout <value> de la commande cadc-data.

• Exemples de syntaxes de découpage:

Exemples de découpages

1. Découpage d'une seule extension

    $ cadc-data get CFHT 806045o.fits.fz --output 806045o-cutout1.fits --cutout [1]
    $ curl -L -G -o 806045o-cutout1.fits --data-urlencode "cutout=[1]" https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o.fits.fz

2. Découpage sur les coordonnées des pixels

    $ cadc-data get CFHTSG D3.IQ.R.fits --output D3.IQ.R.9979_10490_10573_11084.fits --cutout [9979:10490,10573:11084] 
    $ curl -L -G -o D3.IQ.R.9979_10490_10573_11084.fits --data-urlencode "cutout=[9979:10490,10573:11084]" https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHTSG/D3.IQ.R.fits

3. Extension et découpage sur les coordonnées des pixels

    $ cadc-data get CFHT 806045o.fits.fz --output 806045o-cutout2.fits --cutout [1][1:100,1:200]
    $ curl -L -G -o 806045o-cutout2.fits --data-urlencode "cutout=[1][1:100,1:200]" https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o.fits.fz

4. Découpage sur plusieurs extensions

    $ cadc-data get CFHT 806045o --output 806045o-cutout3.fits --cutout [1] [2]
    $ curl -L -G -o 806045o-cutout3.fits --data-urlencode "cutout=[1]&cutout=[2]" https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o.fits.fz

5. Découpage sur plusieurs extensions sur les coordonnées des pixels

    $ cadc-data get CFHT 806045o.fits.fz --output 806045o-cutout4.fits --cutout [1][10:120,20:30] [2][10:120,20:30]
    $ curl -L -G -o 806045o-cutout4.fits --data-urlencode "cutout=[1][10:120,20:30]&cutout=[2][10:120,20:30]" https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o.fits.fz

6. Il est possible de spécifier un découpage avec RA et DEC, en utilisant un service légèrement différent:

   curl -L -O -J "https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/caom2ops/sync?id=ad:CFHTSG/D2.I.fits&Circle=150.570478+2.172356+0.01"

   où les nombres sont la déclinaison RA, l'ascension droite DEC, et la taille, tous en degrés. Le signe "+" dans une adresse URL signifie " ", un espace.

Récupération de l'en-tête des fichiers FITS

Utiliser cadc-data pour télécharger un en-tête FITS

L'option --fhead de l'exécutable cadc-data permet de télécharger l'en-tête d'un fichier FITS.

Exemple:

cadc-data get --fhead IRIS I001B3H0.fits

Utiliser l'adresse du service de Données Directes pour télécharger un en-tête FITS

Une requête avec le paramètre fhead=true permet de télécharger uniquement les en-têtes des fichiers FITS.

Example: récupérer l'en-tête FITS de la première extension d'un fichier du TCFH:

curl -L -G "https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o.fits.fz&fhead=true"

Remarque: cette option ne peut pas être combinée avec les options de découpages. Une solution de contournement posssible est d'effectuer une requête de découpe d'un seul pixel, par example cutout=[1][1:1,1:1].

Utilisation avancée du service de Données Directes

PUT: Téléverser des fichiers

Pour téléverser un fichier, utilisez la commande put de cadc-data, par exemple:

    $ cadc-data put {ARCHIVE} <file to upload>

Un téléversement est effectué de manière équivalente avec une commande HTTP PUT. L'adresse URL identifie le fichier et vous devez fournir les données du fichier dans le flux d'entrée. En cas de succès, un code de réponse HTTP 201 sera renvoyé. Voici un exemple utilisant la commande curl :

• HTTP PUT: https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/newFile

    $ curl -T /path/to/newFile "https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/newFile"

INFO: Retrieving metadata information of archive files

Vous pouvez utiliser cadc-data info pour récupérer les métadonnées d'un fichier. Les informations des métadonnées sont les suivantes:

Exemple:

    $ cadc-data info IRIS I001B3H0.fit

    File I001B3H0.fit:
        archive: IRIS
       encoding: None
        lastmod: Tue, 25 Jul 2006 23:15:19 GMT
         md5sum: 2ada853a8ae135e16504aeba4e47489e
           name: I001B3H0.fits
           size: 1008000
           type: application/fits
        umd5sum: 2ada853a8ae135e16504aeba4e47489e
          usize: 1008000

Programmation avec l'API du service de Données Directes

Si vous souhaitez programmer avec l'API du service de Données Directes, nous hébergeons une documentation des fonctionnalités, résumées ci-dessous.

Points de terminaison

L'adresse URL peut être modifiée pour accéder aux différentes fonctionnalités du service. La formulation de l'adresse URL est: http://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/{endpoint} :

Techniques de transfert des données

• Téléchargement direct: Exécutez une commande "HTTP GET" à /data/pub/<archive>/<file> et obtenez un ré-acheminement vers le site sélectionné pour le téléchargement.
• Téléversement direct: Exécutez une commande "HTTP PUT" à /data/pub/<archive>/<file> et téléversez directement dans le flux.
• Téléchargement négocié: Exécutez une commande "HTTP POST" document de transfert à /data/transfer (ou /data/auth/transfer) et obtenez un document de transfert contenant plusieurs emplacements de téléchargement.
• Téléversement négocié: Exécutez une commande "HTTP POST document de transfert à /data/transfer (ou /data/auth/transfer) et obtenez un document de transfert contenant plusieurs emplacements de téléversement.

Authentication et Authorization

Si vous tentez d'accéder à un fichier non public, vous devrez vous authentifier au moyen de votre nom d'utilisateur et de votre mot de passe du CCDA ou d'un certificat client par l'entremise de SSL. Si l'authentification (connexion) échoue, vous obtenez un message HTTP 401 (Non autorisé). Si l'authentification réussit mais si vous n'avez toujours pas accès au fichier, vous obtenez un message HTTP 403 (Interdit). Si le fichier n'existe pas, vous obtenez un message HTTP 404 (Introuvable).

Vérification de la disponibilité du fichier et de son accès

Pour vérifier la présence d'un fichier et les autorisations d'accès, vous pouvez exécuter une commande HTTP HEAD avec wget ou curl sur la même adresse URL que vous utiliseriez pour télécharger le fichier. Cette commande vous permet de confirmer la présence du fichier et votre autorisation ainsi que de recueillir des métadonnées sur le fichier.

Pour afficher les en-têtes HTTP avec curl, utilisez la commande curl --location --head or curl -L -I Avec wget, utilisez wget --server-response --spider. Les en-têtes portant un préfixe en X sont des en-têtes personnalisés du CCDA; tous les autres en-têtes sont des en-têtes HTTP 1.1 standard.

Service de Données Directes et noms de fichier

Vous pouvez utiliser la disposition du contenu obtenue dans l'en-tête getData HTTP pour facilement enregistrer le fichier téléchargé sous le nom de fichier enregistré dans l'archive au moyen de wget et de son option --content-disposition. L'option --no-clobber peut s'avérer aussi utile pour éviter d'écraser les fichiers déjà téléchargés. Le programme curl n'offre aucune option équivalente à l'option --content-disposition de wget, mais vous pourriez récupérer l'en-tête HTTP du fichier, en faire l'analyse syntaxique pour obtenir la disposition du contenu et le nom du fichier, puis récupérer le fichier et l'enregistrer sous ce nom.

Pour les adresses URLs spécifiant une découpe, le nom de fichier suggéré dans l'en-tête Content-Disposition inclut une partie supplémentaire afin que différentes découpes du même fichier aient des noms de fichiers différents. Cette partie supplémentaire est destinée à être lisible, bien que de nombreux caractères soient remplacés par un trait de soulignement (_) pour être généralement plus compatible avec le standard Internet et le système de fichiers. Cette partie supplémentaire sera cohérente entre les requêtes avec les mêmes paramètres de découpe.

Aide du CCDA

Pour obtenir de l'aide ou du soutien à propos du service de Données Directes, envoyez un courriel à cadc@nrc.ca