[How to] Utilisation de l’API LinkedIn sous Knime
1. Qu’est-ce que l’API LinkedIn?
Voici le guide étape par étape pour apprendre l’utilisation de l’API LinkedIn sous Knime.
L’API LinkedIn est une API REST constituant le cœur de toutes les interactions programmatiques avec LinkedIn. L’API LinkedIn est utilisée pour interroger de manière programmatique des données, créer et gérer des annonces, créer et gérer des campagnes, obtenir des données liées au compte et effectuer une grande variété d’autres tâches.
Ce document s’intéresse à la configuration de l’API depuis le site développeur de LinkedIn puis la configuration de KNIME afin de récupérer les données liées à votre page LinkedIn pour pouvoir les exploiter par la suite sur Tableau.
Knime permet un accès rapide, facile et intuitif à la Data préparation et à la Data Science.
2. Créer une application sur LinkedIn Développer
Afin de configurer un compte de développeur LinkedIn. Allez sur LinkedIn Developer, vous devriez voir l’image ci-dessous sur votre écran.
Cliquez sur Create App pour accéder au formulaire de création d’application :
Remplissez les détails liés au nom que vous souhaitez donner à l’application ainsi que l’URL vers la page LinkedIn et cliquez sur « Create APP« .
Afin de terminer la création de l’application, vous devez vérifier votre application. Cliquez sur « Vérifier« .
Vous devriez voir une pop-up vous demandant de vérifier la société, faites défiler vers le bas et cliquez sur « Generate URL« .
REMARQUE : pour cette étape, vous devez avoir un accès administrateur à la page LinkedIn ou envoyer le lien à l’administrateur de la page.
Si vous êtes l’admin de votre page LinkedIn, copiez ce lien de vérification, ouvrez-le dans un nouvel onglet et cliquez sur « Verify » :
Si vous n’êtes pas l’administrateur de la page LinkedIn, envoyez ce lien à l’administrateur de la page et demandez-lui de le vérifier.
Enfin, revenez à la fenêtre pop-up de vérification de l’entreprise et cliquez sur « I’m done« .
En rafraichissant la page, vous devez voir que votre application LinkedIn est désormais vérifiée :
3. Activation des produits sign in et marketing développer platform
Pour aller plus loin et pouvoir profiter des services de l’API LinkedIn, vous allez avoir besoin d’un accès aux produits Marketing Developer Platform (MDP) et Sign In with LinkedIn.
Depuis la page d’accueil LinkedIn Developper, allez sur l’onglet « Products » et cliquez sur « Select » pour les produits « Marketing Developer Platform » et « Sign In with LinkedIn » :
Un e-mail sera envoyé à l’adresse e-mail principale de votre profil avec un lien pour remplir un formulaire. Vous devez remplir le « Formulaire de demande d’accès à la plate-forme des développeurs marketing« . Si aucun e-mail ne vous est parvenu, cliquez sur « View access form » :
Remplissez l’ensemble des informations demandées sur le formulaire afin de le soumettre aux équipes LinkedIn pour validation :
Remarque : Après avoir soumis le formulaire, attendez un certain temps (environ 1 jour) avant d’avoir la réponse des équipes LinkedIn.
4. Obtention du jeton d’accès
Afin de continuer avec cette guide d’utilisation de l’API LinkedIn sous Knime, nous avons besoin d’obtenir le jeton d’accès.
Il s’agit d’un code unique qui permet de lancer des appels d’API sur l’application LinkedIn initialement créée pour récupérer les données liées à votre page LinkedIn.
La récupération du jeton d’accès se fait en trois étapes :
- Récupération des informations liées à votre page Linkedin (Client_id et Client_secret) depuis l’interface Developper LinkedIn.
- Récupération d’un code d’autorisation d’accès courte durée.
- Echanger le code d’autorisation d’accès courte durée contre un jeton longue durée.
Étape 1 : Récupération du Client_Id et Client_Secret
Chaque application LinkedIn se voit attribuer un identifiant client unique (clé consommateur/clé API) et un secret client. Veuillez prendre note de ces valeurs car elles seront intégrées dans les fichiers de configuration de votre application. Votre Client_Secret protège la sécurité de votre application. Veillez donc à le conserver en toute sécurité.
Allez sur le portail des développeurs de LinkedIn, sélectionnez votre application, accédez à la section « Auth » et notez votre « Client ID » et votre « Client Secret« .
Dans le même onglet « Auth« , faites défiler jusqu’en bas. Sous « OAuth 2.0 Settings« , ajoutez l’URL de rappel https://www.linkedin.com/developers puis cliquez sur « Update » :
Étape 2 : Obtention du jeton d’accès courte durée
La demande du code d’autorisation d’accès courte durée nécessite la construction d’une URL à laquelle nous devrons accéder via un navigateur web. Un code d’autorisation d’accès courte durée sera ensuite visible au niveau de la barre d’URL du navigateur.
Il s’agit d’un call POST à l’URL de base suivante : https://www.linkedin.com/oauth/v2/authorization, en renseignant les 6 paramètres ci-dessous dans le corps de l’appel :
| Paramètre | Description | Requis |
| response_type | La valeur de ce champ doit toujours être : code | Oui |
| client_id | L’identifiant client de votre application | Oui |
| redirect_uri | L’url configuré dans l’étape 1. L’url doit être encoder avant. Pour encoder l’url, utiliser ce site: https://www.urlencoder.org | Oui |
| state | Une chaîne de caractères unique de votre choix, difficile à deviner. Utilisée pour empêcher le CSRF. Par exemple, state=DCEeFWf45A53sdfKef424. | Non |
| scope | Liste des autorisations, délimitées par des espaces, que votre application demande au nom de l’utilisateur. Elles doivent être explicitement demandées. Par exemple, scope=r_liteprofile%20r_emailaddress%20w_member_social. Pour plus d’informations, consultez la section Permissions: https://docs.microsoft.com/en-us/linkedin/shared/authentication/authentication?context=linkedin%2Fcontext&view=li-lms-2022-06#permission-types et les meilleures pratiques pour le développement d’applications. | Oui |
Dans notre cas, l’URL construite sera la suivante : https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id=77usllpfm9a7w2&redirect_uri=https%3A%2F%2Fwww.linkedin.com%2Fdevelopers&scope=rw_organization_admin
Une fois que vous avez collé l’URL dans le navigateur, vous allez être rediriger, pour se voir présenter l’écran d’authentification de LinkedIn. Cet écran identifie votre application et décrit les autorisations/champs d’application particuliers que votre application demande. Cliquez sur « Allow » pour confirmer l’autorisation :
Récupérer le code depuis l’URL : il s’agit du code d’autorisation d’accès courte durée.
Étape 3 : Échange du code d’autorisation contre un jeton d’accès longue durée
L’étape suivante consiste à obtenir un jeton d’accès pour votre application en utilisant le code d’autorisation de l’étape précédente. Pour ce faire, effectuez un call HTTP POST suivante avec un en-tête « Content-Type : x-www-form-urlencoded » en utilisant les paramètres suivants dans le corps de la demande :
| Paramètre | Description | Requis |
| grant_type | La valeur de ce champ doit toujours être : authorization_code | Oui |
| code | Code d’autorisation de l’étape précédente | Oui |
| client_id | L’identifiant client « client ID » de votre application | Oui |
| client_secret | L’identifiant client « client secret » de votre application | Oui |
| redirect_uri | Le même paramètre que l’étape précédente | Oui |
Exemple de requête :
curl -X POST https://www.linkedin.com/oauth/v2/accessToken?grant_type=authorization_code&code={authorization_code_from_step2_response}&redirect_uri={your_callback_url}&client_id={your_client_id}&client_secret={your_client_secret}’ \
-H ‘Content-Type: application/x-www-form-urlencoded’
Exemple de réponse :
Une demande de jeton d’accès réussie renvoie un objet JSON contenant les champs suivants :
| Paramètre | Description |
| access_token | Le jeton d’accès pour l’application. Cette valeur doit être conservée en toute sécurité, comme indiqué dans les conditions d’utilisation de l’API. La longueur des jetons d’accès est de ~500 caractères. |
| expires_in | Le nombre de secondes restant avant l’expiration du jeton. Actuellement, tous les jetons d’accès sont émis avec une durée de vie de 60 jours. |
Alternativement, vous pouvez générer le jeton d’accès longue durée depuis l’outil token-generator de LinkedIn.
Rendez-vous sur la page du token generator et sélectionnez votre application LinkedIn ainsi que les scopes que vous souhaitez. Ensuite cliquez sur « Request Access Token » :
Vous serez rediriger vers la page d’accès LinkedIn, où vous serez inviter à valider l’opération.
Une fois que cela est fait, vous pouvez récupérer le token généré :
5. Configuration Knime
Pour pouvoir lancer des calls d’API via KNIME, il faut installer l’extension KNIME REST Client Extension.
Sur KNIME, allez sur File > Install KNIME Extensions puis cherchez l’extension « KNIME REST Client Extension » :
Sélectionnez l’extension à installer puis avancer en appuyant sur « Next ». KNIME devrait redémarrer à la fin de l’installation.
Au redémarrage de KNIME à la fin de l’installation, vérifier que le nœud GET Request a bel et bien été installé :
Présentation de l’interface du nœud GET Request :
Ce nœud est utilisé pour émettre des requêtes HTTP GET.
Les requêtes GET sont utilisées pour récupérer des données à partir d’un service web sans envoyer de données autres que les paramètres de requête. Le nœud vous permet d’envoyer une requête à une URL fixe (qui est spécifiée dans le dialogue) ou à une liste d’URLs fournies par un tableau d’entrée optionnel.
Chaque URL donne lieu à une requête qui, à son tour, donne lieu à une ligne dans le tableau de sortie. Vous pouvez définir des en-têtes de requête personnalisés dans la boîte de dialogue. Par défaut, le tableau de sortie contient une colonne avec les données reçues, leur type de contenu et le code d’état HTTP.
Sur l’onglet « Connection Settings », vous devez saisir l’URL vers lequel vous souhaitez envoyer votre call GET. Les paramètres que vous souhaitez envoyer dans le corps de la requête devront être ajoutés à l’URL directement, séparés par le caractère « & ».
Pour ajouter des Headers à votre requête, rendez-vous sur l’onglet « Request Headers » :
Pour ajouter des Headers à votre requête, cliquez sur « Add header parameter » puis saisir la clé-valeur qui lui est associée puis cliquez sur OK.
6. Récupération du nombre des followers
Comme promis dans cette guide d’utilisation de l’API LinkedIn sous Knime, une fois votre application LinkedIn ainsi que votre environnement KNIME sont configurés, vous pouvez lancer vos premiers calls API.
Pour récupérer le nombre des followers de votre page par région, nous allons utiliser la fonction API suivante organizationalEntityFollowerStatistics.
Tout d’abord, il faut récupérer l’URN (Universal Request Number) de votre page LinkedIn. Il s’agit d’un identifiant unique que nous allons devoir utiliser pour faire les appels API LinkedIn au nom de votre page LinkedIn. Pour le retrouver, rendez-vous vers la page admin :
L’URN de la page est la chaîne de caractères suivante : « urn:li:organization:82582490 », le dernier code de cette chaîne étant le code récupéré depuis l’URL (cf. capture ci-dessus).
Pour récupérer le nombre des followers sur votre page LinkedIn, rendez-vous sur le nœud GET Request et coller l’URL suivante dans l’onglet « Connection Settings » : https://api.linkedin.com/v2/organizationalEntityFollowerStatistics?q=organizationalEntity&organizationalEntity=urn%3Ali%3Aorganization%3A82582490
Ensuite, il faut spécifier dans le nœud GET Request le jeton longue durée récupéré précédemment.
Pour ce faire, rendez-vous sur l’onglet Request Headers et ajouter une clé Authorization ayant pour valeur la chaîne de caractères suivante : Bearer {TOKEN_LONGUE_DUREE}
NB1 : l’URN de la page doit être encodé, i.e. les deux points « : » remplacées par %3A (se référer au site https://www.urlencoder.org si besoin).
NB2 : pour pouvoir récupérer des données à l’aide de cette fonction, vous avez besoin de la permission rw_organization_admin, comme cela est indiqué sur la page de la documentation. Ceci implique que ce droit devrait être explicitement spécifié au moment de la génération du jeton d’accès (cf. Étape 2 : Obtention du jeton d’accès courte durée) au niveau du paramètre scope.
Une fois que c’est fait, exécutez le nœud GET Request. La réponse de l’API est stockée dans la colonne « body » en format JSON :
7. Récupération des réactions sur le post LinkedIn
La récupération des réactions sur les posts publiés sur LinkedIn se fait en deux étapes (deux calls d’API) :
1er call : Récupération de la liste des identifiants de tous les posts publiés
2ème call : Récupération pour chaque post issu du 1er call, les réactions qui lui sont associées.
Étape 1 : Récupération de la liste des identifiants des posts publiés
Pour cette étape, nous allons utiliser la fonction UGC Post API. L’usage de cet API nécessite la même permission que l’exemple précédent, à savoir rw_organization_social.
Pour récupérer la liste des post sur votre page LinkedIn, rendez-vous sur le nœud GET Request et coller l’URL suivante dans l’onglet « Connection Settings » :
Le résultat renvoyé est un JSON. La clé « elements » de cette réponse JSON contient la liste des informations relatives à chaque post :
Étape 2 : Récupération pour chaque post issu du 1er call, les réactions qui lui sont associées.
Chaque élément de la liste « elements » est un post publié sur votre page LinkedIn.
Nous devons extraire pour chaque élément de cette liste, son ID et son texte. Pour ce faire, nous allons convertir ce JSON en XML puis extraire les informations avec le nœud XPath :
Placer un nœud XPath après le JSON to XML pour extraire l’ID et le texte associé à chaque post.
NB : l’extraction de chaque colonne du XPath (id et text) doit être positionné en Multiple Rows (cf. capture ci-dessous).
Résultat intérmediaire :
Une fois les ID de posts récupérés, un nouveau call d’API est nécessaire pour récupérer les stats liés à chaque post. Pour ce faire, nous allons utiliser la fonction Organization Share Statistics.
Cette fonction attend un appel GET avec les paramètres ci-dessous :
| Paramètre | Description |
| organizationalEntity | URN unique de la page LinkedIn |
| ugcPosts[0] | URN du post (ID du post récupéré à l’étape précédente) |
Nous allons devoir créer une nouvelle colonne SHARES_STATS_URI à l’aide du nœud Column Expressions :
SHARES_STATS_URI= ‘https://api.linkedin.com/rest/organizationalEntityShareStatistics?q=organizationalEntity&organizationalEntity=urn%3Ali%3Aorganization%3A82582490&ugcPosts[0]=’+column(‘id’)
Ensuite, cette nouvelle colonne sera spécifiée dans le nœud GET Request en tant qu’URL à prendre en compte :
La réponse de cette requête sera un JSON associé à chaque ID de post, contenant les réactions enregistrées sur le post en question :
Ajouter un nœud JSON to XML et un nœud XPath pour extraire les réactions, en reprenant la procédure de l’étape précédente :
Résultat final :
8. Annexe : Fonction LinkedIn Utiles
Organization Follower Statistics
L’API organizationalEntityFollowerStatistics vous permet de récupérer des statistiques sur les followers de votre page. Cette API requiert une permission rw_organization_admin.
Cette API permet d’extraire les statistiques suivantes sur vos followers :
| Facet | Description |
| followerCountsByAssociationType | Nombre de followers par type d’association (sponsorisés ou organiques). |
| followerCountsByCountry | Nombre de followers par pays. |
| followerCountsByFunction | Nombre de followers par profession. |
| followerCountsByIndustry | Nombre de followers par industrie. |
| followerCountsByRegion | Nombre de followers par région. |
| followerCountsBySeniority | Nombre de followers par années d’expérience. |
Il existe également une possibilité d’avoir une évolution de ces statistiques sur une période spécifique. Ceci pourrait être intéressant pour quantifier le gain en termes de followers après le lancement d’une campagne.
Pour cela, il faudra rajouter les paramètres suivants dans le corps de la requête :
| Paramètre | Description |
| timeIntervals.timeGranularityType | Granularité de la période (DAY, MONTH, YEAR,..). |
| timeIntervals.timeRange.start | Date de début de la période en timestamp UNIX |
| timeIntervals.timeRange.end | Date de fin de la période en timestamp UNIX |
Exemple de requête :
-H ‘Authorization: Bearer {INSERT_TOKEN}’
Exemple de réponse :
Video Analytics API
L’API videoAnalytics vous permet de recueillir des données analytiques sur une entité vidéo. L’API fournit les mesures suivantes :
- Temps de visionnage
- Le nombre de vues sur la vidéo
- Les personnes ayant visionnées la vidéo
L’API requiert une permission r_organization_social.
L’API prend les paramètres suivants dans le corps :
| Paramètre | Type | Description |
| entity | URN | URN ugcPost du post incluant la vidéo. |
| type | string | Type of analytics returned: |
| · VIDEO_VIEW : Nombre de vues sur la vidéo. | ||
| · VIEWER : Le nombre de personnes ayant visionnées la vidéo.
· TIME_WATCHED: Le temps de visionnement de la vidéo en millisecondes. · TIME_WATCHED_FOR_VIDEO_VIEWS: Le temps observé en millisecondes pour les cycles de lecture-pause vidéo qui durent au moins 3 secondes. |
||
| aggregation | string | Type d’agrégation : |
| · DAY: agrégation sur base quotidienne. | ||
| · WEEK: agrégation sur base hebdomadaire. La semaine commence le dimanche et finit le Samedi. | ||
| · ALL (par défault): agrégation sur toute la période. | ||
| timeRange | object | La période d’analyse. Par défaut, si aucune période n’est spécifiée, les analyses porteront sur la durée depuis la publication de la vidéo. Il s’agit d’un objet dont les champs start et end contiennent les timestamps de début et de fin. |
Exemple de requête :
curl -X GET ‘https://api.linkedin.com/rest/videoAnalytics?q=entity&entity=urn:li:ugcPost:6422171828579602432&type=TIME_WATCHED&timeRange=(start:1531165717442,end:1531770742335)&aggregation=DAY‘ \
-H ‘Authorization: Bearer {INSERT_TOKEN}’
Exemple de réponse :
Author Profile
Latest entries
How To10 novembre 2022[How to] Utilisation de l’API LinkedIn sous Knime
Les 3 minutes Analytics30 juillet 2020Les 3 Minutes Analytics : comment convertir une chaîne de caractères en nombre ?
Les 3 minutes Analytics30 juillet 2020Les 3 Minutes Analytics : Comment exporter vos données vers un fichier Excel dans KNIME
