Del via

GitHub Connector-eksempel

  • Artikkel

GitHub M-utvidelsen viser hvordan du legger til støtte for en OAuth 2.0-protokollgodkjenningsflyt. Du kan lære mer om detaljene i GitHubs godkjenningsflyt på GitHub Developer-nettstedet.

Før du kommer i gang med å opprette en M-utvidelse, må du registrere en ny app på GitHub, og erstatte client_id filene og client_secret filene med de riktige verdiene for appen.

Obs! Kompatibilitetsproblemer i Visual Studio: Power Query SDK bruker en Internet Explorer-basert kontroll til å åpne OAuth-dialogbokser. GitHub har avskrevet støtten for versjonen av IE som brukes av denne kontrollen, noe som vil hindre deg i å fullføre tillatelsestilskuddet for appen hvis du kjører fra Visual Studio. Et alternativ er å laste inn utvidelsen med Power BI Desktop og fullføre den første OAuth-flyten der. Etter at programmet har fått tilgang til kontoen din, vil etterfølgende pålogginger fungere fint fra Visual Studio.

OAuth og Power BI

OAuth er en form for legitimasjonsdelegering. Ved å logge på GitHub og godkjenne «programmet» du oppretter for GitHub, tillater brukeren at «programmet» logger på deres vegne for å hente data til Power BI. Programmet må gis rettigheter til å hente data (hente en access_token) og oppdatere dataene etter en tidsplan (hente og bruke en refresh_token). Programmet ditt i denne konteksten er datakoblingen som brukes til å kjøre spørringer i Power BI. Power BI lagrer og administrerer access_token og refresh_token på dine vegne.

Merk

Hvis du vil tillate at Power BI henter og bruker access_token, må du angi url-adressen for omadressering som https://oauth.powerbi.com/views/oauthredirect.html.

Når du angir denne URL-adressen og GitHub godkjenner og gir tillatelser, omdirigeres GitHub til PowerBI's oauthredirect-endepunkt, slik at Power BI kan hente access_token og refresh_token.

Slik registrerer du en GitHub-app

Power BI-utvidelsen må logge på GitHub. Hvis du vil aktivere dette, registrerer du et nytt OAuth-program med GitHub på https://github.com/settings/applications/new.

  1. Application name: Skriv inn et navn for programmet for M-utvidelsen.
  2. Authorization callback URL: Skriv inn https://oauth.powerbi.com/views/oauthredirect.html.
  3. Scope: Angi omfang til user, repoi GitHub.

Merk

Et registrert OAuth-program tilordnes en unik klient-ID og klienthemmelighet. Klienthemmeligheten kan ikke deles. Du får klient-ID-en og klienthemmeligheten fra GitHub-programsiden. Oppdater filene i Data Connector-prosjektet med klient-ID (client_id fil) og Klienthemmelighet (client_secret fil).

Slik implementerer du GitHub OAuth

Dette eksemplet veileder deg gjennom følgende trinn:

  1. Opprett en definisjon av datakildetype som deklarerer at den støtter OAuth.
  2. Oppgi detaljer slik at M-motoren kan starte OAuth-flyten (StartLogin).
  3. Konverter koden som mottas fra GitHub, til en access_token (FinishLogin og TokenMethod).
  4. Definer funksjoner som får tilgang til GitHub-API-en (GithubSample.Contents).

Trinn 1 – Opprett en datakildedefinisjon

En datakobling starter med en post som beskriver utvidelsen, inkludert det unike navnet (som er navnet på posten), støttede godkjenningstyper og et egendefinert visningsnavn (etikett) for datakilden. Når du støtter OAuth, inneholder definisjonen funksjonene som implementerer OAuth-kontrakten – i dette tilfellet og StartLogin FinishLogin.

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

Trinn 2 – Oppgi detaljer slik at M-motoren kan starte OAuth-flyten

GitHub OAuth-flyten starter når du dirigerer brukere til https://github.com/login/oauth/authorize siden. Hvis brukeren skal logge på, må du angi en rekke spørringsparametere:

Navn Type Bekrivelse
client_id streng Required. Klient-ID-en du mottok fra GitHub da du registrerte deg.
redirect_uri streng NETTADRESSEn i appen der brukere sendes etter godkjenning. Se detaljer nedenfor om url-adresser for omadressering. For M-utvidelser redirect_uri må det være «https://oauth.powerbi.com/views/oauthredirect.html".
område streng En kommadelt liste over omfang. Hvis det ikke er angitt, brukes omfanget som standard til en tom liste over omfang for brukere som ikke har et gyldig token for appen. For brukere som allerede har et gyldig token for appen, vises ikke brukeren OAuth-godkjenningssiden med listen over omfang. I stedet fullføres dette trinnet i flyten automatisk med de samme omfangene som ble brukt sist gang brukeren fullførte flyten.
område streng En tilfeldig streng som ikke kan gjettes. Den brukes til å beskytte mot angrep på tvers av nettsteder.

Kodesnutten nedenfor beskriver hvordan du implementerer en StartLogin funksjon for å starte påloggingsflyten. En StartLogin funksjon tar en resourceUrl, stateog display verdi. I funksjonen oppretter du en AuthorizeUrl som kjeder sammen GitHub-godkjenningsnettadressen med følgende parametere:

  • client_id: Du får klient-ID-en når du registrerer utvidelsen med GitHub fra GitHub-programsiden.
  • scope: Sett omfanget til "user, repo". Dette angir autorisasjonsomfanget (det vil eksempelvis det appen ønsker å få tilgang til) for brukeren.
  • state: En intern verdi som M-motoren sender inn.
  • redirect_uri: Satt til 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 dette er første gang brukeren logger seg på med appen (identifisert av client_id verdien), ser de en side som ber dem om å gi tilgang til appen. Etterfølgende påloggingsforsøk vil ganske enkelt be om legitimasjon.

Trinn 3 – Konverter koden mottatt fra GitHub til en access_token

Hvis brukeren fullfører godkjenningsflyten, omdirigerer GitHub tilbake til nettadressen for Omadressering av Power BI med en midlertidig kode i en code parameter, i tillegg til tilstanden du oppgav i forrige trinn i en state parameter. Funksjonen FinishLogin trekker ut koden fra parameteren callbackUri , og bytter den deretter mot et tilgangstoken (ved hjelp av TokenMethod funksjonen).

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

Hvis du vil ha et GitHub-tilgangstoken, sender du den midlertidige koden fra GitHub Authorize Response. TokenMethod I funksjonen formulerer du en POST-forespørsel til GitHubs access_token endepunkt (https://github.com/login/oauth/access_token). Følgende parametere kreves for GitHub-endepunktet:

Navn Type Bekrivelse
client_id streng Required. Klient-ID-en du mottok fra GitHub da du registrerte deg.
client_secret streng Required. Klienthemmeligheten du mottok fra GitHub da du registrerte deg.
kode string Required. Koden du mottok i FinishLogin.
redirect_uri streng NETTADRESSEn i appen der brukere sendes etter godkjenning. Se detaljer nedenfor om omadressering av nettadresser.

Her er detaljene som brukes parametere for Web.Contents-kallet .

Argument Bekrivelse Verdi
URL-adresse URL-adressen for webområdet. https://github.com/login/oauth/access_token
options En post for å kontrollere virkemåten til denne funksjonen. Ikke brukt i dette tilfellet
Query Legg programmatisk til spørringsparametere i URL-adressen. Innhold = Text.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
kode = kode,
redirect_uri = redirect_uri
]
))
Hvor
  • client_id: Klient-ID fra GitHub-programsiden.
  • client_secret: Klienthemmelighet fra GitHub-programsiden.
  • code: Kode i GitHub-godkjenningssvar.
  • redirect_uri: NETTADRESSEN i appen der brukere sendes etter godkjenning.
Overskrifter En post med flere overskrifter for HTTP-forespørselen. Overskrifter= [
#"Content-type" = "application/x-www-form-urlencoded",
#"Godta" = "program/json"
]

Denne kodesnutten beskriver hvordan du implementerer en TokenMethod funksjon for å utveksle en godkjenningskode for et tilgangstoken.

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 vil inneholde et access_token felt. Metoden TokenMethod konverterer JSON-svaret til en M-post ved hjelp av Json.Document, og returnerer det til motoren.

Eksempelsvar:

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

Trinn 4 – Definer funksjoner som får tilgang til GitHub-API-en

Kodesnutten nedenfor eksporterer to funksjoner (GithubSample.Contents og GithubSample.PagedTable) ved å merke dem som shared, og 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);

Funksjonen GithubSample.Contents publiseres også til brukergrensesnittet (slik at den kan vises i dialogboksen Hent data ). Value.ReplaceType-funksjonen brukes til å angi funksjonsparameteren til den tilskrevne Url.Type typen.

Ved å knytte disse funksjonene til GithubSample datakildetypen, vil de automatisk bruke legitimasjonen som brukeren oppgav. Alle M-bibliotekfunksjoner som er aktivert for utvidbarhet (for eksempel Web.Contents), arver også denne legitimasjonen automatisk.

Hvis du vil ha mer informasjon om hvordan legitimasjon og godkjenning fungerer, kan du se Behandle godkjenning.

Url-adresse for eksempel

Denne koblingen kan hente formaterte data fra noen av GitHub v3 REST API-endepunktene. Spørringen for å hente alle utføringer til datakoblingsrepositoriet vil for eksempel se slik ut:

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