Guide d`utilisation-API - API Data RTE

Transcription

Guide d’Utilisation API actual_generation
Version 1.0
GUIDE D’UTILISATION
API ACTUAL_GENERATION
Version 1.0
Date d’entrée en vigueur : 08 Avril 2016
1
Version 1.0
SOMMAIRE
1
INTRODUCTION ________________________________________ 4
1.1
1.2
2
Définitions ........................................................................................... 4
Assistance technique ............................................................................ 5
DESCRIPTION FONCTIONNELLE DE L’API ACTUAL_GENERATION _________ 6
2.1
2.2
Description générale ............................................................................. 6
Pré-requis à l’utilisation des API ............................................................. 6
2.3
2.4
2.5
Ressource « actual_generations_per_production_type » .......................... 6
Ressource « actual_generations_per_unit » ............................................ 6
Ressource « water_reserves » ............................................................... 6
2.2.1 Confidentialité des données ...................................................................... 6
2.2.2 Résiliation ................................................................................................ 6
3
ACCES A L’API ________________________________________ 7
4
RESSOURCES EXPOSEES PAR L’API « ACTUAL_GENERATION » __________ 8
4.1
Ressource /actual_generations_per_production_type............................... 8
4.1.1 GET /actual_generations_per_production_type .......................................... 8
4.1.1.1 Modalités d’appel ............................................................................ 8
4.2
4.1.1.2
Entrées .......................................................................................... 9
4.1.1.3
Sorties ......................................................................................... 10
4.1.1.4
Règles de gestion ......................................................................... 12
4.1.1.5
Codes erreurs ............................................................................... 13
Ressource /actual_generations_per_unit................................................14
4.2.1 GET /actual_generations_per_unit .......................................................... 14
4.2.1.1 Modalités d’appel .......................................................................... 14
4.3
4.2.1.2
Entrées ........................................................................................ 15
4.2.1.3
Sorties ......................................................................................... 16
4.2.1.4
4.2.1.5
Codes erreurs ............................................................................... 20
Ressource /water_reserves...................................................................21
4.3.1 GET /water_reserves .............................................................................. 21
4.3.1.1 Modalités d’appel .......................................................................... 21
5
4.3.1.2
Entrées ........................................................................................ 22
4.3.1.3
Sorties ......................................................................................... 23
4.3.1.4
4.3.1.5
Codes erreurs ............................................................................... 25
DETAILS DES ERREURS __________________________________ 26
2
6
Version 1.0
5.1
Erreurs fonctionnelles ..........................................................................28
5.2
Erreurs techniques...............................................................................31
5.1.1 actual_generations_per_production_type ................................................ 28
5.1.2 actual_generations_per_unit ................................................................... 29
5.1.3 water_reserves ...................................................................................... 30
ANNEXES ___________________________________________ 32
6.1
Exemples
d’appels
ressource
« actual_generations_per_production_type » .........................................32
6.1.1 Cas sans paramètre – AGPPT-RG01......................................................... 32
6.1.2 Cas avec paramètres dates – AGPPT-RG02 .............................................. 32
6.1.3 Cas à la maille jour calendaire – AGPPT-RG05.......................................... 32
6.2
Exemples d’appels ressource « actual_generations_per_unit » ................32
6.3
Exemples d’appels ressource « water_reserves » ...................................33
6.2.1 Cas sans paramètre – AGPU-RG01 .......................................................... 32
6.2.2 Cas avec paramètre type – AGPU-RG02 ................................................... 33
6.2.3 Cas à la maille jour calendaire – AGPU-RG05 ........................................... 33
6.3.1 Cas sans paramètre – WARE-RG01 ......................................................... 33
6.3.2 Cas avec paramètre type – WARE-RG02 .................................................. 33
6.3.3 Cas à la maille jour calendaire – WARE-RG04 .......................................... 33
FIN DU DOCUMENT _____________________________________ 33
3
Version 1.0
1 Introduction
Ce document décrit l’API actual_generation en version 1 mise à disposition par RTE à ses Clients
dans le but d’exposer les données de production réalisées agrégées par filière, par groupe de production
ainsi que les données de stock hydraulique.
Documents de référence
Référence
courte
[R1]
1.1
Titre du document
Référence complète
CGU des API RTE
Lien accès
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] :
API
Application
applicative)
Programming
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.
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.
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.
4
Interface
(Interface
de
programmation
Version 1.0
Traduction des valeurs anglaises retournées par l’API :
Valeur en Anglais en sortie de l’API
AC_LINK
APPLICATION_DATE
Belgium
BIOMASS
CANCELLED
DC_LINK
England
FINISHED
FORCED_UNAVAILABILITY
FOSSIL_BROWN_COAL_LIGNITE
FOSSIL_COAL_DERIVED_GAS
FOSSIL_GAS
FOSSIL_HARD_COAL
FOSSIL_OIL
FOSSIL_OIL_SHALE
FOSSIL_PEAT
France
GENERATION_UNIT
GEOTHERMAL
Germany
HYDRO_PUMPED_STORAGE
HYDRO_RUN_OF_RIVER_AND_POUNDAGE
HYDRO_WATER_RESERVOIR
Italy
MARINE
NUCLEAR
OTHER
OTHER_RENEWABLE
PLANNED_MAINTENANCE
PRODUCTION_UNIT
SOLAR
Spain
SUBSTATION
Switzerland
TRANSFORMER
UPDATED_DATE
WASTE
WIND_OFFSHORE
WINF_ONSHORE
1.2
Traduction en Français
Ligne alternative
Date d'application
Belgique
Biomasse
Annulée
Ligne continue
Angleterre
Terminée
Indisponibilité fortuites
Lignite
Gaz issu du charbon
Gaz issu du charbon
Charbon
Fioul
Pétrole de schiste
Tourbe
France
Groupe de production
Géothermique
Allemagne
Hydraulique step
Hydraulique file de l'eau éclusée
Hydraulique lacs
Italie
Marine
Nucléaire
Autre
Autre renouvelable
Indisponibilité planifiée
Centrale de production
Solaire
Espagne
Sous-station
Suisse
Transformateur
Date de modification
Déchets industriels
Eolien offshore
Eolien terrestre
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.
5
Version 1.0
2 Description fonctionnelle de l’API actual_generation
2.1
Description générale
L’API permet d’accéder à trois ressources. Ces trois ressources sont uniquement accessibles en lecture,
via une opération de type GET.
2.2
Pré-requis à l’utilisation des API
L’API actual_generation est destinée aux acteurs du marché de l’électricité et au grand public.
Néanmoins les utilisateurs de l’API doivent créer un compte sur le portail digital du RTE. La création de
ce compte permet d’obtenir des identifiants Oauth 2.0. Ces identifiants sont ensuite requis lors des
appels aux API.
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 l’utilisateur supprime son compte sur le
portail Digital RTE.
Si l’Utilisateur souhaite ne plus utiliser une API sans résilier l’abonnement, il suffit de cesser l’émission
des appels à l’API.
2.3 Ressource « actual_generations_per_production_type »
Cette ressource permet de récupérer les données de production réalisées agrégées par filière en
infrajournalier correspondant à la production nette injectée sur le réseau.
2.4 Ressource « actual_generations_per_unit »
Cette ressource permet de récupérer les données de production réalisées par groupe en infrajournalier.
Les données de réalisation sont construites en H+1 à partir de télémesures sur le réseau de RTE. Elles
concernent la production nette injectée sur le réseau. Pour les groupes ne produisant pas, ce chiffre
peut être négatif du fait de la consommation du site.
2.5
Ressource « water_reserves »
Cette ressource permet de récupérer les données de stock hydraulique. Le stock hydraulique à la maille
France représente le taux agrégé de remplissage hebdomadaire des réservoirs et centrales de stockage
hydraulique de type Lac, constaté le lundi à 0h00. Il est exprimé en MWh et envoyé par les producteurs
à RTE, qui agrège les données avant publication. Cette donnée est publiée chaque mercredi à 12h30
ou le jour suivant si le mercredi n’est pas un jour ouvré.
6
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.
7
Version 1.0
4 Ressources exposées par l’API « actual_generation »
4.1
Ressource /actual_generations_per_production_type
4.1.1
GET /actual_generations_per_production_type
4.1.1.1 Modalités d’appel
La ressource est exposée de la manière suivante :
Exposition
REST / JSON
Méthode
GET
https://digital.iservices.rtefrance.com/open_api/actual_generation/v1/actual_generations_per_production_type?s
tart_date=<valeur>&end_date=<valeur>
https://digital.iservices.rtefrance.com/open_api/actual_generation/v1/sandbox/actual_generations_per_productio
n_type
URL ressource
URL sandbox
(1)
(1)
La sandbox ne prend pas en compte les paramètres d’entrées
Préconisations d’appels
Cette ressource a pour objectif de permettre de récupérer la production infrajournalière réalisée agrégée
par filière. Dans le cas d’utilisation nominal il n’est pas nécessaire de renseigner les champs de la
période. Le service retourne automatiquement le réalisé de la journée en cours Cf. AGPPT-RG01.
Les données mises à disposition sont à partir du 15/12/2014. Les données antérieures à cette date
sont disponibles uniquement sous forme de fichiers d'archives.
Il est conseillé de faire un appel par heure à ce service et de ne pas dépasser une période de 155 jours
par appel.
8
Version 1.0
4.1.1.2 Entrées
1
NOM
CARD.
start_date
0..1
end_date
0..1
DESCRIPTION
Date de début de
recherche des prévisions
Date de fin de recherche
des prévisions
TYPE
date
date
VALEURS / FORMAT
YYYY-MMDDThh:mm:sszzzzzz1
REGLES
AGPPT-RG01
AGPPT-RG02
AGPPT-RG01
AGPPT-RG02
Les dates en paramètre peuvent être exprimées sur n’importe quel fuseau horaire
Exemples d’appel :
Sans paramètre
URL:
GET /open_api/actual_generation/v1/actual_generations_per_production_type
HTTP/1.1
Headers:
Host: digital.iservices.rte-france.com
Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z
Body:
Avec tous les paramètres
URL:
GET /open_api/actual_generation/v1/actual_generations_per_production_type? start_date=2015-0608T00:00:00%2B02:00&end_date=2015-06-11T00:00:00%2B02:00
HTTP/1.1
Headers:
Body:
9
Version 1.0
4.1.1.3 Sorties
NOM
CARD.
actual_generations_p
er_production_type
1..1
NOM
DESCRIPTION
Tableau de valeurs {JSON} contenant 1 occurrence par type de production
retourné. Sa structure est la suivante :
CARD.
DESCRIPTION
TYPE
Date de début de recherche
date
des prévisions
Date de fin de recherche des
date
prévisions
VALEURS / FORMAT
Une des valeurs
suivantes :
BIOMASS
FOSSIL_BROWN_COAL_L
IGNITE
FOSSIL_COAL_DERIVED_
GAS
FOSSIL_GAS
FOSSIL_HARD_COAL
FOSSIL_OIL
FOSSIL_OIL_SHALE
FOSSIL_PEAT
GEOTHERMAL
HYDRO_PUMPED_STORA
GE
HYDRO_RUN_OF_RIVER
_
AND_POUNDAGE
HYDRO_WATER_RESERV
OIR
MARINE
NUCLEAR
OTHER_RENEWABLE
SOLAR
WASTE
WIND_OFFSHORE
WIND_ONSHORE
OTHER
start_date
1..1
end_date
1..1
production_type
1..1
Filière de production
values
1..1
Une valeur par intervalle de temps.
Tableau de valeurs {JSON} structuré comme suit :
0..n
enum
NOM
0..n
start_dat
e
CARD.
DESCRIPTION
TYPE
1..1
Début de l'intervalle
de temps
date
end_date 1..1
Fin de l'intervalle de
temps
date
updated_
1..1
date
Date de mise à jour
des données
date
value
Valeur de la prévision
de l'intervalle
int
1..1
REGLES
AGPPT
AGPPT
AGPPT
AGPPT
–
AGPPT -RG04
VALEURS /
REGLES
FORMAT
YYYY-MMDDThh:mm:sszzz –
zzz1
YYYY-MM–
DDThh:mm:sszzz
zzz1
YYYY-MMDDThh:mm:sszzz –
zzz1
Entier numérique –
1 Les dates en retour sont exprimées en heure française (UTC + 2 heures en été, UTC 1 heure en hiver)
10
-RG03
-RG05
-RG03
-RG05
Version 1.0
Format JSON du retour :
GET /open_api/actual_generation/v1/actual_generations_per_production_type
HTTP/1.1 200 OK
{"actual_generations_per_production_type": [
{
"start_date": "2016-01-12T00:00:00+01:00",
"end_date": "2016-01-12T11:12:09+01:00",
"production_type": "BIOMASS",
"values": [{ "start_date": "2015-11-12T00:00:00+01:00", "end_date": "2015-11-12T00:30:00+01:00",
"value": 277, "updated_date":"2015-11-12T00:00:00+01:00" }, { ... 24 valeurs ... }],
},
{
"start_date": "2016-01-12T00:00:00+01:00",
"end_date": "2016-01-12T11:12:09+01:00",
"production_type": "FOSSIL_GAS",
"values": [{ "start_date": "2015-11-12T00:00:00+01:00", "end_date": "2015-11-12T00:30:00+01:00",
"value": 277, "updated_date":"2015-11-12T00:00:00+01:00" }, { ... 24 valeurs ... }],
},
{...}
] }
11
Version 1.0
4.1.1.4 Règles de gestion
Règle de gestion en fonction des paramètres d’entrée :
Paramètre en entrée
Description
Numéro
vide
Si aucun paramètre d’entrée n’est renseigné, le Service
retourne la production réalisée par filière de la journée.
AGPPT-RG01
renseigné
Si les paramètres start_date et end_date sont passés, le
Service retourne la production réalisée par filière sur la
période demandée.
AGPPT-RG02
start_date
end_date
vide
renseigné
Règles de gestion appliquées en sortie :
Numéro
AGPPT-RG03
AGPPT-RG04
AGPPT-RG05
Description
Les données de sortie sont triées par date de début (start_date) puis par filière
(production_type) triée par ordre alphabétique.
Il n’y a pas de gestion de changement d’heure. Le Service retourne tout le temps 24
valeurs, une valeur par heure.
En sortie du Service les productions réalisées par filière sont retournées à la maille
jour calendaire.
12
Version 1.0
4.1.1.5 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
Fonctionnelle
ACTUALGEN_PRODTYPE_F01
§5.1.1
Fonctionnelle
§5.1.1
Fonctionnelle
§5.1.1
Fonctionnelle
§5.1.1
Fonctionnelle
§5.1.1
Fonctionnelle
Technique
§5.1.1
404
§5.2
Technique
408
§5.2
Technique
413
§5.2
Technique
414
§5.2
Technique
429
§5.2
Technique
500
§5.2
Technique
503
§5.2
Technique
509
§5.2
13
Détails
4.2
Version 1.0
Ressource /actual_generations_per_unit
4.2.1 GET /actual_generations_per_unit
Exposition
REST / JSON
Méthode
GET
https://digital.iservices.rtefrance.com/open_api/actual_generation/v1/actual_generations_per_unit?start_date=<
valeur>&end_date=<valeur>&unit_eic_code=<valeur>
https://digital.iservices.rtefrance.com/open_api/actual_generation/v1/sandbox/actual_generations_per_unit
URL ressource
URL sandbox
(1)
(1)
Cette ressource a pour objectif de permettre de récupérer la production infrajournalière réalisée
agrégée par groupe. Dans le cas d’utilisation nominal il n’est pas nécessaire de renseigner les champs
de la période. Le service retourne automatiquement le réalisé de la journée en cours Cf. AGPU-RG01.
ne sont pas disponibles.
Il est conseillé de faire un appel par heure à ce service et de ne pas dépasser une période de 7 jours
par appel.
14
Version 1.0
4.2.1.2 Entrées
NOM
start_date
1
CARD.
0..1
DESCRIPTION
TYPE
Date de début de
recherche
VALEURS / FORMAT
date
AGPU-RG01
AGPU-RG02
AGPU-RG04
AGPU-RG01
AGPU-RG02
AGPU-RG04
end_date
0..1
date
unit_eic_code
0..1
Code EIC de l’unité de
production
string
Exemple :
Sans paramètre
URL:
GET /open_api/actual_generation/v1/actual_generations_per_unit
HTTP/1.1 200 OK
Headers:
Body:
URL:
GET /open_api/actual_generation/v1/actual_generations_per_unit?start_date=2015-0608T00:00:00%2B02:00&end_date=2015-06-11T00:00:00%2B02:00
HTTP/1.1 200 OK
Headers:
Body:
15
REGLES
AGPU-RG03
AGPU-RG04
Version 1.0
4.2.1.3 Sorties
NOM
1..1
CARD.
DESCRIPTION
Tableau de valeurs {JSON} contenant 1 occurrence par valeur unit retournée.
Sa structure est la suivante :
DESCRIPTION
TYPE
VALEURS / FORMAT
REGLES
start_date
1..1
date
AGPU-RG05
AGPU-RG06
end_date
1..1
date
AGPU-RG05
unit
1..1
Une valeur par intervalle de temps. Tableau de valeurs {JSON} structuré comme suit :
VALEURS /
NOM CARD.
DESCRIPTION
TYPE
REGLES
FORMAT
1..1
actual_generations_
per_unit
NOM
CARD.
eic_c
ode
1..1
NOM
AGPU-RG06
1..1
CARD.
DESCRIPTION
TYPE
start_da
te
1..1
Intervalle de
temps début
date
end_dat
e
1..1
Intervalle de
temps fin
date
updated
_date
1..1
Date de mise à
jour de la donnée
date
producti
on_type
1..1
Filière de
production
enum
0..n
0..n
Code EIC de l’unité
string
de production
Nom de l’unité de
string
production
name
values
1..1
16
–
AGPU-RG07
VALEURS /
FORMAT
YYYY-MMDDThh:mm:sszzzz
zz1
zz1
zz1
Une des valeurs
suivantes :
BIOMASS
FOSSIL_BROWN_C
OAL_LIGNITE
FOSSIL_COAL_DE
RIVED_GAS
FOSSIL_GAS
FOSSIL_HARD_CO
AL
FOSSIL_OIL
FOSSIL_OIL_SHAL
E
FOSSIL_PEAT
GEOTHERMAL
HYDRO_PUMPED_
STORAGE
HYDRO_RUN_OF_
RIVER_AND_POUN
DAGE
HYDRO_WATER_R
ESERVOIR
MARINE
NUCLEAR
REGLES
_
_
_
_
Version 1.0
OTHER_RENEWAB
LE
SOLAR
WASTE
WIND_OFFSHORE
WIND_ONSHORE
OTHER
value
1
1..1
Valeur de la
donnée
int
Entier numérique
_
Les dates en retour sont exprimées en heure française (UTC + 2 heures en été, UTC 1 heure en hiver)
17
Version 1.0
GET /open_api/actual_generation/v1/actual_generations_per_unit
HTTP/1.1 200 OK
{"actual_generations_per_unit": [{
"start_date": "2016-01-14T00:00:00+01:00",
"end_date": "2016-01-14T15:11:54+01:00",
"unit": {
"eic_code": "17W100P100P00016",
"name": "Pont-sur-Sambre"
},
"values": [{
"start_date": "2016-01-14T00:00:00+01:00",
"end_date": "2016-01-14T00:30:00+01:00",
"updated_date": "2016-01-14T00:00:00+01:00",
"value": -2
}, {...}]
},
{...}
]}
Description
start_date end_date unit_eic_code
vide
vide
renseigné renseigné
vide
vide
renseigné renseigné
vide
vide
renseigné
renseigné
Si aucun paramètre d’entrée n’est
renseigné, le Service retourne la
production réalisée par groupe de la
journée.
Si les paramètres start_date et
end_date sont passés, le Service
retourne la production réalisée par groupe
sur la période demandée.
Si le champ unit_eic_code est renseigné,
le service ne retourne que la production
réalisé par groupe du groupe selectionné.
Il n’est pas possible de renseigner
plusieurs groupes
Il est possible de passer au Service les 3
paramètres pour obtenir des données
ciblées.
18
Numéro
AGPURG01
AGPURG02
AGPURG03
AGPURG04
Version 1.0
Numéro
AGPU-RG05
AGPU-RG06
AGPU-RG07
Description
En sortie du Service les productions réalisées par groupe sont retournées à la maille
jour calendaire.
Les données de sortie sont triées par date de début (start_date) puis par code de
groupe (eic_code) trié par ordre alphabétique.
Il n’y a pas de gestion de changement d’heure. Le Service retourne tout le temps 24
valeurs, une valeur par heure.
19
Version 1.0
Type d’erreur
Code erreur
Détails
Fonctionnelle
ACTUALGEN_PERUNIT_F01
§5.1.2
Fonctionnelle
§5.1.2
Fonctionnelle
§5.1.2
Fonctionnelle
§5.1.2
Fonctionnelle
§5.1.2
Fonctionnelle
Technique
§5.1.2
404
§5.2
Technique
408
§5.2
Technique
413
§5.2
Technique
414
§5.2
Technique
429
§5.2
Technique
500
§5.2
Technique
503
§5.2
Technique
509
§5.2
20
4.3
Version 1.0
Ressource /water_reserves
4.3.1 GET /water_reserves
Exposition
REST / JSON
Méthode
GET
https://digital.iservices.rtefrance.com/open_api/actual_generation/v1/water_reserves?start_date=<valeur>&end
_date=<valeur>
https://digital.iservices.rtefrance.com/open_api/actual_generation/v1/sandbox/water_reserves/
URL ressource
URL sandbox
(1)
(1)
Cette ressource a pour objectif de permettre de récupérer le stock hydraulique par semaine. Dans le
cas d’utilisation nominal il n’est pas nécessaire de renseigner les champs de la période. Le service
retourne automatiquement le réalisé de la dernière semaine Cf. WARE-RG01.
sont disponibles uniquement sous forme de fichiers d'archives.
Il est conseillé de faire un appel par semaine à ce service, le mercredi à 13h00, et de ne pas dépasser
une période de 366 jours par appel.
21
Version 1.0
4.3.1.2 Entrées
1
NOM
CARD.
start_date
0..1
end_date
0..1
DESCRIPTION
TYPE
Date
de
début
de
date
recherche des prévisions
date
des prévisions
VALEURS / FORMAT
Exemples d’appel :
Sans paramètre
URL:
GET /open_api/actual_generation/v1/water_reserves
HTTP/1.1
Headers:
Body:
URL:
GET /open_api/actual_generation/v1/water_reserves?start_date=2015-0608T00:00:00%2B02:00&end_date=2015-06-11T00:00:00%2B02:00
HTTP/1.1
Headers:
Body:
22
REGLES
WARE-RG01
WARE-RG02
WARE-RG01
WARE-RG02
Version 1.0
4.3.1.3 Sorties
NOM
CARD.
water_reserve
s
1..1
DESCRIPTION
Tableau de valeurs {JSON} contenant 1 occurrence pour la période définie.
Sa structure est la suivante :
NOM
CARD.
DESCRIPTION
start_dat
e
1..1
date
YYYY-MM-DDThh:mm:sszzzzzz1 WARE-RG04
end_date
1..1
date
YYYY-MM-DDThh:mm:sszzzzzz1 WARE-RG04
values
1..1
0..n
0..n
NOM
1
TYPE
CARD.
VALEURS / FORMAT
DESCRIPTION
TYPE
start_date
1..1
Intervalle de temps début
date
end_date
1..1
Intervalle de temps fin
date
updated_da
te
1..1
Date de mise à jour de la
donnée
date
value
1..1
Valeur de la donnée
int
VALEURS /
FORMAT
YYYY-MMDDThh:mm:
sszzzzzz1
YYYY-MMDDThh:mm:
sszzzzzz1
YYYY-MMDDThh:mm:
sszzzzzz1
Entier
numérique
REGLES
REGLES
WARE-RG03
WARE-RG03
WARE-RG03
–
Les dates en retour sont exprimées en heure française (UTC + 2 heures en été, UTC 1 heure en hiver)
GET /open_api/actual_generation/v1/water_reserves
HTTP/1.1 200 OK
{"water_reserves":[
{
"start_date":"2016-01-12T00:00:00+01:00",
"end_date":"2016-01-12T14:13:32+01:00",
"values":[{"start_date":"2016-01-04T00:00:00+01:00","end_date":"2016-0110T00:00:00+01:00","value":1978425,"updated_date":"2016-01-04T00:00:00+01:00"}]
}
]}
23
Version 1.0
start_date
end_date
vide
vide
renseigné
renseigné
Description
Si aucun paramètre d’entrée n’est renseigné, le Service
retourne le stock hydraulique de la semaine
précédente.
Si les paramètres start_date et end_date sont
passés, le Service retourne le stock hydraulique sur la
période demandée.
Numéro
WARE-RG01
WARE-RG02
Numéro
Description
Les données de sortie sont triées par date de début (values/start_date) puis par
WARE-RG03
date de mise à jour (values/updated_date) de la plus récente à la plus ancienne.
WARE-RG04 En sortie du Service le stock hydraulique est retourné à la maille semaine calendaire
24
Version 1.0
Type d’erreur
Code erreur
Détails
Fonctionnelle
ACTUALGEN_WATERRESERVES_F01
§5.1.3
Fonctionnelle
§5.1.3
Fonctionnelle
§5.1.3
Fonctionnelle
§5.1.3
Fonctionnelle
§5.1.3
Fonctionnelle
Technique
§5.1.3
404
§5.2
Technique
408
§5.2
Technique
413
§5.2
Technique
414
§5.2
Technique
429
§5.2
Technique
500
§5.2
Technique
503
§5.2
Technique
509
§5.2
25
5
Version 1.0
Détails des erreurs
Le shé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 ».
26
Version 1.0
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.
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
27
5.1
Version 1.0
Erreurs fonctionnelles
5.1.1 actual_generations_per_production_type
Ce tableau récapitule les erreurs fonctionnelles retournées par la ressource correspondant à une erreur
dans la requête (code http 400) :
RG
Cette erreur est générée si les paramètres start_date et end_date sont passés l’un
sans l’autre.
Message
If one of the fields "start_date" or "end_date" is used, the two fields are mandatory.
Please used either fields or neither.
Exemple
d'appel
GET
openapi/actual_generation/v1/actual_generations_per_production_type?start_date=201506-01T00:00:00%2B02:00
RG
Cette erreur est générée si le paramètre start_date est plus récent que le paramètre
end_date.
Message
The field "start_date" in the API input is more recently than the field "end_date". Please
correct the values of these fields
Exemple
d'appel
RG
Message
Exemple
d'appel
RG
Message
Exemple
d'appel
RG
Message
Exemple
d'appel
GET
openapi/actual_generation/v1/actual_generations_per_production_type?start_date=201506-02T00:00:00%2B02:00&end_date=2015-06-01T00:00:00%2B02:00
Cette erreur est générée si la période demandée est supérieure à 155 jours.
The API does not provide feedback on such a long period in one call. To retrieve all the
data please make it with severals calls to the API.
GET
openapi/actual_generation/v1/actual_generations_per_production_type?start_date=201506-01T00:00:00%2B02:00&end_date=2016-07-02T00:00:00%2B02:00
Cette erreur est générée si end_date est supérieur à J+2 par rapport à la date système,
le Service génère cette erreur.
The value of "end_date" field is incorrect. It is not possible to recover data to this term.
GET
open_api/actual_generation/v1/actual_generations_per_production_type?start_date=
2015-10-31T00:00:00%2B02:00&end_date=2015-11-09T00:00:00%2B02:00 pour un
appel le 30/10/2015
Cette erreur est générée si l’intervalle de temps entre start_date et end_date est
inférieur 1 jour calendaire.
The period filled by fields "start_date" and "end_date" is too short to return values.
Please check the user guide to verify the minimum period for this API.
GET
2015-06-01T00:00:00%2B02:00&end_date=2015-06-01T12:00:00%2B02:00
RG
Cette erreur est générée si au moins un des paramètres start_date ou end_date n’a
pas le format attendu
Message
One of the dates in the API input does not follow the format described in the user guide.
Please verify compliance with the format for each field.
28
Exemple
d'appel
Version 1.0
GET
2015-06-01&end_date=2015-06-01
5.1.2 actual_generations_per_unit
RG
Cette erreur est générée si les paramètres start_date et end_date sont passés l’un sans
l’autre.
Message
If one of the fields "start_date" or "end_date" is used, the two fields are mandatory. Please
used either fields or neither.
Exemple GET
open_api/actual_generation/v1/actual_generations_per_unit?start_date=2015-06d'appel 01T00:00:00%2B02:00
RG
end_date.
Message
Exemple GET
open_api/actual_generation/v1/actual_generations_per_unit?start_date=2015-06d'appel 02T00:00:00%2B02:00&end_date=2015-06-01T00:00:00%2B02:00
RG
The API does not provide feedback on such a long period in one call. To retrieve all the data
Message
please make it with severals calls to the API.
Exemple GET
RG
Cette erreur est générée si end_date est supérieur à J+1 par rapport à la date système.
Message The value of "end_date" field is incorrect. It is not possible to recover data to this term.
GET
open_api/actual_generation/v1/actual_generations_per_unit?start_date=2015-10Exemple
31T00:00:00%2B02:00&end_date=2015-11-09T00:00:00%2B02:00 Pour un appel le
d'appel
30/10/2015
Cette erreur est générée si l’intervalle de temps entre start_date et end_date est inférieur
RG
1 jour calendaire.
The period filled by fields "start_date" and "end_date" is too short to return values. Please
Message
check the user guide to verify the minimum period for this API.
Exemple GET
RG
Cette erreur est générée si au moins un des paramètres start_date ou end_date n’a pas
le format attendu
Message
29
Version 1.0
Exemple GET
open_api/actual_generation/v1/actual_generations_per_unit?start_date=2015-06d'appel 01&end_date=2015-06-01
5.1.3 water_reserves
RG
Cette erreur est générée si les paramètres start_date et end_date sont passés l’un sans
l’autre.
Message
If one of the fields "start_date" or "end_date" is used, the two fields are mandatory. Please
used either fields or neither.
Exemple GET
open_api/actual_generation/v1/water_reserves?start_date=2015-06d'appel 01T00:00:00%2B02:00
RG
end_date.
Message
Exemple GET
open_api/actual_generation/v1/water_reserves?start_date=2015-06d'appel 02T00:00:00%2B02:00&end_date=2015-06-01T00:00:00%2B02:00
RG
The API does not provide feedback on such a long period in one call. To retrieve all the data
Message
please make it with severals calls to the API.
Exemple GET open_api/actual_generation/v1/water_reserves?start_date=2015-06d'appel 01T00:00:00%2B02:00&end_date=2015-07-02T00:00:00%2B02:00
RG
Cette erreur est générée si end_date est supérieur à J+7 par rapport à la date système.
Message The value of "end_date" field is incorrect. It is not possible to recover data to this term.
GET
open_api/actual_generation/v1/water_reserves?start_date=2015-10Exemple
31T00:00:00%2B02:00&end_date=2015-11-09T00:00:00%2B02:00 Pour un appel le
d'appel
30/10/2015
Cette erreur est générée si l’intervalle de temps entre start_date et end_date est inférieur
RG
1 jour calendaire.
The period filled by fields "start_date" and "end_date" is too short to return values. Please
Message
check the user guide to verify the minimum period for this API.
Exemple GET
open_api/actual_generation/v1/water_reserves?start_date=2015-06d'appel 01T00:00:00%2B02:00&end_date=2015-06-01T12:00:00%2B02:00
RG
Cette erreur est générée si au moins un des paramètres start_date ou end_date n’a pas
le format attendu
Message
Exemple GET
open_api/actual_generation/v1/water_reserves?start_date=2015-06d'appel 01&end_date=2015-06-01
30
5.2
Version 1.0
Erreurs techniques
404
Code http 404
Message
Not Found
Exemple
d'appel
La ressource appelé n’existe pas ou aucune donnée n’a été trouvée
408
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
31
Exemple
d'appel
Version 1.0
Erreur générée sur maintenance (http 503).
509
Code http 509
Message
Bandwidth Limit Exceeded.
Exemple
d'appel
L‘ensemble des requêtes des clients atteint la limite maximale.
6 Annexes
6.1
Exemples d’appels ressource « actual_generations_per_production_type »
6.1.1 Cas sans paramètre – AGPPT-RG01
GET
/open_api/actual_generation/v1/actual_generations_per_production_type
La réponse JSON est décrite dans le fichier actual_generations_per_production_typeEC09-RG01.v1.0.1.json
inclus au fichier zip intitulé « zip_agppt » fourni en annexe.
6.1.2 Cas avec paramètres dates – AGPPT-RG02
GET
/open_api/actual_generation/v1/actual_generations_per_production_type?start_date=2015-06-
08T00:00:00%2B02:00&end_date=2015-06-11T00:00:00%2B02:00
La réponse JSON est décrite dans le fichier actual_generations_per_production_typeEC09-RG02.v1.0.1.json inclus au
en annexe.
6.1.3 Cas à la maille jour calendaire – AGPPT-RG05
GET
/open_api/actual_generation/v1/actual_generations_per_production_type?start_date=2015-06-
01T12:00:00%2B02:00&end_date=2015-06-03T12:00:00%2B02:00
La réponse JSON est décrite dans le fichier
actual_generations_per_production_typeEC09-RG05.v1.0.1.json inclus au fichier zip
intitulé « zip_agppt » fourni en annexe.
6.2
Exemples d’appels ressource « actual_generations_per_unit »
6.2.1 Cas sans paramètre – AGPU-RG01
GET
/open_api/actual_generation/v1/actual_generations_per_unit
La réponse JSON est décrite dans le fichier actual_generations_per_unitEC10-RG01.v1.0.1.json
inclus au fichier zip intitulé « zip_agpu » fourni en annexe.
32
Version 1.0
6.2.2 Cas avec paramètre dates – AGPU-RG02
GET
/open_api/actual_generation/v1/actual_generations_per_unit?start_date=2015-06-
08T00:00:00%2B02:00&end_date=2015-06-11T00:00:00%2B02:00
6.2.3 Cas à la maille jour calendaire – AGPU-RG05
GET
/open_api/actual_generation/v1/actual_generations_per_unit?start_date=2015-06-
01T12:00:00%2B02:00&end_date=2015-06-03T12:00:00%2B02:00
6.3
Exemples d’appels ressource « water_reserves »
6.3.1 Cas sans paramètre – WARE-RG01
GET
/open_api/actual_generation/v1/water_reserves
La réponse JSON est décrite dans le fichier water_reservesEC11-RG01.v1.0.1.json inclus au fichier
zip intitulé « zip_wr » fourni en annexe.
6.3.2 Cas avec paramètre type – WARE-RG02
GET
/open_api/actual_generation/v1/water_reserves?start_date=2015-06-
08T00:00:00%2B02:00&end_date=2015-06-15T00:00:00%2B02:00
6.3.3 Cas à la maille jour calendaire – WARE-RG04
GET
/open_api/actual_generation/v1/water_reserves?start_date=2015-06-
01T12:00:00%2B02:00&end_date=2015-06-25T12:00:00%2B02:00
FIN DU DOCUMENT
33

Guide d`utilisation-API - API Data RTE

Transcription

Documents pareils

ESP-2006 Literatura española actual

Lire l`intégralité de l`article

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

LECON ORTHOGRAPHE 1 L`alphabet phonetique

Hydrangea • Hortensia

Devenir formateur - tuteur pour accompagner les

Ergos rejoint ACTUAL

Circuit d`Ailleville

Arrache agrafes, Maped 12725 te-agrafes Start - webus.liefert