Exemple de connecteur GitHub

Article
10/05/2023

L’extension GitHub M montre comment ajouter la prise en charge d’un flux d’authentification de protocole OAuth 2.0. Vous pouvez en savoir plus sur les spécificités du flux d’authentification de GitHub sur le site du développeur GitHub.

Avant de commencer à créer une extension M, vous devez inscrire une nouvelle application sur GitHub et remplacer les fichiers client_id et client_secret par les valeurs appropriées pour votre application.

Remarque sur les problèmes de compatibilité dans Visual Studio : Le kit de développement logiciel (SDK) Power Query utilise un contrôle Basé sur Internet Explorer pour afficher les boîtes de dialogue OAuth. GitHub a déconseillé sa prise en charge de la version d’Internet Explorer utilisée par ce contrôle, ce qui vous empêche d’effectuer l’octroi d’autorisations pour votre application si elle est exécutée à partir de Visual Studio. Une alternative consiste à charger l’extension avec Power BI Desktop et à y terminer le premier flux OAuth. Une fois que votre application a reçu l’accès à votre compte, les connexions suivantes fonctionnent correctement à partir de Visual Studio.

OAuth et Power BI

OAuth est une forme de délégation d’informations d’identification. En vous connectant à GitHub et en autorisant l'« application » que vous créez pour GitHub, l’utilisateur autorise votre « application » à se connecter en son nom pour récupérer des données dans Power BI. L'« application » doit disposer de droits pour récupérer des données (obtenir un access_token) et actualiser les données selon une planification (obtenir et utiliser un refresh_token). Votre « application » dans ce contexte est votre connecteur de données utilisé pour exécuter des requêtes dans Power BI. Power BI stocke et gère les access_token et les refresh_token en votre nom.

Remarque

Pour permettre à Power BI d’obtenir et d’utiliser le access_token, vous devez spécifier l’URL de redirection en tant que https://oauth.powerbi.com/views/oauthredirect.html.

Lorsque vous spécifiez cette URL et GitHub authentifie et accorde des autorisations, GitHub redirige vers le point de terminaison oauthredirect de PowerBI afin que Power BI puisse récupérer les access_token et les refresh_token.

Inscription d’une application GitHub

Votre extension Power BI doit se connecter à GitHub. Pour l’activer, vous inscrivez une nouvelle application OAuth auprès de GitHub sur https://github.com/settings/applications/new.

Application name: entrez un nom pour l’application pour votre extension M.
Authorization callback URL : Entrez https://oauth.powerbi.com/views/oauthredirect.html.
Scope: Dans GitHub, définissez l’étendue sur user, repo.

Remarque

Chaque application OAuth inscrite se voit attribuer un ID client et une clé secrète client uniques. La clé secrète client ne doit pas être partagée. Vous obtenez l’ID client et la clé secrète client à partir de la page de l’application GitHub. Mettez à jour les fichiers de votre projet Data Connector avec l’ID client (client_id fichier) et secret client (client_secret fichier).

Comment implémenter GitHub OAuth

Cet exemple vous guide tout au long des étapes suivantes :

Créez une définition de type de source de données qui déclare qu’elle prend en charge OAuth.
Fournissez des détails pour que le moteur M puisse démarrer le flux OAuth (StartLogin).
Convertissez le code reçu de GitHub en access_token (FinishLogin et TokenMethod).
Définissez des fonctions qui accèdent à l’API GitHub (GithubSample.Contents).

Étape 1 : créez une définition de source de données

Un connecteur de données commence par un enregistrement qui décrit l’extension, y compris son nom unique (qui est le nom de l’enregistrement), les types d’authentification pris en charge et un nom complet convivial (étiquette) pour la source de données. Lors de la prise en charge d’OAuth, la définition contient les fonctions qui implémentent le contrat OAuth , dans ce cas StartLogin et FinishLogin.

//
// Data Source definition
//
GithubSample = [
    Authentication = [
        OAuth = [
            StartLogin = StartLogin,
            FinishLogin = FinishLogin
        ]
    ],
    Label = Extension.LoadString("DataSourceLabel")
];

Étape 2 : fournissez des détails pour que le moteur M puisse démarrer le flux OAuth

Le flux OAuth GitHub démarre lorsque vous dirigez les utilisateurs vers la page https://github.com/login/oauth/authorize. Pour que l’utilisateur se connecte, vous devez spécifier un certain nombre de paramètres de requête :

Nom	Type	Description
client_id	string	Obligatoire. ID client que vous avez reçu de GitHub lors de l’inscription.
redirect_uri	string	URL de votre application où les utilisateurs sont redirigés après l’autorisation. Consultez les détails ci-dessous sur les URL de redirection. Pour les extensions M, `redirect_uri` doit être «https://oauth.powerbi.com/views/oauthredirect.html" ;.
scope	string	Liste d’étendues séparée par des virgules. Si elle n’est pas fournie, l’étendue est définie par défaut sur une liste vide d’étendues pour les utilisateurs qui n’ont pas de jeton valide pour l’application. Les utilisateurs qui possèdent déjà un jeton valide pour l’application ne voient pas s’afficher la page d’autorisation OAuth comportant la liste des étendues. Au lieu de cela, cette étape du flux se termine automatiquement avec les mêmes étendues que celles utilisées la dernière fois que l’utilisateur a terminé le flux.
état	chaîne	Chaîne aléatoire indevinable. Elle est utilisée pour protéger contre les attaques de falsification de requête intersite.

L’extrait de code suivant décrit comment implémenter une fonction StartLogin pour démarrer le flux de connexion. Une fonction StartLogin prend une valeur resourceUrl, state et display. Dans la fonction, créez un AuthorizeUrl qui concatène l’URL d’autorisation GitHub avec les paramètres suivants :

client_id: vous obtenez l’ID client après avoir inscrit votre extension auprès de GitHub à partir de la page de l’application GitHub.
scope: définissez l’étendue sur «user, repo». Cela définit l’étendue d’autorisation (autrement dit, ce à quoi votre application souhaite accéder) pour l’utilisateur.
state: valeur interne transmise par le moteur M.
redirect_uri: définir sur https://oauth.powerbi.com/views/oauthredirect.html.

StartLogin = (resourceUrl, state, display) =>
        let
            AuthorizeUrl = "https://github.com/login/oauth/authorize?" & Uri.BuildQueryString([
                client_id = client_id,
                scope = "user, repo",
                state = state,
                redirect_uri = redirect_uri])
        in
            [
                LoginUri = AuthorizeUrl,
                CallbackUri = redirect_uri,
                WindowHeight = windowHeight,
                WindowWidth = windowWidth,
                Context = null
            ];

S’il s’agit de la première fois que l’utilisateur se connecte avec votre application (identifiée par sa client_id valeur), il verra une page qui lui demande d’accorder l’accès à votre application. Les tentatives de connexion suivantes demandent simplement leurs informations d’identification.

Étape 3 : convertissez le code reçu de GitHub en access_token

Si l’utilisateur termine le flux d’authentification, GitHub le renvoie à l’URL de redirection Power BI avec un code temporaire dans un paramètre code, de même que l’état que vous avez fourni à l’étape précédente dans un paramètre state. Votre FinishLogin fonction extrait le code du callbackUri paramètre, puis l’échange pour un jeton d’accès (à l’aide de la TokenMethod fonction).

FinishLogin = (context, callbackUri, state) =>
    let
        Parts = Uri.Parts(callbackUri)[Query]
    in
        TokenMethod(Parts[code]);

Pour obtenir un jeton d’accès GitHub, vous transmettez le code temporaire à partir de la réponse d’autorisation GitHub. Dans la fonction TokenMethod, vous formulez une requête POST sur le point de terminaison access_token de GitHub (https://github.com/login/oauth/access_token). Les paramètres suivants sont requis pour le point de terminaison GitHub :

Nom	Type	Description
client_id	string	Obligatoire. ID client que vous avez reçu de GitHub lors de l’inscription.
client_secret	string	Obligatoire. Clé secrète client que vous avez reçue de GitHub lors de l’inscription.
code	string	Obligatoire. Code que vous avez reçu en `FinishLogin`.
redirect_uri	string	URL de votre application où les utilisateurs sont redirigés après l’autorisation. Consultez les détails ci-dessous sur les URL de redirection.

Voici les paramètres utilisés pour l’appel Web.Contents .

Argument	Description	active
url	URL du site Web.	https://github.com/login/oauth/access_token
options	Enregistrement pour contrôler le comportement de cette fonction.	Non utilisé dans ce cas
Requête	Ajouter des paramètres de requête par programme à l’URL.	`Content = Text.ToBinary( Uri.BuildQueryString( [ client_id = client_id, client_secret = client_secret, code = code, redirect_uri = redirect_uri ] ))` Where `client_id`: ID client à partir de la page d’application GitHub. `client_secret`: ID client à partir de la page d’application GitHub. `code`: Code dans la réponse d’autorisation GitHub. `redirect_uri`: URL de votre application où les utilisateurs sont redirigés après l’autorisation.
En-têtes	Enregistrement avec des en-têtes supplémentaires pour la requête HTTP.	`Headers= [ #« Content-type » = « application/x-www-form-urlencoded », #« Accept » = « application/json » ]`

Cet extrait de code décrit comment implémenter une fonction TokenMethod pour échanger un code d’authentification pour un jeton d’accès.

TokenMethod = (code) =>
    let
        Response = Web.Contents("https://Github.com/login/oauth/access_token", [
            Content = Text.ToBinary(Uri.BuildQueryString([
                client_id = client_id,
                client_secret = client_secret,
                code = code,
                redirect_uri = redirect_uri])),
            Headers=[#"Content-type" = "application/x-www-form-urlencoded",#"Accept" = "application/json"]]),
        Parts = Json.Document(Response)
    in
        Parts;

La réponse JSON du service contient un champ access_token. La méthode TokenMethod convertit la réponse JSON en enregistrement M à l’aide de Json.Document et la retourne au moteur.

Exemple de réponse :

{
    "access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a",
    "scope":"user,repo",
    "token_type":"bearer"
}

Étape 4 : définissez des fonctions qui accèdent à l’API GitHub

L’extrait de code suivant exporte deux fonctions (GithubSample.Contents et GithubSample.PagedTable) en les marquant comme shared, et les associe au GithubSample type de source de données.

[DataSource.Kind="GithubSample", Publish="GithubSample.UI"]
shared GithubSample.Contents = Value.ReplaceType(Github.Contents, type function (url as Uri.Type) as any);

[DataSource.Kind="GithubSample"]
shared GithubSample.PagedTable = Value.ReplaceType(Github.PagedTable, type function (url as Uri.Type) as nullable table);

La fonction GithubSample.Contents est également publiée dans l’interface utilisateur (ce qui lui permet d’apparaître dans la boîte de dialogue Obtenir des données ). La fonction Value.ReplaceType est utilisée pour définir le paramètre de fonction sur le Url.Type type inscrit.

En associant ces fonctions au GithubSample type de source de données, elles utilisent automatiquement les informations d’identification fournies par l’utilisateur. Toutes les fonctions de bibliothèque M qui ont été activées pour l’extensibilité (comme Web.Contents) héritent automatiquement de ces informations d’identification.

Pour plus d’informations sur le fonctionnement des informations d’identification et de l’authentification, consultez Gestion de l’authentification.

Exemple d’URL

Ce connecteur peut récupérer des données mises en forme à partir de l’un des points de terminaison de l’API REST GitHub v3. Par exemple, la requête pour extraire toutes les validations dans le dépôt Data Connectors ressemble à ceci :

GithubSample.Contents("https://api.github.com/repos/microsoft/dataconnectors/commits")

Partager via