Service d'accès direct aux données

Le service d'accès direct aux données permet de télécharger des fichiers directement des archives du CCDA. Si le nom du fichier et de l'archive sont connues, l'executable de ligne de commande avec le module python cadc-data permet de télécharger le fichier. Une adresse URL permet aussi de télécharger un fichier, grâce par exemple aux commandes wget ou curl. Ceci permet d'intégrer les téléchargments automatiques dans des scripts.

Utilisation simple

Téléchargements avec le client cadc-data

Le client cadc-data est une application Python pour accéder le service d'accès direct aux données du CCDA.

cadc-data permet de:

• récupérer un ou plusieurs fichiers à la fois à partir d'une archive
• téléverser des fichiers
• découvrir les informations à propos de fichiers
• découvrir automatiquement l'adresse URL du service d'accès direct aux données et fail-over sur une autre adresse URL si une erreur se produit pendant le transfer
• recommencer automatiquer si une erreur transiente s'est produite
• vérifier le condensé MD5 d'un fichier téléchargé correspond bien au condensé MD5 sur les serveurs du CCDA pour assurer l'intégrité du fichier

Voici un exemple simple avec cadc-data:

cadc-data get HLADR2 hst_05476_4r_wfpc2_total_pc_drz.fits.gz

qui va télécharger le fichier hst_05476_4r_wfpc2_total_pc_drz.fits.gz de l'archive HLADR2 dans le répertoire courant. Si le fichier est comprimé avec gzip, en utilisant l'option -z décomprimera automatiquement le fichier.

Pour sauvegarder le fichier sous un nom de fichier différent, on peut utiliser l'option -o <noveau_nom>.

Si les données que vous voulez télécharger ne sont pas publiques, vous pouvez utilisez votre nom d'utilisateur de votre mot de passe du CCDA, en passant votre nom d'utilisateur avec l'option --user.

cadc-data get --user USERNAME HLADR2 hst_05476_4r_wfpc2_total_pc_drz.fits.gz

Vous devez saisir votre mot de passe, ou vous pouvez aussi utiliser l'option --netrc-file, qui vous permet d'utiliser un fichier .netrc contenant le nom d'utilisateur et de mot de passe du CCDA:

cadc-data get --netrc-file NETRC_FILE HLADR2 hst_05476_4r_wfpc2_total_pc_drz.fits.gz

Si vous possédez un certificate x509 pour vous authentifier, vous pouvez utiliser l'option --cert qui permet de spécifier le fichier contenant le certificat.

cadc-data get --cert CERT_FILE HLADR2hst_05476_4r_wfpc2_total_pc_drz.fits.gz

cadc-data peut aussi être utilisé dans des scripts. En cas d'erreur, il retourne une valeur non nulle. Par exemple:

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

Options courantes avec cadc-data

• -u, --user=USER nom de l'utilisateur CCDA. Le mot de passe devra être saisi de manière interactive.
• --cert CERT certificat X509 à utiliser pour autorisation (non encripté, en format PEM)
• --netrc-file NETRC_FILE fichier netrc à utiliser pour identification
• --fhead télécharge l'en-tête du fichier FITS
• -z, --decompress décomprime le fichier (format gzip).
• -o, --output OUTPUT liste des fichiers destinations à télécharger (séparés par un espace, et des guillemets pour plusieurs éléments)
• --cutout [CUTOUT [CUTOUT ...]] découpage d'une ou plusieurs extension FITS, ou des paramètres de découpage. La syntaxe de cfitsio est utilisée.
• -q, --quiet éxécute la commande en arrière plan

Adresse URL du service des données

L'adresse URL du service des donées est seulement utilisée pour télécharger les données par transfer direct, par exemple:

https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/1722795p.fits[24][520:990,2420:2782]

L'adresse URL a quatre parties:

Cette adresse URL (et les autres ci-dessous) peut servir sur la ligne de commande des clients web (comme wget, curl) ou avec des scripts (comme avec la bibliothèque requests) de Python.

Utilisation de wget et de curl

Exemple simple avec wget:

wget https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/HLADR2/hst_05476_4r_wfpc2_total_pc_drz.fits.gz

Exemple simple avec curl:

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

Les options -O -J provoquent l'enregistrement local du fichier en utilisant le nom de fichier spécifié au serveur Content-Disposition si disponible, ou extrait un nom du fichier de l'adresse URL sinon (au lieu de l'enregistrer vers STDOUT). L'option -L entraîne le suivi de tout réacheminement.

Si les données que vous téléchargez ne sont pas publiques, vous devez utiliser votre nom d'utilisateur et votre mot de passe du CCDA. Par exemple avec wget:

wget --user=fred --password=Pas$w0rD https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/HLADR2/hst_05476_4r_wfpc2_total_pc_drz.fits.gz

Avec curl:

curl -u fred:Pas$w0rD -O -J -L https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/HLADR2/hst_05476_4r_wfpc2_total_pc_drz.fits.gz

Les deux commandes acceptent plusieurs autres options

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 NUMBER fixe le nombre de tentatives jusqu'à la valeur précisée par NUMBER (nous recommandons 5 tentatives).

Découpages

Autres paramètres de l'adresse URL utilisés lors du téléchargement d'un fichier afin de faire un découpage:

Exemples de syntaxes de découpage

Exemples de découpages

1. Découpage d'une seule extension

   cadc-data get --output 806045o-cutout1.fits --cutout [1] CFHT 806045o
   curl --location-trusted -g -o 806045o-cutout1.fits "https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o?cutout=[1]"

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

   cadc-data get --output D3.IQ.R.9979_10490_10573_11084.fits --cutout [9979:10490,10573:11084] CFHTSG D3.IQ.R.fits
   curl --location-trusted -g -o D3.IQ.R.9979_10490_10573_11084.fits "https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHTSG/D3.IQ.R.fits[9979:10490,10573:11084]"

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

   cadc-data get --output 806045o-cutout2.fits --cutout [1][1:100,1:200] CFHT 806045o
   curl --location-trusted -g -o 806045o-cutout2.fits "https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o?cutout=[1][1:100,1:200]"

4. Découpage sur plusieurs extensions

   cadc-data get --output 806045o-cutout3.fits --cutout [1][2] CFHT 806045o
   curl --location-trusted -g -o 806045o-cutout3.fits "https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o?cutout=[1]&cutout=[2]"

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

   cadc-data get --output 806045o-cutout4.fits --cutout [1][10:120,20:30] [2][10:120,20:30] CFHT 806045o`
   curl --location-trusted -g -o 806045o-cutout4.fits "https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o?cutout=[1][10:120,20:30]&cutout=[2][10:120,20:30]"

6. Découpage d'une seule extension

   cadc-data get --output 806045o-cutout5.fits --cutout [1] CFHT 806045o
   curl --location-trusted -g -o 806045o-cutout5.fits "https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o[1]"

7. Extension et découpage sur les coordonnées d'un pixel (version courte)

   cadc-data get --output 806045o-cutout6.fits --cutout [1][1:100,1:200] CFHT 806045o
   curl --location-trusted -g -o 806045o-cutout6.fits "https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o[1][1:100,1:200]"

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

Remarque: cette option est incompatible avec l'option de découpage (cutout).

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

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

Autre paramètre lié à l'adresse URL utilisé pour télécharger des renseignements sur l'en-tête FITS:

Exemples

• Récupérer l'en-tête FITS d'une seule extension d'un fichier du CFHT

  HTTP HEAD à: https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o?cutout=[1]

  curl -v --location-trusted -g --head "https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o?cutout=[1]"

• Affichage des en-têtes FITS de l'extension d'un fichier CFHT (version courte):

  HTTP HEAD à: https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o[1]

  curl -v -L -g --head "https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/CFHT/806045o[1]"

Utilisation avancée du client cadc-data

Pour télécharge un fichier en utilisant le client, utilisez le nom du fichier et de l'archive:

cadc-data get IRIS I001B3H0.fits

Si cadc-data n'est pas capable de télécharger le fichier, un message d'erreur est affiché.

cadc-data info FOO foo.fits

affiche:

ERROR:cadc-data:File name foo.fit not found in archive FOO
ERROR:cadc-data:Finished with 1 error(s)

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

cadc-data put CFHT newFile

Utilisez la commande info de cadc-data pour récupérer les meta-données d'un fichier:

cadc-data info IRIS I001B3H0.fits

    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

Information sur les meta-données affichées par cadc-data info:

Utilisation avancée

Téléversement d'un fichier

Pour télécharger un fichier vers le service de données, vous devez détenir les droits d'accès d'écriture dans l'archive demqndée. Pour procéder à un téléversement, utilisez une commande de requête HTTP PUT sur l'adresse URL du fichier et du flux source connexe de données. Si la commande réussit, le système transmet un code de réponse HTTP 201.

Exemple de téléversement:

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

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

Ressources du service de données

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 selectionné 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 simplement vérifier la présence d'un fichier et la possibilité d'y accéder, 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 de base sur le fichier.

Pour afficher les en-têtes HTTP au moyen de 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 entêtes sont des en-têtes HTTP 1.1 standard.

Service de données 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. Veuillez noter que vous pourriez aussi vouloir utiliser l'option --no-clobber 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.|

Dans le cas d'une adresse URL qui précise un découpage, le nom de fichier suggéré dans l'en-tête Content-Disposition comporte une partie supplémentaire; les différents découpages tirés du même fichier auront ainsi des noms de fichier distincts. Cette partie supplémentaire est en quelque sorte lisible, bien que bon nombre de caractères soient remplacés par un soulignement (_) pour en assurer la compatibilité avec l'internet et les systèmes de fichiers. Cette partie supplémentaire est uniforme d'une commande à une autre portant les mêmes paramètres de découpage.

Aide du CCDA

Pour obtenir de l'aide ou du soutien en ce qui a trait au service de données, envoyez un courriel à mailto:cadc@nrc.ca