API du serveur CDSPortal

Paramètres communs à tous les points d'entrée

Ci-dessous sont listés les paramètres qui sont communs à toutes les commandes. La casse des noms des paramètres n'a aucune importance (contrairement aux paramètres spécifiques à chaque commande, qui eux doivent forcément être en minuscule) :

command

C'est le nom de la commande à exécuter. La liste des commandes connues est données un peu plus bas. La casse des noms des commandes n'a aucune importance. Ce paramètre est obligatoire.

sessionId

C'est l'identifiant de l'utilisateur. Ce paramètre est obligatoire.

format

Le format dans lequel les données seront renvoyées. Ce paramètre est optionnel. La casse n'a pas d'importance. La valeur par défaut est xml. Le seul autre format reconnu est json.

outputFormat

Ce paramètre ne sert que pour la commande downloadTable. Il sert à indiquer dans quel format la VOTable doit être renvoyé. La casse n'a pas d'importance. Les valeurs possibles sont : vot, csv, tsv et fits.

Commandes reconnues

tables

Cette commande permet de récupérer la liste de toutes les VOTable que l'utilisateur a uploadé. Voici un exemple de réponse au format json.

{"cdsStore": {"tables": [
    {
        "date": "1473263765224",
        "fileName": "A2744CL-1",
        "metadata": {
            "coordinates": {
                "decUnit": "deg",
                "dec": "DEC",
                "raUnit": "deg",
                "errorType": "noError",
                "ra": "RA"
            },
            "comment": "bla bla bla"
        },
        "size": "6018",
        "nbRows": "1"
    },
    {
        "date": "1474374997438",
        "fileName": "csv-with-header.csv",
        "metadata": {
            "coordinates": {},
            "comment": "csv hide"
        },
        "size": "941",
        "nbRows": "3"
    }
]}}

S'il n'y a qu'une seule table, la valeur de tables n'est pas un tableau, mais un objet. Voici un exemple :

{"cdsStore": {"tables": {
    "date": "1474374997438",
    "fileName": "csv-with-header.csv",
    "metadata": {
        "coordinates": {},
        "comment": "csv hide"
    },
    "size": "941",
    "nbRows": "3"
}}}

S'il n'y a aucune table, un objet vide est rendu :

{"cdsStore": {}}

Dans le navigateur, pour obtenir systématiquement un tableau, vous pouvez écrire :

[].concat(cdsStore.tables);

L'objet coordinates existent toujours dans les métadatas, même s'il est vide. Cf l'exemple ci-dessus concernant le fichier csv-with-header.csv.

deleteTables

Cette commande permet de supprimer une table qui a été uploadé. La commande prend un seul argument, tables, qui contient la liste des noms des tables à supprimer, séparées par des slash ( / ).Ce caractère fait parti des caractères qui ne peuvent pas être dans le nom d'un fichier. Voir les commandes upload, uploadFromUrl et rename

La valeur rendue par la commande est toujours la suivante, même si on a demandé la suppression d'une table inexistante.

{"cdsStore": {}}

downloadTable

Cette commande permet de récupérer une table. Cette commande utilise l'argument général outputFormat. Le paramètre filename est obligatoire, et donne le nom du fichier à récupérer. En sortie, on récupère la VOTable dans le format qui a été spécifié par outputFormat.

updateTableComment

Cette commande permet de modifier le commentaire associé à une table. Le commentaire est stocké dans les métadonnées qui sont renvoyées lorsqu'on récupère la liste de toutes les tables.

Les arguments sont filename et comment. Ils sont obligatoires.

En résultat, la commande renvoie dans l'objet cdsPortal, un sous objet nommé commentUpdated, qui a comme valeur le nouveau commentaire.

updateCoordinatesMetadata

Cette commande permet de mettre à jour les informations sur les colonnes RA et DEC de la VOTable, ainsi que sur les colonnes d'erreurs associées. La liste des paramètres reconnus est

Lors de la mise à jour de ces informations, aucune vérification n'est faite côté serveur sur les valeurs. Ces informations sont utilisées par le serveur de Xmatch.

tableMetadata

Cette commande permet de récupérer les informations concernant les colonnes d'une table. Le paramètre filename, indiquant pour quelle VOTable on veut le résultat, est obligatoire. Le résultat donne la liste de toutes les colonnes de la table, avec l'ucd de la colonne. Un exemple de résultat :

{"cdsStore": {"columns": [
    {
        "ucd": "meta.id;meta.main",
        "name": "ID"
    },
    {
        "ucd": "pos.eq.ra;meta.main",
        "name": "RA"
    },
    {
        "ucd": "pos.eq.dec;meta.main",
        "name": "DEC"
    },
    {
        "ucd": "phot.mag;em.opt.B",
        "name": "MAG_B435"
    },
    {
        "ucd": "phot.mag;em.opt.V",
        "name": "MAG_V606"
    },
    {
        "ucd": "stat.error;phot.mag;em.opt.B",
        "name": "MAGERR_B435"
    },
    {
        "ucd": "stat.error;phot.mag;em.opt.V",
        "name": "MAGERR_V606"
    }
]}}

Tout comme pour les tables, s'il n'y a qu'une seule colonne, la valeur de columns est un objet, pas un tableau.

rename

Cette commande permet de renommer un fichier. Les paramètres obligatoires (forcément en minuscule) sont :

filename : le nom actuel du fichier. Le nom est transformé, s'il contient des caractères interdits. Voir la commande upload pour plus de détails.

newname : le nouveau nom du fichier. Il ne faut pas qu'un autre fichier avec le nouveau nom existe, sinon une erreur est rendue.

En cas de succès, le résultat est :

{"cdsStore": {"rename": "ok"}} 

addThing

Cette commande permet d'ajouter un objet JSON. Le contenu de l'objet est absolument libre. Les paramètres obligatoires sont :

category : la category dans laquelle l'objet sera rangé. Le caractère virgule , est interdit dans le nom de la categorie.

id : un identifiant unique de l'objet, pour la catégorie en question. 2 catégories différentes peuvent contenir le même id.

value : la valeur de l'objet. C'est une chaîne de caractères qui doit contenir un objet json correctement formaté. L'ensemble de l'objet est sauvé, sans que le serveur regarde le contenu. La seule exception est la valeur de id. Lorsqu'on récupère une liste d'objets, cette valeur sera écrasée par l'identifiant donné par le paramètre id. La longueur maximum de la chaîne de caractères de la valeur est limitée. La limite actuelle est 2048 octets.

maxThings : ce paramètre optionnel indique le nombre maximum d'objets à garder dans cette catégorie. Si la limite est dépassée avec le nouveau objet qu'on ajoute, les plus anciens objets sont supprimés.

setThings

Cette commande remplace complètement tous les objets d'une catégorie par le ou les nouveaux objets passés avec la commande. Les paramètres obligatoires sont :

category : la category dans laquelle l'objet sera rangé. Le caractère virgule , est interdit dans le nom de la categorie.

value : la liste des nouveaux objets à stocker. C'est une chaîne de caractères qui doit contenir un objet json correctement formaté. Voici un exemple de format :

value={id10:{p33: v3, p44:v4},id11:{p1:v1}}

La commande renvoie le nombre d'objets ajoutés :

{"cdsStore": {"thingsSet": "2 things added."}}

things

Cette commande permet de récupérer tous les objets pour une catégorie donnée. category est un argument obligatoire. Il peut contenir une liste de noms de catégories que l'on veut récupérer, séparé par le caractère ,. L'identifiant de chaque objet est un mis à l'intérieur de l'objet qui a été donné lors de l'ajout. Voici un exemple de résultat, si on demande 2 catégories ( test-cat et prefs) :

{"cdsStore": {
    "test-cat": {
        "v": "c",
        "id": "id1"
    },
    "prefs": [
        {
            "p1": "v1",
            "p2": "v2",
            "id": "id1"
        },
        {
            "p3": "v3",
            "p4": "v4",
            "id": "identifier"
        }
    ]
}}

Comme pour les tables, lorsque la catégorie ne contient qu'une seule entrée, c'est un objet. S'il y a plusieurs entrées, c'est un tableau qui est récupéré.

La valeur d'un objet peut être un tableau. Par contre, il y a 2 restrictions. À l'intérieur d'un tableau, il faut des valeurs simples (pas de tableau ou un nouvel objet). Si le tableau ne contient qu'une seule valeur, alors cette valeur est renvoyée comme une valeur simple, et pas comme un tableau à une seule valeur.

deleteThing

Cette commande permet de supprimer un objet. Les paramètres category et id sont obligatoires. Voici un exemple de résultat rendu :

{"cdsStore": {"thingDeleted": {
    "id": "id1",
    "category": "prefs"
}}}

upload

Permet l'upload d'une VOTable. Le format du fichier d'entrée est automatiquement détecté, en utilisant la librairie STIL.

Les paramètres optionnels sont comment et origin. La valeur par défaut de origin est Upload. La valeur de comment, si présente, est stockée dans les métadonnées.

4 caractères sont interdits dans les noms des fichiers : /, &, < et ,. Ces 4 caractères sont remplacés par un _ au moment du upload.

uploadFromUrl

Permet l'upload d'un catalogue, en donnant l'URL depuis laquelle obtenir le catalogue.

Les paramètres obligatoires sont url et filename. Le code est le même que pour la commande upload. Il y a donc les mêmes paramètres optionnels, et les mêmes transformations concernant d'éventuels caractères interdits.

Le résultat a le format :

{"cdsStore": {"uploadFromUrl": "ok"}} 

Et en cas d'erreur :

{"cdsStore": {"error": "Error while uploading from url: http://cdsarc.u-strasbg.fr/viz-bin/vizgraph= =?-s=I/337&-i=.graph_sql&Source=4659456740670442752&file=fov.dat&--output=votable"}}

-- PascalWassong - 2016-09-20