Guide d`utilisation-API - API Data RTE

Transcription

Guide d’Utilisation API referential_data
Version 1.0
GUIDE D’UTILISATION
API REFERENTIAL_DATA
Version 1
Date d’entrée en vigueur : 15 Septembre 2016
SOMMAIRE
1
Guide d’Utilisation API referential_data en version 01.00 de RTE
1
INTRODUCTION ________________________________________ 3
1.1
1.2
2
Version 1.0
Définitions ........................................................................................... 3
Assistance technique ............................................................................ 4
DESCRIPTION FONCTIONNELLE DE L’API REFERENTIAL_DATA __________ 5
2.1
2.2
Description générale ............................................................................. 5
Pré-requis à l’utilisation des API ............................................................. 5
2.2.1 Confidentialité des données ...................................................................... 5
2.2.2 Résiliation ................................................................................................ 5
2.3
Ressource « service_points/transcodifications» ....................................... 5
3
ACCES A L’API ________________________________________ 6
4
RESSOURCE EXPOSEE PAR L’API « REFERENTIAL_DATA » _____________ 7
4.1
Ressource /service_points/transcodifications ........................................... 7
4.1.1 GET /service_points/transcodifications....................................................... 7
4.1.1.1 Modalités d’appel ............................................................................ 7
5
4.1.1.2
Entrées .......................................................................................... 7
4.1.1.3
Sorties ........................................................................................... 8
4.1.1.4
Codes erreurs ............................................................................... 10
DETAILS DES ERREURS __________________________________ 11
5.1
Erreurs fonctionnelles ..........................................................................13
5.1.1 service_points/transcodifications ............................................................. 13
5.2
Erreurs techniques...............................................................................13
5.2.2 Codes erreurs transverses VESPA ............................................................ 13
2
Version 1.0
1 Introduction
Ce document décrit la version 1 l’API « referential_data ».
Cette API permet de mettre à disposition des sociétés ayant souscrits à des services de données la
correspondance entre les codes EIC et les codes Décomptes (PPE) / Points De Comptage / Points de
Livraisons et d’Injection Contractuels
Documents de référence
Référence
courte
[R1]
1.1
Titre du document
Référence complète
CGU des API RTE
Sera complété ultérieurement
Définitions
Les termes utilisés dans le Guide d’Utilisation et dont la première lettre est une majuscule sont définis
ci-dessous ou, à défaut, dans les Conditions Générales d’Utilisation [R1] :
Terme
Description
API
Application Programming Interface (Interface de programmation applicative)
Authentification
Mode de Protection permettant de s’assurer que l’identité de l’Émetteur ou
du Récepteur a été vérifiée par RTE et qu’il est donc autorisé à accéder au
SI et à utiliser les Applications.
Émetteur
Partie qui émet un Message.
EIC
« Energy Identification Code », système d’identification unique des acteurs
et des objets du marché de l’énergie (ex : entités, zones, points de mesures,
liaisons électriques d’interconnexion), défini par l’ENTSO-E.
Message
Ensemble de données informatiques destiné à véhiculer des informations et
structuré selon un ordre spécifié dans le Guide d’Utilisation. Un Message
peut être émis par l’Utilisateur ou RTE.
Opération
Une opération est la manière dont le client interagit avec la ressource de
l’API. Il s’agit d’un verbe http (par exemple : GET pour lecture)
Partie ou Parties
Dans le cadre du Guide d’Utilisation, il s’agit, individuellement, soit de RTE
soit de l’Utilisateur et, conjointement, de RTE et de l’Utilisateur.
Récepteur
Partie qui reçoit le Message de l’Émetteur.
Ressource
Une ressource représente la donnée sur laquelle l’application cliente
interagit.
3
Terme
Description
URL
Uniform Resource Locator : chaîne de caractères suivant un format
spécifique permettant de localiser une ressource sur un réseau et d’identifier
un moyen d’agir (protocole) sur cette ressource.
Utilisateur(s)
Personne morale ayant validé les Conditions Générales d’Utilisation des API
de RTE et accédant au SI de RTE afin d’utiliser les API mises à dispositions
par RTE.
PPE
Dans le cadre de la contractualisation du droit d’usage du réseau de
transport, le PPE est la maille élémentaire de décompte des flux d’énergie
selon les règles du mécanisme de RE (Responsable d’Equilibre). C’est un
regroupement de points de comptage de même classe de tension tarifaire
(1/40 kV, 41/130 kV, 131/350 kV, 400 kV), de même utilisation électrique
(alimentation principale, alimentation secours-substitution), de même durée
d’utilisation auquel s’applique un type de barème et un ensemble de
conditions contractuelles. Un seul contrat peut “ générer ” plusieurs PPE. Un
Equipement peut être relié à (0,n) PPE.
PDC
Le Point De Comptage est le point physique où sont placés les
transformateurs de mesure de courant et de tension destinés au comptage
des flux d’énergie.
PLIC
Point de Livraison et d’Injection Contractuel
OAuth 2
1.2
Version 1.0
OAuth 2.0 (Open Authorization) est un framework de délégation
d’autorisation qui permet à une application d’obtenir un jeton d’accès à des
données hébergées par un tiers.
Assistance technique
En cas de difficulté pour l’accès ou l’utilisation d’une API, l’Utilisateur peut faire appel aux services
d’assistance téléphonique mis en place par RTE dans les conditions techniques prévues dans les
Conditions Générales d’Utilisation.
4
Version 1.0
2 Description fonctionnelle de l’API referential_data
2.1
Description générale
Ce document décrit l’API referential_data en version 1 proposée par RTE à ses Clients dans le but de
mettre à disposition la correspondance entre les codes EIC et les codes internes RTE des points de
services.
2.2
Pré-requis à l’utilisation des API
L’API referential_data est destinée aux Clients titulaires d’un Contrat d’Accès au Réseau Public de
Transport (CART), d’un contrat de service de décompte ou à tous tiers mandatés par un Client titulaire
d’un contrat via une autorisation de transmission de données (ATD).
2.2.1 Confidentialité des données
Les informations contenues dans les Messages ne pourront être utilisées à d’autres fins que celles
prévues dans les Conditions Générales d’Utilisation [R1].
2.2.2 Résiliation
L’abonnement à une API est automatiquement résilié lorsque le Contrat ou l’ATD donnant droit à
l’utilisation de l’API est résilié ou arrive à expiration.
Si l’Utilisateur souhaite ne plus utiliser une API sans résilier son Contrat ou son ATD, il suffit de cesser
l’émission des appels à l’API.
2.3
Ressource « service_points/transcodifications»
Ce Service permet de fournir la correspondance entre les codes EIC et les codes internes RTE des points
de services.
5
3
Version 1.0
Accès à l’API
L’accès à l’API décrite dans ce document se fait via le protocole REST.
Comme pour toutes les API mises à disposition par RTE, l’accès et l’utilisation de ces API sont soumis
aux termes des Conditions Générales d’Utilisation [R1].
La méthode d’autorisation d’accès aux API est OAuth, dont les usages sont décrits dans la FAQ.
6
Version 1.0
4 Ressource exposée par l’API « referential_data »
4.1
Ressource /service_points/transcodifications
4.1.1 GET /service_points/transcodifications
4.1.1.1 Modalités d’appel
La ressource est exposée de la manière suivante :
Exposition
REST / JSON
Méthode
GET
http://digital.iservices.rte-france.com/private_api/referential_data/v1/service_points
/transcodifications?category_type=PLIC&range=0-999
Où les paramètres category_type et range sont les mêmes que ceux transmis à la
ressource par l’appelant.
http://digital.iservices.rte-france.com/private_api/referential_data/v1/sandbox/
service_points /transcodifications
URL ressource
URL sandbox
(1)
(1)
La sandbox ne prend pas en compte les paramètres d’entrées
4.1.1.2 Entrées
CHAMP
TYPE
CARD.
category_type
string
0..1
Type de
demandé.
0..1
Plage de points
demandés.
range
string
DESCRIPTION
point
VALEURS / FORMAT
de
service Valeurs possibles : {PLIC, PPE,
PDC}
de
service « X-Y » ou X représente le
numéro du premier élément
demandé, Y le numéro du dernier.
Exemples d’appel :
Sans paramètre
URL:
GET /private_api/referential_data/v1/service_points/transcodifications
Headers:
Host: digital.iservices.rte-france.com
Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z
Body:
Avec tous les paramètres
7
Version 1.0
URL:
GET /private_api/referential_data/v1/service_points/transcodifications?category_type=PLIC&range=0999
HTTP/1.1
Headers:
Host: digital.iservices.rte-france.com
Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z
Body:
4.1.1.3 Sorties en succès
Entêtes http en réponse :
CHAMP
TYPE
CARD.
Accept-Range
string
0..1
Response-Date
string
0..1
Content-Range
string
0..1
VALEURS / FORMAT
Description
Nombre maximal de points de
services pouvant être renvoyés
par appel à l’API
Date au format ISO 8601 Date de la réponse
yyyy-mm-jjThh:mm:sszzzzz
X-Y/Z ou X représente le
numéro du premier point
retourné, Y le dernier, Z le
total de points existants
Plage de ponts de services
renvoyés.
Corps de la réponse :
NOM
trans codifications
0..1
NOM
0..1
CARD.
DESCRIPTION
Structure {JSON} détaillée ci-dessous :
CARD.
DESCRIPTION
TYPE
VALEURS /
FORMAT
company_eic_code
0..1
Code EIC de la
société
string
category_type
0..1
Type de catégorie
du point de
service
string
Valeurs possibles
{PLIC, PPE, PDC}
string
Valeurs possibles si
category_type=PLIC:
{ PLIC HTA5, PLIC
CONCAVE, PLIC
HTB5}
service_point_category
Catégorie du point
de servie
0..1
8
:
Version 1.0
Sinon,
service_point_categor
y=category_type
service_point_eic_code
0..1
Code EIC du point
de service
string
service_point_external_code
0..1
Code Rte du point
de service
string
Format JSON du retour:
GET /private_api/referential_data/v1/service_points/transcodifications
HTTP/1.1 200 OK
Accept-Range: 1000
Response-Date: 2016-09-09T17:59:16Z
Content-Range: 0-5/6
{
"transcodifications":
[{
"company_eic_code": "SOC_1",
"category_type": "PDC",
"service_point_category": "PDC",
"service_point_eic_code": "XXX",
"service_point_external_code": "XXX"
},
{
"company_eic_code": "SOC_1",
"category_type": "PDC",
"service_point_category": "PDC",
"service_point_eic_code": "XXX",
"service_point_external_code": "XXX"
}]
}
9
Version 1.0
4.1.1.4 Codes erreurs
Le tableau suivant liste les codes erreurs pouvant être retournés lors de l'appel à la ressource.
Le détail de ces erreurs est décrit au chapitre 5 Détails des erreurs.
Type d’erreur
Code erreur
Détails
Fonctionnelle
REFEDATA_SEPOTR_F01
§5.1.1
Fonctionnelle
REFEDATA_SEPOTR_F03
§5.1.1
Technique
403
§5.2.2
Technique
404
§5.2.2
Technique
408
§5.2.2
Technique
413
§5.2.2
Technique
414
§5.2.2
Technique
429
§5.2.2
Technique
500
§5.2.2
Technique
503
§5.2.2
10
5
Version 1.0
Détails des erreurs
Le schéma ci-dessous présente les codes retournés à l’Utilisateur de l’API en fonction du séquencement
des appels.
Ce paragraphe concerne les erreurs communes à toutes les ressources de l’API et à ce titre il ne décrit
pas les erreurs de requêtes (code http 400). Ces erreurs sont décrites ressource par ressource dans le
paragraphe correspondant.
En cas d’erreur lors de la phase d’authentification (validation du login et du mot de passe) un code HTTP 401 «
unauthorized » est retourné à l’appelant.
La seconde étape est de vérifier que l’Utilisateur ne dépasse pas le nombre maximal d’appels autorisés pour
l’opération. En cas de dépassement, l’appelant en est informé par un code HTTP 429. La réponse du serveur
contient dans ce cas un entête "Retry-After:" indiquant le temps d'attente (en secondes) que le client doit attendre
avant de renvoyer sa demande.
La troisième étape est de vérifier que l’application est bien créée/habilitée à accéder à la plateforme technique
VESPA. Si ce n’est pas le cas l’appelant en est informé par un code HTTP 403 « forbidden ».
La quatrième étape consiste à vérifier que l’application a bien souscrit à un abonnement à l’API. Si ce n’est pas le
cas, l’appelant en est informé par un code HTTP 403 « forbidden ».
La cinquième étape consiste à accéder aux ressources de RTE. Diverses erreurs fonctionnelles peuvent se produire.
Celles-ci sont communiquées à l’Utilisateur en tant qu’erreur JSON. Les erreurs décrites dans ce document sont les
erreurs fonctionnelles retournées avec le code retour http 500.
11
Version 1.0
Structure JSON :
{
"error": "libelle_court, codification explicite de l’erreur",
"error_description": "libellé long, lisible par un utilisateur",
"error_uri": "URI vers le guide d’utilisation présent sur la plateforme technique VESPA ou la
FAQ/documentation sur le portail web de VESPA"
"error_details" : {
"transaction_id" : "identifiant unique d’appel, utile en cas d’incident"
}
}

Le libellé court (« error ») est un code permettant à l’application appelante de traiter
automatiquement les messages des erreurs. Il est représenté par une suite de mots séparés
par des « _ ».

Le libellé long (« error_description ») est une description permettant aux utilisateurs de
comprendre de façon plus précise l’origine de l’erreur. Ce libellé doit être validé par le métier
afin de s’assurer qu’il est suffisamment explicite.

L’URI vers le guide d’utilisation est présent pour donner plus d’explications en fonction de l’Api
appelée.

Le champ transaction_id : fournit un identifiant unique d’appel. Cet identifiant peut être utilisé
pour dialoguer avec la hotline Rte.
12
5.1
Version 1.0
Erreurs fonctionnelles
5.1.1 service_points/transcodifications
Ce tableau récapitule les erreurs fonctionnelles retournées par la ressource correspondant à une erreur
dans la requête :
REFEDATA_SEPOTR_F01
Code http
400
Message
Au moins une des valeurs du champ category_type n'est pas reconnue.
Si au moins une des valeurs du champ category_type n'est pas reconnue.
Description
REFEDATA_SEPOTR_F03
Code http
404
Message
Le code EIC de la société n’est pas reconnu.
Description
Si le code EIC de la société n’est pas reconnu.
REFEDATA_SEPOTR_F04
Code http
400
Message
Le seuil maximal de pagination est dépassé
Description
5.2
Un appel est fait avec un paramètre range représentant une plage de plus de
1000 éléments.
Erreurs techniques
5.2.2 Codes erreurs transverses VESPA
403
Code http 403
Message
Exemple
d'appel
Forbidden
L'application authentifiée n’est pas autorisée à exécuter l'opération demandée
404
Code http 404
Message
Not Found
Exemple
d'appel
La ressource appelée n’existe pas ou aucune donnée n’a été trouvée
408
13
Version 1.0
Code http 408
Message
Request Time-out
Exemple
d'appel
Erreur générée sur non réponse du service appelé ou retour en timeout (http 408) du
service appelé.
413
Code http 413
Message
Request Entity Too Large
Exemple
d'appel
La taille de la requête dépasse 5Mo
414
Code http 414
Message
Request-URI Too Long
Exemple
d'appel
L’URI transmise par l’appelant dépasse 512 caractères.
429
Code http 429
Message
Too Many Requests
Exemple
d'appel
Le nombre d’appel maximum dans un certain laps de temps est dépassé.
500
Code http 500
Message
Exemple
d'appel
Internal Server Error
Toute autre erreur technique.
(Cette erreur est accompagnée d’un message JSON avec un champ error_code et
error_description)
503
Code http 503
Message
Service Unavailable
Exemple
d'appel
Erreur générée sur maintenance (http 503).
FIN DU DOCUMENT
14

Guide d`utilisation-API - API Data RTE

Transcription

Documents pareils

Mission d`Hommes d`Affaires Tunisiens à WUHAN /La CHINE pour

LECON ORTHOGRAPHE 1 L`alphabet phonetique

Devenir formateur - tuteur pour accompagner les

RADIOPROTECTION DES LOCAUX

TITAN AVIATION - Groupe POURPRIX

frais d`approche et divers - Agence de Promotion de l`Industrie et de

L`organisation des fichiers

Nom de l`activité : Cours de piano, de chant, de guitare, accordéon,

Huile moteur

Saint-Orens-de-Gameville (31)