Exempel på GitHub Connector

Artikel
12/13/2023

GitHub M-tillägget visar hur du lägger till stöd för ett OAuth 2.0-protokollautentiseringsflöde. Du kan lära dig mer om detaljerna i GitHubs autentiseringsflöde på GitHub Developer-webbplatsen.

Innan du börjar skapa ett M-tillägg måste du registrera en ny app på GitHub och ersätta client_id filerna och client_secret med lämpliga värden för din app.

Obs! Om kompatibilitetsproblem i Visual Studio: Power Query SDK använder en Internet Explorer-baserad kontroll för att öppna OAuth-dialogrutor. GitHub har föråldrat sitt stöd för den version av IE som används av den här kontrollen, vilket hindrar dig från att slutföra behörighetsbeviljandet för din app om den körs inifrån Visual Studio. Ett alternativ är att läsa in tillägget med Power BI Desktop och slutföra det första OAuth-flödet där. När programmet har beviljats åtkomst till ditt konto fungerar efterföljande inloggningar bra från Visual Studio.

OAuth och Power BI

OAuth är en form av delegering av autentiseringsuppgifter. Genom att logga in på GitHub och auktorisera det "program" som du skapar för GitHub tillåter användaren att ditt "program" loggar in för deras räkning för att hämta data till Power BI. Programmet måste beviljas behörighet att hämta data (hämta en access_token) och uppdatera data enligt ett schema (hämta och använda en refresh_token). Ditt "program" i den här kontexten är dataanslutningsappen som används för att köra frågor i Power BI. Power BI lagrar och hanterar access_token och refresh_token åt dig.

Kommentar

Om du vill att Power BI ska kunna hämta och använda access_token måste du ange omdirigerings-URL:en som https://oauth.powerbi.com/views/oauthredirect.html.

När du anger den här URL:en och GitHub autentiserar och beviljar behörigheter omdirigeras GitHub till PowerBI:s oauthredirect-slutpunkt så att Power BI kan hämta access_token och refresh_token.

Så här registrerar du en GitHub-app

Ditt Power BI-tillägg måste logga in på GitHub. Om du vill aktivera detta registrerar du ett nytt OAuth-program med GitHub på https://github.com/settings/applications/new.

Application name: Ange ett namn för programmet för ditt M-tillägg.
Authorization callback URL: Ange https://oauth.powerbi.com/views/oauthredirect.html.
Scope: I GitHub anger du omfånget till user, repo.

Kommentar

Ett registrerat OAuth-program tilldelas ett unikt klient-ID och en klienthemlighet. Klienthemligheten ska inte delas. Du får klient-ID och klienthemlighet från GitHub-programsidan. Uppdatera filerna i dataanslutningsprojektet med klient-ID (client_id fil) och klienthemlighet (client_secret fil).

Så här implementerar du GitHub OAuth

Det här exemplet vägleder dig genom följande steg:

Skapa en typdefinition för datakälla som deklarerar att den stöder OAuth.
Ange information så att M-motorn kan starta OAuth-flödet (StartLogin).
Konvertera koden som tas emot från GitHub till en access_token (FinishLogin och TokenMethod).
Definiera funktioner som har åtkomst till GitHub API (GithubSample.Contents).

Steg 1 – Skapa en definition för datakälla

En dataanslutning börjar med en post som beskriver tillägget, inklusive dess unika namn (som är namnet på posten), autentiseringstyper som stöds och ett eget visningsnamn (etikett) för datakällan. När du stöder OAuth innehåller definitionen de funktioner som implementerar OAuth-kontraktet – i det här fallet StartLogin och FinishLogin.

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

Steg 2 – Ange information så att M-motorn kan starta OAuth-flödet

GitHub OAuth-flödet startar när du dirigerar användare till sidan https://github.com/login/oauth/authorize . För att användaren ska kunna logga in måste du ange ett antal frågeparametrar:

Namn	Type	Beskrivning
client_id	sträng	Obligatoriska. Det klient-ID som du fick från GitHub när du registrerade dig.
redirect_uri	sträng	Url:en i din app där användare skickas efter auktorisering. Se information nedan om omdirigerings-URL:er. För M-tillägg måste vara `redirect_uri` "https://oauth.powerbi.com/views/oauthredirect.html".
omfattning	sträng	En kommaavgränsad lista över omfång. Om det inte anges är omfånget som standard en tom lista med omfång för användare som inte har en giltig token för appen. För användare som redan har en giltig token för appen visas inte användaren på Auktoriseringssidan för OAuth med listan över omfång. I stället slutförs det här steget i flödet automatiskt med samma omfång som användes förra gången användaren slutförde flödet.
tillstånd	string	En slumpmässig sträng som inte kan gissas. Den används för att skydda mot förfalskningsattacker mellan webbplatser.

Följande kodfragment beskriver hur du implementerar en StartLogin funktion för att starta inloggningsflödet. En StartLogin funktion tar värdet resourceUrl, stateoch display . I funktionen skapar du en AuthorizeUrl som sammanfogar GitHub-auktorisera URL:en med följande parametrar:

client_id: Du får klient-ID när du har registrerat ditt tillägg med GitHub från GitHub-programsidan.
scope: Ange omfånget till "user, repo". Detta anger auktoriseringsomfånget (det vill vara vad din app vill komma åt) för användaren.
state: Ett internt värde som M-motorn skickar in.
redirect_uri: Ange till 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
            ];

Om det här är första gången användaren loggar in med din app (identifieras med dess client_id värde) ser de en sida som ber dem att bevilja åtkomst till din app. Efterföljande inloggningsförsök kommer helt enkelt att be om sina autentiseringsuppgifter.

Steg 3 – Konvertera koden som tas emot från GitHub till en access_token

Om användaren slutför autentiseringsflödet omdirigerar GitHub tillbaka till Power BI-omdirigerings-URL:en med en tillfällig kod i en code parameter samt det tillstånd som du angav i föregående steg i en state parameter. Funktionen FinishLogin extraherar koden från parametern callbackUri och byter den sedan mot en åtkomsttoken (med hjälp av TokenMethod funktionen).

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

För att få en GitHub-åtkomsttoken skickar du den tillfälliga koden från GitHub Authorize Response. TokenMethod I funktionen formulerar du en POST-begäran till GitHubs access_token slutpunkt (https://github.com/login/oauth/access_token). Följande parametrar krävs för GitHub-slutpunkten:

Namn	Type	Beskrivning
client_id	sträng	Obligatoriska. Det klient-ID som du fick från GitHub när du registrerade dig.
client_secret	sträng	Obligatoriska. Klienthemligheten som du fick från GitHub när du registrerade dig.
kod	sträng	Obligatoriska. Koden som du fick i `FinishLogin`.
redirect_uri	sträng	Url:en i din app där användare skickas efter auktorisering. Se information nedan om omdirigerings-URL:er.

Här är de informationsparametrar som används för web.contents-anropet .

Argument	beskrivning	Värde
URL	Url:en för webbplatsen.	https://github.com/login/oauth/access_token
alternativ	En post som styr funktionens beteende.	Används inte i det här fallet
Fråga	Lägg programmatiskt till frågeparametrar till URL:en.	`Content = Text.ToBinary( Uri.BuildQueryString( [ client_id = client_id, client_secret = client_secret, code = code, redirect_uri = redirect_uri ] ))` Där `client_id`: Klient-ID från GitHub-programsidan. `client_secret`: Klienthemlighet från GitHub-programsidan. `code`: Kod i GitHub-auktoriseringssvar. `redirect_uri`: URL:en i din app där användare skickas efter auktorisering.
Sidhuvuden	En post med ytterligare rubriker för HTTP-begäran.	`Headers= [ #"Content-type" = "application/x-www-form-urlencoded", #"Accept" = "application/json" ]`

Det här kodfragmentet beskriver hur du implementerar en TokenMethod funktion för att byta ut en autentiseringskod mot en åtkomsttoken.

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;

JSON-svaret från tjänsten innehåller ett access_token fält. Metoden TokenMethod konverterar JSON-svaret till en M-post med Json.Document och returnerar det till motorn.

Exempelsvar:

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

Steg 4 – Definiera funktioner som har åtkomst till GitHub-API:et

Följande kodfragment exporterar två funktioner (GithubSample.Contents och GithubSample.PagedTable) genom att markera dem som shared, och associerar dem med GithubSample datakällans typ.

[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);

Funktionen GithubSample.Contents publiceras också i användargränssnittet (så att den visas i dialogrutan Hämta data ). Funktionen Value.ReplaceType används för att ange funktionsparametern till den Url.Type tillskrivna typen.

Genom att associera dessa funktioner med GithubSample datakällans typ använder de automatiskt de autentiseringsuppgifter som användaren angav. Alla M-biblioteksfunktioner som har aktiverats för utökningsbarhet (till exempel Web.Contents) ärver automatiskt även dessa autentiseringsuppgifter.

Mer information om hur autentiseringsuppgifter och autentisering fungerar finns i Hantera autentisering.

Exempel-URL

Den här anslutningsappen kan hämta formaterade data från någon av GitHub v3 REST API-slutpunkterna. Frågan om att hämta alla incheckningar till dataanslutningsplatsen skulle till exempel se ut så här:

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

Dela via