Skip to content
Snippets Groups Projects
Commit 5b3f8a76 authored by Bastien DUMONT's avatar Bastien DUMONT :angel:
Browse files

fix : several links

parent f5fc2264
Branches
No related tags found
1 merge request!9fix : several links
Hide whitespace changes
Inline Side-by-side
docs/konnectors/egl.md
+ 124
− 125
View file @ 5b3f8a76
## EGL Konnector
This konnector fetches consumptions measures from EGL API.
The EGL API allows us to get a user's consumption data gathered by it's connected water meter "Téléo".
You can clone the project [here](https://forge.grandlyon.com/web-et-numerique/llle_project/egl-konnector).
You should also check Cozy's official documentations for konnectors :
[https://docs.cozy.io/en/tutorials/konnector/getting-started/](https://docs.cozy.io/en/tutorials/konnector/getting-started/)
API Url for Development : [https://agence-rec.eaudugrandlyon.com](https://agence-rec.eaudugrandlyon.com/)
API Url for Production : [https://agence.eaudugrandlyon.com/ws](https://agence.eaudugrandlyon.com/ws)
## Authentication
In order to authenticate to the EGL API we have to request the following route
Method : **POST**
Authentication Route : **/connect.asp**
```json
"headers":
{
{
"AuthKey": <your-auth-key>,
"Content-Type": "application/x-www-form-urlencoded"
}
}
```
```json
"body":
{
"mode": "formdata"
{
"login": <your-login>,
"pass": <your-password>
}
}
```
Once you've sent this request the API should answer with a code 100 if everything is ok and provides you a valid **token** and **num_abt** that you will use later in order to get data.
```json
{
"codeRetour": 100,
"libelleRetour": "Connecté",
"resultatRetour": {
"num_abt": toto,
"list_num_abt": [toto, tata]
"token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
}
```
## Fetch Data
In order to get data from the EGL API we have to request the following route :
Method : **POST**
Data Route : **/getAllAgregatsByAbonnement.aspx**
```json
"body":
{
"mode": "formdata"
{
"token": "897555754A703055397897456568776E32704C3953514F5R",
"num_abt": 1895683,
"date_debut": MM/JJ/YYYY,
"date_fin": MM/JJ/YYYY
}
}
```
The dates must be valid dates otherwise you'll get an error
The answer will provide you an array of data day by day with the value got by the water meter 'ValeurIndex' at this moment.
```json
{
"codeRetour": 100,
"libelleRetour": "L'opération a réussi",
"resultatRetour": [
{
"DateReleve": "2020-07-01T00:00:00+02:00",
"TypeAgregat": "R",
"ValeurIndex": 562362
},
{
"DateReleve": "2020-07-02T00:00:00+02:00",
"TypeAgregat": "R",
"ValeurIndex": 562432
}
]
}
```
Daily data is calculated by substracting current valeurIndex day with previous day.
### TypeAgregats
- "R" means the real value
- "A" means an anomaly
- "D" means a water meter changing
- "V" means data has been estimated on a period
- "X" marks the start and end of "V" estimated data
- "T" means pending data
If you're looking for more information about the API, checkout the [complete API documentation](/documents/egl-api-doc.pdf)
### Konnector Methods
| Method | Description |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start | Init Function |
| getData | Retrieve data from API |
| processData | Parse data. Remove existing data from DB using hydrateAndFilter, store filtered data and return the list of filtered data |
| authenticate | Authentication method. Requires login, password, baseUrl and ApiAuthKey. |
| storeData | Save data in the right doctype db and prevent duplicated keys |
| format | Format data for DB storage and remove bad data (former "T" typeagregats remain in response even if the data was added later, leading to duplicated data) |
| resetInProgressAggregatedData | Function handling special case.The temporary aggregated data need to be remove in order for the most recent one te be saved. Ex for com.grandlyon.egl.year : `{ load: 76.712, year: 2020, ... }` need to be replace by `{ load: 82.212, year: 2020, ... }` after egl data reprocess |
## EGL Konnector
This konnector fetches consumptions measures from EGL API.
The EGL API allows us to get a user's consumption data gathered by it's connected water meter "Téléo".
You can clone the project [here](https://forge.grandlyon.com/web-et-numerique/llle_project/egl-konnector).
You should also check Cozy's official documentations for konnectors :
[https://docs.cozy.io/en/tutorials/konnector/getting-started/](https://docs.cozy.io/en/tutorials/konnector/getting-started/)
- API Url for Development : [https://agence-rec.eaudugrandlyon.com](https://agence-rec.eaudugrandlyon.com/)
- API Url for Production : [https://agence.eaudugrandlyon.com/ws](https://agence.eaudugrandlyon.com/ws)
## Authentication
In order to authenticate to the EGL API we have to request the following route
Method : **POST**
Authentication Route : **/connect.asp**
```json
"headers":
{
{
"AuthKey": <your-auth-key>,
"Content-Type": "application/x-www-form-urlencoded"
}
}
```
```json
"body":
{
"mode": "formdata"
{
"login": <your-login>,
"pass": <your-password>
}
}
```
Once you've sent this request the API should answer with a code 100 if everything is ok and provides you a valid **token** and **num_abt** that you will use later in order to get data.
```json
{
"codeRetour": 100,
"libelleRetour": "Connecté",
"resultatRetour": {
"num_abt": toto,
"list_num_abt": [toto, tata]
"token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
}
```
## Fetch Data
In order to get data from the EGL API we have to request the following route :
Method : **POST**
Data Route : **/getAllAgregatsByAbonnement.aspx**
```json
"body":
{
"mode": "formdata"
{
"token": "897555754A703055397897456568776E32704C3953514F5R",
"num_abt": 1895683,
"date_debut": MM/JJ/YYYY,
"date_fin": MM/JJ/YYYY
}
}
```
The dates must be valid dates otherwise you'll get an error
The answer will provide you an array of data day by day with the value got by the water meter 'ValeurIndex' at this moment.
```json
{
"codeRetour": 100,
"libelleRetour": "L'opération a réussi",
"resultatRetour": [
{
"DateReleve": "2020-07-01T00:00:00+02:00",
"TypeAgregat": "R",
"ValeurIndex": 562362
},
{
"DateReleve": "2020-07-02T00:00:00+02:00",
"TypeAgregat": "R",
"ValeurIndex": 562432
}
]
}
```
Daily data is calculated by substracting current valeurIndex day with previous day.
### TypeAgregats
- "R" means the real value
- "A" means an anomaly
- "D" means a water meter changing
- "V" means data has been estimated on a period
- "X" marks the start and end of "V" estimated data
- "T" means pending data
If you're looking for more information about the API, checkout the [complete API documentation](/documents/egl-api-doc.pdf)
### Konnector Methods
| Method | Description |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start | Init Function |
| getData | Retrieve data from API |
| processData | Parse data. Remove existing data from DB using hydrateAndFilter, store filtered data and return the list of filtered data |
| authenticate | Authentication method. Requires login, password, baseUrl and ApiAuthKey. |
| storeData | Save data in the right doctype db and prevent duplicated keys |
| format | Format data for DB storage and remove bad data (former "T" typeagregats remain in response even if the data was added later, leading to duplicated data) |
| resetInProgressAggregatedData | Function handling special case.The temporary aggregated data need to be remove in order for the most recent one te be saved. Ex for com.grandlyon.egl.year : `{ load: 76.712, year: 2020, ... }` need to be replace by `{ load: 82.212, year: 2020, ... }` after egl data reprocess |
docs/konnectors/enedis.md
+ 4
− 4
View file @ 5b3f8a76
......@@ -7,12 +7,12 @@ You should also check Cozy's official documentations for konnectors :
## Enedis Konnector
The Oauth protocol does not take place in the konnector code, therefore it is also important to take a look at the [proxy](/proxy/description.md) documentation to fully understand all the interactions that will be told below.
The Oauth protocol does not take place in the konnector code, therefore it is also important to take a look at the [proxy](/proxy/description/) documentation to fully understand all the interactions that will be told below.
All the actions performed by the stack are targetted from pre-registered paramaters, here is the list of all parameters needed by the stack to perform the Oauth protocol and allow the konnector to fetch data.
On its first launch, following the Oauth Client Connect authentification.
- The cozy stack calls the **authentification_endpoint** and start the oauth protocol, see [proxy doc](/proxy/description.md).
- The cozy stack calls the **authentification_endpoint** and start the oauth protocol, see [proxy doc](/proxy/description/).
- The account has now an access_token and an id_token from the oauth call
!!! info ""
......@@ -24,8 +24,8 @@ This token holds several meta datas, including the usage_point_id (id of user's
## Enedis API
API Url for Production : [https://gw.prd.api.enedis.fr](https://gw.prd.api.enedis.fr)
API url for Development : [https://gw.hml.api.enedis.fr](https://gw.hml.api.enedis.fr)
- API Url for Production : [https://gw.prd.api.enedis.fr](https://gw.prd.api.enedis.fr)
- API url for Development : [https://gw.hml.api.enedis.fr](https://gw.hml.api.enedis.fr)
Once you've finished the OAuth protocol and have a valid token, you can go fetch the data. Currently we use the two following endpoints in Ecolyo:
......
docs/konnectors/grdf.md
+ 2
− 2
View file @ 5b3f8a76
......@@ -7,7 +7,7 @@ You should also check Cozy's official documentations for konnectors :
## Grdf Adict Konnector
The Oauth protocol does not take place in the konnector code, therefore it is also important to take a look at the [proxy](/proxy/description.md) documentation to fully understand all the interactions that will be told below.
The Oauth protocol does not take place in the konnector code, therefore it is also important to take a look at the [proxy](/proxy/description/) documentation to fully understand all the interactions that will be told below.
All the actions performed by the stack are targetted from pre-registered paramaters, here is the list of all parameters needed by the stack to perform the Oauth protocol and allow the konnector to fetch data.
......@@ -15,7 +15,7 @@ All the actions performed by the stack are targetted from pre-registered paramat
On its first launch, following the Oauth Client Connect authentification.
- The cozy stack calls the **authentification_endpoint** and start the oauth protocol, see [proxy doc](/proxy/description.md).
- The cozy stack calls the **authentification_endpoint** and start the oauth protocol, see [proxy doc](/proxy/description).
- The account has now an access_token and an id_token from the oauth call
!!! info ""
......
docs/proxy/description.md
+ 1
− 1
View file @ 5b3f8a76
This section of documentation refers to the Oauth protocols working hand in hand with our custom proxy and the cozy-stack.
To fully understand its whereabouts, you should also look at the [enedis konnector](/konnectors/enedis.md) and [grdf konnector](/konnectors/grdf.md) documentation.
To fully understand its whereabouts, you should also look at the [enedis konnector](/konnectors/enedis/) and [grdf konnector](/konnectors/grdf/) documentation.
!!! info "proxy code source"
Feel free to check the proxy [code](https://forge.grandlyon.com/pocs/cozy/cozy-oauth-proxy) at all time when reading this documentation.
......
docs/proxy/use_cases/enedis.md
+ 103
− 103
View file @ 5b3f8a76
### Enedis Data Connect
!!! info "enedis documentation"
Create an account on https://datahub-enedis.fr/ to explore all the services exposed by Enedis.
[Authorize API](https://datahub-enedis.fr/data-connect/documentation/authorize-v1/) swagger.
[Api healthcheck](https://datahub-enedis.fr/data-connect/ressources/etat-des-services/).
Regarding Enedis, two endpoints are exposed:
#### Authorize
##### /dataconnect/v1/oauth2/authorize
<table>
<colgroup>
<col width="30%">
<col width="70%">
</colgroup>
<thead>
<tr class="header">
<th>Paramater</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>client_id</td>
<td>Unique identifier of the Application</td>
</tr>
<tr>
<td>response_type</td>
<td>Authorization scenario requested. It will always be "code" as Enedis implemented a code grant authorization</td>
</tr>
<tr>
<td>state</td>
<td>Security parameter allowing to maintain the state between the request and the redirection. ** Maximum length of 100 characters ! **</td>
</tr>
<tr>
<td>duration</td>
<td>Duration of the consent requested by the application, ISO 8601 format. It cannot exceed 3 years</td>
</tr>
</tbody>
</table>
!!! important "Important"
The response targets the redirect-uri registered with Enedis (the redirect-uri is our proxy and the response will be explained in details further below when explaining the proxy endpoints mechanics).
#### Token
##### /v1/oauth2/token
<table>
<colgroup>
<col width="30%">
<col width="70%">
</colgroup>
<thead>
<tr class="header">
<th>Paramater</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>redirect_uri</td>
<td>URI defined when the application was created. Must be secured in https</td>
</tr>
<tr>
<td>content-type</td>
<td>application/json</td>
</tr>
<tr>
<td>grant_type</td>
<td>Authorization type to get an access token. This must be set to “authorization_code” when using an authorization code, and to “refresh_token” when using a refresh token</td>
</tr>
<tr>
<td>client_id</td>
<td>Unique identifier of the Application</td>
</tr>
<tr>
<td>client_secret</td>
<td>Secret of the client application, associated with its client_id</td>
</tr>
<tr>
<td>refresh_token</td>
<td>Refresh token returned to the previous POST request to the /token endpoint</td>
</tr>
<tr>
<td>code</td>
<td>Authorization code returned to the GET request of /authorize endpoint</td>
</tr>
</tbody>
</table>
On success, response will contain **access_token** or **refresh_token**, **usage_point_id** among other things. All informations will be stored by the cozy-stack in a cozy-accounts database.
#### Consent Handling
Consent is replaced everytime a new oauth dance is launched (for 6 months, hardcoded in **/authorize** request).
User can revoke its consent from the Enedis website, no external endpoints are available for this purpose.
If a consent has been revoked or expired. A 403 error will be thrown saying: *No consent can be found for this customer and this usage point*.
### Enedis Data Connect
!!! info "enedis documentation"
Create an account on [https://datahub-enedis.fr/](https://datahub-enedis.fr/) to explore all the services exposed by Enedis.
[Authorize API](https://datahub-enedis.fr/data-connect/documentation/authorize-v1/) swagger.
[Api healthcheck](https://datahub-enedis.fr/data-connect/ressources/etat-des-services/).
Regarding Enedis, two endpoints are exposed:
#### Authorize
##### /dataconnect/v1/oauth2/authorize
<table>
<colgroup>
<col width="30%">
<col width="70%">
</colgroup>
<thead>
<tr class="header">
<th>Paramater</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>client_id</td>
<td>Unique identifier of the Application</td>
</tr>
<tr>
<td>response_type</td>
<td>Authorization scenario requested. It will always be "code" as Enedis implemented a code grant authorization</td>
</tr>
<tr>
<td>state</td>
<td>Security parameter allowing to maintain the state between the request and the redirection. ** Maximum length of 100 characters ! **</td>
</tr>
<tr>
<td>duration</td>
<td>Duration of the consent requested by the application, ISO 8601 format. It cannot exceed 3 years</td>
</tr>
</tbody>
</table>
!!! important "Important"
The response targets the redirect-uri registered with Enedis (the redirect-uri is our proxy and the response will be explained in details further below when explaining the proxy endpoints mechanics).
#### Token
##### /v1/oauth2/token
<table>
<colgroup>
<col width="30%">
<col width="70%">
</colgroup>
<thead>
<tr class="header">
<th>Paramater</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>redirect_uri</td>
<td>URI defined when the application was created. Must be secured in https</td>
</tr>
<tr>
<td>content-type</td>
<td>application/json</td>
</tr>
<tr>
<td>grant_type</td>
<td>Authorization type to get an access token. This must be set to “authorization_code” when using an authorization code, and to “refresh_token” when using a refresh token</td>
</tr>
<tr>
<td>client_id</td>
<td>Unique identifier of the Application</td>
</tr>
<tr>
<td>client_secret</td>
<td>Secret of the client application, associated with its client_id</td>
</tr>
<tr>
<td>refresh_token</td>
<td>Refresh token returned to the previous POST request to the /token endpoint</td>
</tr>
<tr>
<td>code</td>
<td>Authorization code returned to the GET request of /authorize endpoint</td>
</tr>
</tbody>
</table>
On success, response will contain **access_token** or **refresh_token**, **usage_point_id** among other things. All informations will be stored by the cozy-stack in a cozy-accounts database.
#### Consent Handling
Consent is replaced everytime a new oauth dance is launched (for 6 months, hardcoded in **/authorize** request).
User can revoke its consent from the Enedis website, no external endpoints are available for this purpose.
If a consent has been revoked or expired. A 403 error will be thrown saying: *No consent can be found for this customer and this usage point*.
Ecolyo can warn the user that the service is unable to continue and ask to give new consent.
\ No newline at end of file
docs/proxy/use_cases/grdfadict.md
+ 33
− 33
View file @ 5b3f8a76
### Grdf Adict
!!! info "grdf documentation"
Visit https://site.grdf.fr/web/grdf-adict/technique to explore all the services exposed by Grdf.
> Prod endpoints are: https://sofit-sso-oidc.grdf.fr/openam/
Regarding Grdf Adict Oauth connexion, two endpoints are exposed:
!!! warning "Oauth connexion still in Beta"
Grdf Adict Oauth service is called Client Connect and is still in early beta. It is currently lacking a *state* parameter in the Oauth dance.
#### Authorize
##### /oauth2/realms/externeGrdf/authorize
#### Token
##### /oauth2/realms/externeGrdf/access_token
The */access_token* endpoint can be called with two different *grant_type* parameter.
- *authorization_code* gives an access token and will also retrieve the consents list given by the user in session.
- *client_credentials* gives only the access token allowing us to request the data service.
The grdf Konnector would only need to call the *client_credentials* to get a refresh token.
#### Consent Handling
Consent is represented by an access right. This access holds characteristics specific to the consent of the end customer.
##### Optional: Revoke consent from external applications
It is possible to cancel a consent that was given from the user to our service (for test or development purpose for instance).
**api.grdf.fr/adict/v1/droit_acces/{id_accreditation}**
### Grdf Adict
!!! info "grdf documentation"
Visit [https://sites.grdf.fr/web/portail-api-grdf-adict/documentation-grdf-adict](https://sites.grdf.fr/web/portail-api-grdf-adict/documentation-grdf-adict) to explore all the services exposed by Grdf.
> Prod endpoints are: [https://sofit-sso-oidc.grdf.fr/openam/](https://sofit-sso-oidc.grdf.fr/openam/)
Regarding Grdf Adict Oauth connexion, two endpoints are exposed:
!!! warning "Oauth connexion still in Beta"
Grdf Adict Oauth service is called Client Connect and is still in early beta. It is currently lacking a *state* parameter in the Oauth dance.
#### Authorize
##### /oauth2/realms/externeGrdf/authorize
#### Token
##### /oauth2/realms/externeGrdf/access_token
The */access_token* endpoint can be called with two different *grant_type* parameter.
- *authorization_code* gives an access token and will also retrieve the consents list given by the user in session.
- *client_credentials* gives only the access token allowing us to request the data service.
The grdf Konnector would only need to call the *client_credentials* to get a refresh token.
#### Consent Handling
Consent is represented by an access right. This access holds characteristics specific to the consent of the end customer.
##### Optional: Revoke consent from external applications
It is possible to cancel a consent that was given from the user to our service (for test or development purpose for instance).
**api.grdf.fr/adict/v1/droit_acces/{id_accreditation}**
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment