Documentation

Documentation Accès directement aux données

Accès directement aux données

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:

L'adresse URL a quatre parties:

Élément Description
ressource du service de données https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub/. L'adresse URL de base qui désigne la ressource du service de données. La terminaison data/pub vous permet d'accéder à tous les fichiers publics. Si le fichier est exclusif, vous êtes redirigé vers data/auth où vous devez saisir votre nom d'utilisateur et votre mot de passe du CCDA dans la fenêtre surgissante habituelle d'un navigateur ou sur la ligne de commande au moyen des commandes wget et curl. Il existe d'autres options décrites ci-dessous à la section Ressources pour le service de données.
archive CFHT: désigne le nom de l'archive. Les archives disponibles sont dans ce fichier: archives.txt
fileID 1722795p.fits: désigne le nom du fichier.
options [24][520:990,2420:2782]: après le nom du fichier, vous pouvez ajouter des options, dans le présent cas, un découpage. Cette adresse URL télécharge seulement une sous-section de l'image.

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:

Nombre Paramètre Valeur Explication
un ou plus cutout [numéro de l'extension][section de l'image] Lorsque vous recherchez un fichier de type FITS, vous pouvez inclure divers paramètres liés aux découpages afin de récupérer seulement ces découpages. Nous utilisons un sous-ensemble de la spécification de la section d'image CFITSIO pour préciser le découpage. Veuillez noter que vous pouvez aussi utiliser les paramètres d'un seul découpage en guise de suffixe dans l'élément de l'identifiant du fichier de l'adresse URL.

Exemples de syntaxes de découpage

Image Section Explanation
[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
    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:

Nombre Paramètre Valeur Explication
un ou plus fhead vraie Lors du téléchargement d'un fichier de type FITS, l'ajout du paramètre fhead=true donne lieu au téléchargement des seuls renseignements sur l'en-tête du fichier.

Exemples

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:

Nom Explication
archive nom de l'archive
encoding type de codage (en général une compression) utilisé (optionnel)
lastmod date de la dernière modification du fichier (optionnel; absent lors d'une modification durant la livraison)
md5sum condensé MD5 du contenu du fichier
name nom de fichier suggéré pour les clients qui enregistrent le fichier
size taille du fichier téléchargé en octet
type type MIME du fichier (optionnel; seulement si le type est connu)
umd5sum condensé MD5 du contenu du fichier non comprimé (optionnel; absent lors d'une modification durant la livraison)
usize taille du fichier non comprimé en octets (optionnel; absent lors d'une modification durant la livraison)

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:

Ressources du service de données

Ressource Description
https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub Ressource de transfert du fichier de données publiques. Le dossier /pub sous HTTP ne recueille pas les justificatifs d'identité de l'utilisateur. Donc, si vous téléchargez un fichier non public ou téléversez vers un dossier non public, vous serez redirigé vers https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/auth et vous serez invité à saisir votre nom d'utilisateur et votre mot de passe.
https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/auth Ressource de transfert du fichier de données authentifiées. Cette ressource vous invite à saisir votre nom d'utilisateur et votre mot de passe du CCDA à des fins d'authentification et d'autorisation.
https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/pub Ressource de transfert du fichier de données SSL. L'utilisation d'un certificat client est nécessaire pour vous connecter à cette ressource SSL. Votre autorisation dépend des justificatifs d'identité inscrits sur le certificat.
https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/transfer Point d'extrémité de la négociation du transfert lors des téléchargements et des téléversements.
https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/transfer Point d'extrémité de la négociation du transfert qui soumet le certificat client en vue de l'authentification et de l'autorisation.
https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/auth/transfer Point d'extrémité de la négociation du transfert qui soumet le nom d'utilisateur et le mot de passe en vue de l'authentification et de l'autorisation.
https://www.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/data/availability Ressource qui peut servir à vérifier la disponibilité du service de données. L'exécution d'une commande "HTTP get" sur cette ressource produit un document XML qui décrit l'état du service.

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.

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