Tous les exemples de données de cette page sont fictifs. En particulier, il est rappelé que les métadonnées sont avant tout dédiées à recevoir des données d’interconnexion avec des services extérieurs (identifiants permettant de consulter des services externes).
Depuis la version 1.54 (janvier 2024), un endpoint supplémentaire permet de modifier les métadonnées par lot de 100 offres : cette méthode est à privilégier si vous souhaitez modifier un nombre important de métadonnées en même temps.
Webservice unitaire
Modification des métadonnées d’un seul objet à la fois
Présentation du web-service
L’administration des métadonnées d’un de vos noeud se fait par le biais d’une API REST. L’action est déterminé par la méthode passée dans la requête :
- Méthode GET : lecture des métadonnées du noeud.
- Méthode PUT : permet d’insérer ou de modifier des métadonnées du noeud.
- Méthode DELETE : permet de supprimer des métadonnées du noeud.
Authentification
L’authentification du projet se fait via une authentification « client credentials » OAuth.
Cette méthode d’authentification permet de récupérer un token qui doit être passé dans l’en-tête HTTP de l’appel pour authentifier le projet.
Méthodes d’accès au service REST
GET
Récupère des métadonnées sur un objet et pour un noeud donné. Si aucune cible n’est spécifiée, retourne l’intégralité des métadonnées de l’objet pour ce noeud.
- méthode : GET
- url : /v002/metadata/{referenceId}/{nodeId}/{targetType}/{targetId}
- paramètres :
- referenceId, paramètre obligatoire. Un entier, l’id de l’objet touristique portant les métadonnées.
- nodeId, paramètre obligatoire. Une chaîne de caractères, le nom de votre noeud fournissant les métadonnées.
- targetType, paramètre facultatif. Une chaîne de caractères, le type de la cible parmi general, membre, projet.
- targetId, paramètre facultatif. Un entier, l’id du membre ou du projet cible.
- exemple d’appel : /api/v002/metadata/100798/alliance-reseau-commercialisation/projet/1
- résultat : l’information associé à l’objet, au noeud et à la cible indiquée.
DELETE
Supprime une ou plusieurs métadonnées sur une objet et pour un noeud donné. Si aucune cible n’est spécifiée, supprime l’intégralité des métadonnées de l’objet pour ce noeud.
- méthode : DELETE
- url : /v002/metadata/{referenceId}/{nodeId}/{targetType}/{targetId}
- paramètres :
- referenceId, paramètre obligatoire. Un entier, l’id de l’objet touristique portant les métadonnées.
- nodeId, paramètre obligatoire. Une chaîne de caractères, le nom de votre noeud fournissant les métadonnées.
- targetType, paramètre facultatif. Une chaîne de caractères, le type de la cible parmi general, membre, projet.
- targetId, paramètre facultatif. Un entier, l’id du membre ou du projet cible.
- exemple d’appel : /api/v002/metadata/100798/alliance-reseau-commercialisation/membre/64
- résultat : Code 200 si la suppression s’est passée sans erreur. Une erreur sinon.
PUT
Insère ou modifie des métadonnées sur un objet, pour un noeud donné. Attention, pour cette méthode, les métadonnées doivent être passées dans des paramètres de la requête. Voir le format des données.
Remarque : Si vous insérez une métadonnée pour une cible qui en a déjà une, la métadonnée pré-existante sera écrasée et remplacée par la nouvelle.
- méthode : PUT
- url : /v002/metadata/{referenceId}/{nodeId}
- paramètres d’URL :
- referenceId, paramètre obligatoire. Un entier, l’id de l’objet touristique portant les métadonnées.
- nodeId, paramètre obligatoire. Une chaîne de caractères, le nom de votre noeud fournissant les métadonnées.
- Exemple d’appel : /api/v002/metadata/100798/alliance-reseau-commercialisation
- résultat : Code 200 si la modification s’est passée sans erreur. Une erreur sinon.
Format des données
Les métadonnées doivent être insérées dans des paramètres de la requête PUT.
Il existe plusieurs moyens d’insérer des métadonnées, à utiliser selon le nombre de métadonnées à insérer et le type de cibles visées.
Insérer les métadonnées unes à unes
- Nom du paramètre : le type de cible (general, membre ou projet), suivi de l’id de la cible si nécessaire, sous la forme _.
- Données associées au paramètre : la métadonné JSON.
Exemple :
general={"infoGenerale":"Ceci est une information a portée générale"}
membres.membre_42={"foo":"Lorem ipsum dolor sit amet, consectetur adipisicing elit"}
projets.projet_1={"pression":2.2,"temperatures":[10,25]}Insérer plusieurs métadonnées pour un meme type de cible
- Nom du paramètre : membres ou projets, selon le type de cible à insérer.
- Données associées au paramètre : une liste d’éléments au format JSON. Chaque élément possède doit posséder un champ targetId, pour l’id de la cible, et un champ jsonData, contenant la métadonnée encodée au format json (c’est donc un champ texte contenant la donnée json encodée et échappée).
Exemple :
membres= [
{
"targetId" : 21,
"jsonData" : "{ \"texte1\":\"Cette information est à destination du membre 21\" , \"departements\" : [69,38]"}
},
{
"targetId" : 12,
"jsonData" : "{ \"bar\":\"Lorem ipsum dolor sit amet, consectetur adipisicing elit\" }"
}
]
projets=[
{
"targetId" : 118,
"jsonData" : "{ \"foo\":\"Ceci est une information à destination du projet 118\", \"temperature\" : 19}"
},
{
"targetId" : 322,
"jsonData" : "{ \"lipsum\":\"Lorem ipsum dolor sit amet, consectetur adipisicing elit\" }"
}
]Insérer plusieurs métadonnées pour des types de cibles différents
- Nom du paramètre : node.
- Données associées au paramètre : une structure de données, au format JSON. La structure est composée de trois champs : general qui contient la métadonnée à portée générale, membres et projets qui contiennent une structure de données similaire à celle présentée ci-dessus.
Exemple :
node={
"general":"{\"capaciteMax\":12,\"capaciteMin\":2,\"note\":\"Lorem ipsum\"}",
"membres":[
{
"targetId" : 21,
"jsonData" : "{ \"texte1\":\"Cette information est à destination du membre 21\" , \"departements\" : [69,38]}"
},
{
"targetId" : 12,
"jsonData" : "{ \"bar\":\"Lorem ipsum dolor sit amet, consectetur adipisicing elit\" }"
}
],
"projets":[
{
"targetId" : 118,
"jsonData" : "{ \"foo\":\"Ceci est une information à destination du projet 118\", \"temperature\" : 19}"
},
{
"targetId" : 322,
"jsonData" : "{ \"lipsum\":\"Lorem ipsum dolor sit amet, consectetur adipisicing elit\" }"
}
]
}Webservice par lot
Modification de 100 offres (maximum) par appel, disponible depuis janvier 2024
Endpoint : /api/v002/metadata/
Méthode : PUT
Authentification : client credentials OAuth
Paramètres (POSTFIELDS) :
query : Chaîne de caractère, JSON des modifications à réaliser
Détail du json composant query
Le json est un tableau, chaque entrée de premier niveau représentant une offre.
Une entrée (offre) est composée des paramètres suivants :
Voir schemas complets
referenceId : Identifiant de l’objet
node : Identifiant du noeud de métadonnée
action : ADD ou REMOVE
metadata : (ADD seulement) : voir schemas
targetType : general, membre, projet
targetId : Identifiant du membre ou du projet ciblé si targetType n’est pas general
Exemple de query
[
{
"referenceId": 4647678,
"node": "test-pg",
"action": "REMOVE"
},
{
"referenceId": 4647679,
"node": "test-pg",
"action": "ADD",
"metadata": {
"general": "{\"test\":\"2628\",\"test2\":\"2628\"}"
}
}
]Exemple en PHP
$ch = curl_init();
$curl_opts = [];
$curl_opts[CURLOPT_URL] = 'https://api.apidae-tourisme.(com|cooking|dev)/api/v002/metadata/';
$curl_opts[CURLOPT_HTTPHEADER] = [
'Accept: application/json',
'Authorization: Bearer 303118e6-5f95-4eaf-bd0b-***********'
];
$curl_opts[CURLOPT_POSTFIELDS] = [
'query' => '[{"referenceId":4647678,"node":"test-pg","action":"ADD","metadata":{"general":"{\"test\":\"2628\",\"test2\":\"2628\"}"}},{"referenceId":5787447,"node":"test-pg","action":"ADD","metadata":{"general":"{\"test\":\"2628\",\"test2\":\"2628\"}"}}]'
];
$curl_opts[CURLOPT_CUSTOMREQUEST] = 'PUT';
$curl_opts[CURLOPT_HEADER] = true;
$curl_opts[CURLOPT_SSL_VERIFYPEER] = false;
$curl_opts[CURLOPT_ENCODING] = 'UTF-8';
$curl_opts[CURLOPT_RETURNTRANSFER] = true;
$curl_opts[CURLOPT_FOLLOWLOCATION] = true;
$curl_opts[CURLOPT_CONNECTTIMEOUT] = 30;
$curl_opts[CURLOPT_TIMEOUT] = 30;
curl_setopt_array($ch, $curl_opts);
$response = curl_exec($ch);F.A.Q.
Une mise à jour de métadonnée déclenche-t-elle un export de l’offre ?
Oui, une mise à jour modifie la dateExportModification qui fait référence pour les exports et API : une métadonnée modifiée entraînera donc un export de l’offre lors des prochains calculs de sélections qui la contiennent.
Dans certains cas, il n’y aura aucune modification sur l’offre, si la métadonnée n’était pas générale par exemple (et donc pas visible sur tous les projets) : dans les faits, depuis la mise en place des métadonnées, toutes sont systématiquement générales (au 06/02/2024).
Une mise à jour de métadonnée déclenche-t-elle un appel au temps réel ?
Oui, un appel au temps réel pour signaler une mise à jour de l’offre concernée est réalisé sur tous les projets contenant l’offre (dans les mêmes conditions que pour les exports).