Accès directement aux données

Le service de données directes vous permet de télécharger des fichiers directement des archives du CCDA à l'aide d'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 sous 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
• en programmant avec une bibliothèque Python
• 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 du nom de fichier.

Exemple: CFHT/1722795p.fits.fz

La forme la plus simplifiée de l'adresse URL du service de données directes suit le format suivant:

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

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

élément	Valeur	Description
{ARCHIVE}	CFHT	Nom de l'archive requise
{FICHIER}	1722795p.fits.fz	Nom du fichier dans l'archive
[OPTIONS]	meta=true	Options sur le fichier, dans ce cas l'en-tête du fichier FITS

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 et pourra être sauvegardé. Si vous n'utilisez pas le service de recherche avancée, vous pouvez toujours formuler l'adresse URL en connaissant l'archive et le nom du fichier.

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 310 Mo 1722795p.fits.fz de l'archive CFHT:

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

Interface en ligne de commande

Une requête au service de données directes peut être utilisé à partir d'un exécutable en ligne de commande. Un client exécutable de ligne de commande tel que wget, curl ou httpie peut être utilisé, et le CCDA fournit un client de ligne de commande légèrement plus évolué: cadcget, cadcput, cadcinfo. Nous détaillons son 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 IRIS:

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

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

• les options -O -J forcent l'enregistrement du fichier localement (en utilisant le Content-Disposition filename spécifié par le serveur si disponible, et sinon avec un nom de fichier extrait depuis l'adresse URL) au lieu de la sortie standard (STDOUT)
• l'option -L assurera la redirection de l'adresse URL vers une adresse temporaire du service de transfert si nécessaire.

Si vous désirez télécharger des données non publiques, vous aurez besoin de votre certificat CCDA X509 (l'authentification par utilisateur/mot de passe pourrait être activée dans une future version du service).

Exemple:

$ wget --certificate mycert.pem --ca-certificate mycert.pem https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/IRIS/I429B4H0.fits
$ curl -E mycert.pem -O -J -L https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/IRIS/I429B4H0.fits

Pour télécharger un certificat d'utilisateur du CCDA, à partir d'un navigateur, connectez-vous au CCDA: https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/fr/connexion.html. Ensuite, cliquez sur votre nom dans le coin supérieur droit et suivez le lien "Obtenir un certificat", qui va automatiquement télécharger un nouveau certificat, valide pour 30 jours.

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:

• -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.
• --ca-certificate FILE : utilise un ensemble de certificats

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.
• -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.

Utilisation des Clients CCDA: cadc[get|put|info|remove]

cadcdata est un logiciel pour accéder au service de données directes du CCDA. Il installe 4 applications en ligne de commande utilisées pour manipuler les données au CCDA:

• cadcget  : récupère les fichiers du service de données CCDA
• cadcinfo : obtient des informations sur les fichiers
• cadcput  : téléverse des fichiers nouveaux ou mis à jour dans le service de données CCDA
• cadcremove : supprime des fichiers du service de données CCDA

Il est écrit en Python et peut être installé avec :

$ pip install [--upgrade] cadcdata

Il est recommandé de réinstaller régulièrement la dernière version du logiciel en utilisant l'option pip install --upgrade.

Commande cadcget :

La commande cadcget est conçue pour être robuste et performante en tirant parti de l'architecture du système de stockage du CCDA.

Utilisation:

$ cadcget {fileID}

Où {fileID} est l'identifiant d'un fichier. La forme complète de l'identifiant est {scheme}:{archive}/{chemin}/{fichier} où :

• scheme : (facultatif) représente un schéma attribué par le fournisseur de données cadc, mast, gemini etc.
• archive : nom de l'archive
• chemin : les observatoires peuvent choisir d'utiliser un chemin de fichier dans l'identifiant. C'est très peu fréquent.
• fichier : nom complet du fichier

En pratique, {archive}/{filename} est suffisant pour accéder à un fichier dans la majorité des cas.

Exemple:

• Téléchargez le fichier I429B4H0.fits depuis l'archive publique IRIS dans le répertoire courant:

$ cadcget IRIS/I429B4H0.fits

Cependant, la forme plus complète fonctionnera également :

$ cadcget cadc:IRIS/I429B4H0.fits

Scripts avec cadcget :

cadcget 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 "téléchargement de $archive/$file"
    cadcget $archive/$file && echo "succès" || echo "échec"
  done
  

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=VALEUR, comme spécifié dans l'API du service.

• Exemples de syntaxes de découpage pour la VALEUR:

Valeur	Description
[1:512:2,2:512:2]	Ouvre une image de 256x256 pixels composée d'un nombre impair de colonnes (1er axe) et d'un nombre pair de lignes (2e axe) de l'image stockée dans le tableau principal du fichier.
[*,512:256]	Ouvre une image composée de toutes les colonnes de l'image source, mais seulement des lignes 256 à 512. L'image subit une rotation le long du 2e axe, étant donné que le pixel de départ est supérieur au pixel de fin.
[*:2,512:256:2]	Idem, mais conserve seulement une ligne et une colonne sur deux de l'image source.
[-*,*]	Copie toute l'image, et lui fait subir une rotation sur le premier axe.
[3][1:256,1:256]	Ouvre une sous-section de l'image qui se trouve dans la 3e extension du fichier.

Exemples de découpages

1. Découpage d'une seule extension

    $ cadcget "CFHT/806045o.fits.fz?cutout=[1]" --output 806045o-cutout1.fits
    $ 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

    $ cadcget "CFHTSG/D3.IQ.R.fits?cutout=[9979:10490,10573:11084]" --output D3.IQ.R.9979_10490_10573_11084.fits
    $ 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

    $ cadcget "CFHT/806045o.fits.fz?cutout=[1][1:100,1:200]" --output 806045o-cutout2.fits
    $ 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

    $ cadcget "CFHT/806045o.fits.fz?cutout=[1]&cutout=[2]" --output 806045o-cutout3.fits
    $ curl -L -G -o 806045o-cutout3.fits --data-urlencode "cutout=[1]" --data-urlencode "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

    $ cadcget "CFHT/806045o.fits.fz?cutout=[1][10:120,20:30]&cutout=[2][10:120,20:30]" --output 806045o-cutout4.fits
    $ curl -L -G -o 806045o-cutout4.fits --data-urlencode "cutout=[1][10:120,20:30]" --data-urlencode "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://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/caom2ops/sync?id=cadc: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.

Options cadcget couramment utilisées :

Vous pouvez adapter cadcget à 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 du CCDA pour accéder aux données protégées. 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 « I429B4H0.fits » :

    $ cadcget --user=ntremblay IRIS/I429B4H0.fits
    johnsmith@ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca
    Mot de passe: ********

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

• -c, --cert=/chemin/du/certificat : spécifiez le chemin d'un certificat 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.canfar.net
    Mot de passe: ********
  
    $ cadcget --cert ~/.ssl/cadcproxy.pem IRIS/I429B4H0.fits

• -n, --netrc-file=/chemin/du/netrc : autorise le format de fichier .netrc pour l'authentification d'un service Web. 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:

    $ cadcget -n CFHT/700000o.fits.fz

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

    $ cadcget -v -n --fhead GEMINI/mrgN20091214S0271_add.fits

• -o, --output FICHIER : écrire dans un nom de fichier différent ou télécharger dans un autre répertoire

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

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

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

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

Utiliser cadcget 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:

cadcget --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 meta=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&meta=true"

Remarque: l'option meta=true ne peut pas être combinée avec les options de découpages cutout=.... Une solution alternative 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

Jusqu'à présent, uniquement la fonctionalité de lecture a été décrite. Pour téléverser un fichier, utilisez la commande cadcput, par exemple:

$ cadcput {fileID} src

Notez que cadcput nécessite l'adresse URI complet, y compris la source, par exemple: cadc:CFHT/2583975o.fits.fz. Un téléchargement est effectué en effectuant un HTTP PUT vers l'adresse URL identifiant le fichier et en fournissant les données du fichier dans le flux d'entrée accompagnant la demande.

INFO: Obtenir des informations sur les fichiers

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

Metadonnée	Description
id:	L'identification complète dans le système de stockage du CCDA
encoding:	Le type de codage (compression) utilisé (facultatif)
last modified:	Date de la dernière modification du fichier (facultatif: non-présent lors de la livraison en modification)
md5sum:	Le résumé de somme MD5 du contenu du fichier.
name:	Contient un nom de fichier suggéré pour les clients qui écriront le fichier
size:	Taille du fichier
type:	Le type MIME du fichier (facultatif: présent uniquement si le type est connu)

Exemple:

$ cadcinfo IRIS/I001B3H0.fits

CADC Storage Inventory artifact IRIS/I001B3H0.fits:
                  id: cadc:IRIS/I001B3H0.fits
                name: I001B3H0.fits
                size: 1008000
                type: application/fits
            encoding: None
       last modified: 2006-07-25T16:15:19.000
              md5sum: 2ada853a8ae135e16504aeba4e47489e

Programmation avec la bibliothèque Python

Le logiciel cadcdata installe une bibliothèque Python qui peut être utilisée directement dans un script. La documentation sur la façon d'accéder à la bibliothèque est disponible avec la commande pydoc cadcdata et peut être résumée par les 2 méthodes suivantes:

1. Instanciez la classe StorageInventoryClient et utilisez-la pour accéder aux données.

   Exemple:

   
   from cadcdata import StorageInventoryClient
   client = StorageInventoryClient()
   print(client.cadcinfo('GEMINI/N20220622S0260.fits'))
       

   
   id=gemini:GEMINI/N20220622S0260.fits, name=N20220622S0260.fits, size=7254720, type=application/fits, encoding=binary, last modified=2022-06-23T17:24:09.000, md5sum=6831f29dfc324e0cfc30f1bc5
       

2. Appelez les fonctions de point d'entrée cadc*. Ce sont les fonctions correspondant aux applications en ligne de commande (cadcget_cli, cadcinfo_cli, etc.).

   Exemple:

    
from cadcdata import cadcinfo_cli
import sys
sys.argv = ['cadcinfo', 'GEMINI/00AUG02_002.fits']
cadcinfo_cli()
    

CADC Storage Inventory identifier GEMINI/N20220622S0260.fits:
                  id: gemini:GEMINI/N20220622S0260.fits
                name: N20220622S0260.fits
                size: 7254720
                type: application/fits
            encoding: binary
       last modified: 2022-06-23T17:24:09.000
              md5sum: 6831f29dfc324e0cfc30f1bc5b86e7e4

Toutes les opérations en lignes de commandes présentées dans ce document peuvent être effectuées à l'aide de l'une des méthodes répertoriées ci-dessus. Les avantages et les inconvénients de ces méthodes sont mentionnés dans l'aide en ligne de la bibliothèque.

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.

Techniques de transfert des données

• Téléchargement direct: Exécutez une commande "HTTP GET" à /data/pub/<archive>/<fichier> et obtenez un ré-acheminement vers le site sélectionné pour le téléchargement.
• Téléchargement ou téléversement négocié: Exécutez une commande "HTTP POST" document de transfert à https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/raven/locate et obtenez un document de transfert contenant plusieurs sites de téléchargement.

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. Les outils de ligne de commande cadcdata acceptent le nom d'utilisateur et le mot de passe CCDA ou les certificats client tandis que l'accès direct au service fonctionne avec les certificats client, les cookies ou les certificats porteurs. Ces méthodes d'autorization pourraient être mises à jour à l'avenir.

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.

En-tête HTTP	Explication
Content-Type	Type MIME du fichier (optionnel; seulement si le type est connu)
Content-Encoding	Type de codage (en général, une compression) utilisé (optionnel)
Content-Disposition	Nom de fichier suggéré pour les clients qui enregistrent le fichier
Content-Length	Taille du fichier téléchargé
Content-MD5	Condensé MD5 du contenu du fichier
Last-Modified	Date de la dernière modification du fichier (optionnel; absent lors d'une modification durant la livraison)
X-Uncompressed-Length	Taille du fichier non compressé en octets (optionnel; absent lors d'une modification durant la livraison)
X-Uncompressed-MD5	Condensé MD5 du contenu du fichier non compressé (optionnel; absent lors d'une modification durant la livraison)
X-CADC-Stream	Nom du flux utilisé lors de l'exécution d'une commande PUT (optionnel; le flux par défaut est utilisé en l'absence de précision)

Service de données directes et noms de fichier

Vous pouvez utiliser la disposition du contenu obtenue dans l'en-tête data 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 à support@canfar.net