Del via

Eksempel på GitHub-connector

  • Artikel

GitHub M-udvidelsen viser, hvordan du tilføjer understøttelse af et OAuth 2.0-protokolgodkendelsesflow. Du kan få mere at vide om detaljerne for GitHubs godkendelsesflow på GitHub-udviklerwebstedet.

Før du begynder at oprette en M-udvidelse, skal du registrere en ny app på GitHub og erstatte client_id filerne og client_secret med de relevante værdier for din app.

Bemærk om kompatibilitetsproblemer i Visual Studio: Power Query SDK bruger et Internet Explorer-baseret kontrolelement til at åbne OAuth-dialogbokse. GitHub har frarådet sin understøttelse af den version af IE, der bruges af dette kontrolelement, hvilket forhindrer dig i at fuldføre tilladelsestilskuddet til din app, hvis den køres fra Visual Studio. Et alternativ er at indlæse udvidelsen med Power BI Desktop og fuldføre det første OAuth-flow der. Når dit program har fået adgang til din konto, fungerer efterfølgende logon fint fra Visual Studio.

OAuth og Power BI

OAuth er en form for delegering af legitimationsoplysninger. Ved at logge på GitHub og godkende det "program", du opretter til GitHub, tillader brugeren, at dit "program" logger på deres vegne for at hente data til Power BI. "Programmet" skal tildeles rettigheder til at hente data (få en access_token) og til at opdatere dataene efter en tidsplan (hent og brug en refresh_token). Dit "program" i denne kontekst er din dataconnector, der bruges til at køre forespørgsler i Power BI. Power BI gemmer og administrerer access_token og refresh_token på dine vegne.

Bemærk

Hvis du vil give Power BI tilladelse til at hente og bruge access_token, skal du angive URL-adressen til omdirigering som https://oauth.powerbi.com/views/oauthredirect.html.

Når du angiver denne URL-adresse, og GitHub godkender og tildeler tilladelser, omdirigerer GitHub til PowerBI's oauthredirect-slutpunkt, så Power BI kan hente access_token og refresh_token.

Sådan registrerer du en GitHub-app

Din Power BI-udvidelse skal logge på GitHub. Hvis du vil aktivere dette, skal du registrere et nyt OAuth-program med GitHub på https://github.com/settings/applications/new.

  1. Application name: Angiv et navn til programmet for din M-udvidelse.
  2. Authorization callback URL: Angiv https://oauth.powerbi.com/views/oauthredirect.html.
  3. Scope: I GitHub skal du angive område til user, repo.

Bemærk

Et registreret OAuth-program tildeles et entydigt klient-id og klienthemmelighed. Klienthemmeligheden bør ikke deles. Du får klient-id'et og klienthemmeligheden fra gitHub-programsiden. Opdater filerne i dit Data Connector-projekt med klient-id (client_id fil) og Klienthemmelighed (client_secret fil).

Sådan implementerer du GitHub OAuth

I dette eksempel gennemgås følgende trin:

  1. Opret en datakildetypedefinition, der deklarerer, at den understøtter OAuth.
  2. Angiv detaljer, så M-programmet kan starte OAuth-flowet (StartLogin).
  3. Konvertér den kode, der modtages fra GitHub, til en access_token (FinishLogin og TokenMethod).
  4. Definer funktioner, der har adgang til GitHub-API'en (GithubSample.Contents).

Trin 1 – Opret en datakildedefinition

En Data Connector starter med en post , der beskriver udvidelsen, herunder det entydige navn (som er navnet på posten), understøttede godkendelsestype(r) og et brugervenligt vist navn (navn) for datakilden. Når du understøtter OAuth, indeholder definitionen de funktioner, der implementerer OAuth-kontrakten – i dette tilfælde StartLogin og FinishLogin.

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

Trin 2 – Angiv oplysninger, så M-programmet kan starte OAuth-flowet

GitHub OAuth-flowet starter, når du sender brugere til https://github.com/login/oauth/authorize siden. Hvis brugeren skal logge på, skal du angive en række forespørgselsparametre:

Name Skriv Description
client_id string Krævet. Det klient-id, du modtog fra GitHub, da du registrerede det.
redirect_uri string URL-adressen i din app, hvor brugerne sendes efter godkendelse. Se detaljer nedenfor om URL-adresser til omdirigering. I forbindelse med M-udvidelser redirect_uri skal være "https://oauth.powerbi.com/views/oauthredirect.html".
omfang string En kommasepareret liste over områder. Hvis det ikke er angivet, er området som standard en tom liste over områder for brugere, der ikke har et gyldigt token til appen. For brugere, der allerede har et gyldigt token til appen, får brugeren ikke vist OAuth-godkendelsessiden med listen over områder. I stedet fuldføres dette trin i flowet automatisk med de samme områder, som blev brugt, sidste gang brugeren fuldførte flowet.
state string En tilfældig streng, der ikke kan gættes. Den bruges til at beskytte mod forfalskningsangreb på tværs af websteder.

I følgende kodestykke beskrives det, hvordan du implementerer en StartLogin funktion for at starte logonflowet. En StartLogin funktion tager værdien resourceUrl, stateog display . I funktionen skal du oprette en AuthorizeUrl , der sammenkæder GitHub-godkendelses-URL-adressen med følgende parametre:

  • client_id: Du får klient-id'et, når du har registreret din udvidelse med GitHub fra siden med GitHub-programmet.
  • scope: Angiv område til "user, repo". Dette angiver godkendelsesomfanget (dvs. det, din app vil have adgang til) for brugeren.
  • state: En intern værdi, som M-programmet passerer ind.
  • redirect_uri: Angiv som 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
            ];

Hvis det er første gang, brugeren logger på med din app (identificeret af dens client_id værdi), får vedkommende vist en side, der beder vedkommende om at give adgang til din app. Efterfølgende logonforsøg vil blot bede om deres legitimationsoplysninger.

Trin 3 – Konvertér den kode, der modtages fra GitHub, til en access_token

Hvis brugeren fuldfører godkendelsesflowet, omdirigerer GitHub tilbage til URL-adressen til Power BI-omdirigering med en midlertidig kode i en code parameter samt den tilstand, du har angivet i det forrige trin i en state parameter. Din FinishLogin funktion udtrækker koden fra callbackUri parameteren og udveksler den derefter med et adgangstoken (ved hjælp af funktionen TokenMethod ).

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

Hvis du vil hente et GitHub-adgangstoken, skal du overføre den midlertidige kode fra GitHub-godkendelsessvar. I funktionen TokenMethod kan du formulere en POST-anmodning til GitHubs access_token slutpunkt (https://github.com/login/oauth/access_token). Følgende parametre er påkrævet for GitHub-slutpunktet:

Name Skriv Description
client_id string Krævet. Det klient-id, du modtog fra GitHub, da du registrerede det.
client_secret string Krævet. Den klienthemmelighed, du modtog fra GitHub, da du tilmeldte dig.
kode string Krævet. Den kode, du har modtaget i FinishLogin.
redirect_uri string URL-adressen i din app, hvor brugerne sendes efter godkendelse. Se detaljer nedenfor om URL-adresser til omdirigering.

Her er de oplysninger, der bruges parametre for Web.Contents-kaldet .

Argument Beskrivelse Værdi
url URL-adressen til webstedet. https://github.com/login/oauth/access_token
options En post til at styre funktionsmåden for denne funktion. Bruges ikke i dette tilfælde
Anmodning Føj forespørgselsparametre til URL-adressen ved hjælp af programmering. Content = Text.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
code = code,
redirect_uri = redirect_uri
]
))
Hvor
  • client_id: Klient-id fra gitHub-programsiden.
  • client_secret: Klienthemmelighed fra gitHub-programsiden.
  • code: Kode i GitHub-godkendelsessvar.
  • redirect_uri: URL-adressen i din app, hvor brugerne sendes efter godkendelse.
Headere En post med flere headere til HTTP-anmodningen. Overskrifter= [
#"Indholdstype" = "application/x-www-form-urlencoded",
#"Accept" = "application/json"
]

Dette kodestykke beskriver, hvordan du implementerer en TokenMethod funktion for at udveksle en godkendelseskode for et adgangstoken.

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 fra tjenesten indeholder et access_token felt. Metoden TokenMethod konverterer JSON-svaret til en M-post ved hjælp af Json.Document og returnerer det til programmet.

Eksempel på svar:

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

Trin 4 – Definer funktioner, der har adgang til GitHub-API'en

Følgende kodestykke eksporterer to funktioner (GithubSample.Contents og GithubSample.PagedTable) ved at markere dem som sharedog knytter dem til GithubSample datakildetypen.

[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 udgives også i brugergrænsefladen (så den vises i dialogboksen Hent data ). Funktionen Value.ReplaceType bruges til at angive funktionsparameteren til den Url.Type tilskrevne type.

Ved at knytte disse funktioner til GithubSample datakildetypen bruger de automatisk de legitimationsoplysninger, som brugeren har angivet. Alle M-biblioteksfunktioner, der er aktiveret til udvidelse (f.eks. Web.Contents), arver også automatisk disse legitimationsoplysninger.

Du kan finde flere oplysninger om, hvordan legitimationsoplysninger og godkendelse fungerer, under Håndtering af godkendelse.

EKSEMPEL PÅ URL-adresse

Denne connector kan hente formaterede data fra et af GitHub v3 REST API-slutpunkterne. Forespørgslen om at trække alle bekræftelser til lageret dataconnectors vil f.eks. se sådan ud:

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