-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.Rmd
146 lines (100 loc) · 5.78 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# apinsee
<!-- badges: start -->
[](https://www.tidyverse.org/lifecycle/#experimental)
[](https://travis-ci.org/InseeFrLab/apinsee)
[](https://codecov.io/gh/InseeFrLab/apinsee?branch=master)
[](https://cran.r-project.org/package=apinsee)
[](https://opensource.org/licenses/MIT)
<!-- badges: end -->
**apinsee** est un package pour le langage R destiné à faciliter l'authentification aux API de l'Insee accessibles à l'adresse [api.insee.fr](https://api.insee.fr/).
## Avertissement
**Ce package est en cours de développement. Ses fonctionnalités peuvent évoluer.**
## Motivation
Comme toutes les API modernes, l'utilisation des API de l'Insee requiert d'utiliser une procédure d'authentification et de récupérer un jeton d'accès. Le site [api.insee.fr](https://api.insee.fr/) recommande d'utiliser un nouveau jeton d'accès toutes les 24 heures.
L'objectif du package **apinsee** est de faciliter la gestion et l'utilisation de ces jetons d'accès conformément à ces recommandations : il permet de récupérer automatiquement, depuis R, un nouveau jeton d'accès valide pour une durée de 24 heures.
## Installation
Vous pouvez installer la version de développement depuis [GitHub](https://github.com/) en exécutant :
``` r
remotes::install_github("inseefrlab/apinsee")
```
## Exemple
### Créer une application
Créez une application sur le site [api.insee.fr](https://api.insee.fr/) : voir [l'aide](https://api.insee.fr/catalogue/site/themes/wso2/subthemes/insee/pages/help.jag).
Sauvegardez la clef du consommateur dans la variable d'environnement `INSEE_APP_KEY` et le secret du consommateur dans la variable d'environnement `INSEE_APP_SECRET` : la méthode la plus sûre est d'enregistrer ces deux variables d'environnement dans votre fichier `.Renviron`.
Pour accéder facilement au fichier `.Renviron`, vous pouvez utiliser la commande `usethis::edit_r_environ("user")`.
Ajoutez ces deux lignes dans votre fichier `.Renviron` :
```{bash, eval=FALSE}
INSEE_APP_KEY=xxxxxxxxxxxxxxxxxx # clef du consommateur
INSEE_APP_SECRET=yyyyyyyyyyyyyyyyyy # secret du consommateur
```
Sauvegardez ce fichier et **redémarrez votre session R**.
### Créer et utiliser un jeton d'accès
Le package **apinsee** ne comprend qu'une fonction utile : `insee_auth()`. Cette fonction permet de récupérer un jeton d'accès à votre application. Ce jeton d'accès peut être affecté à un objet et est sauvegardé de façon interne dans votre session R. Vous pouvez donc simplement exécuter la fonction :
```{r}
token <- apinsee::insee_auth()
```
Les jetons d'accès ayant une durée de validité limitée, cette fonction permet de récupérer automatiquement un jeton valide.
Ce token peut ensuite être utilisé comme valeur du paramètre `token` de la fonction `httr::config()` :
```{r, eval=FALSE}
library(httr)
set_config(config(token = token))
```
Dès lors, vous pouvez accéder aux API de l'Insee auxquelles votre application a souscrites.
## Utiliser **apinsee** dans votre package
Imaginons que vous souhaitiez développer un package qui accède à l'API Sirene. Vous pouvez créer la fonction suivante :
```{r}
requete_siren_unitaire <- function(siren, date = NULL,
token = apinsee::insee_auth()) {
url <- httr::modify_url(
"https://api.insee.fr/",
path = c("entreprises", "sirene", "V3", "siren", siren),
query = list(date = date)
)
res <- httr::GET(url, httr::config(token = token))
# check for rate limit
if (identical(httr::status_code(res), 429L)) {
Sys.sleep(60)
res <- httr::GET(url, httr::config(token = token))
}
httr::stop_for_status(res)
httr::content(res)[["uniteLegale"]]
}
```
Dès lors, votre utilisateur (s'il utilise une application ayant souscrit à l'API Sirene et qu'il a correctement renseigné les variables d'environnement) aura à simplement exécuter la fonction `requete_sirene_unitaire()` de votre package :
```{r demo, eval=FALSE}
requete_siren_unitaire(siren = "005520135", date = Sys.Date())
```
<details>
```{r demo, echo=FALSE}
```
</details>
### Conseil aux développeurs de packages utilisant apinsee
Si vous testez du code utilisant **apinsee**, vous devez mettre le package **httpuv** dans la rubrique `Suggests` du fichier `DESCRIPTION` de votre package.
## Utilisation interne à l'Insee
**apinsee** peut également être utilisé au sein de l'Insee pour les agents qui souhaiteraient accéder aux plateformes de test, recette ou pré-production. Le plus simple est de modifier l'option `apinsee.url`. La valeur par défaut de l'option `apinsee.url` est :
```{r}
getOption("apinsee.url")
```
Il vous suffit donc de rajouter avant d'exécuter vos scripts :
```{r, eval=FALSE}
options(apinsee.url = "adresse.de.la.plateforme")
```
Enfin, pour accéder à l'environnement de recette, il ne faut pas utiliser de proxy, vous devez donc également soit modifier les variables d'environnement `http_proxy` et `https_proxy` dans le fichier `.Renviron` (recommandé), soit rajouter :
```{r, eval=FALSE}
httr::set_config(httr::use_proxy(""))
```
## Licence
Le code source de ce projet est publié sous licence MIT.