Ukážka GitHub konektora

Rozšírenie GitHub M ukazuje, ako pridať podporu pre proces autentifikácie protokolu OAuth 2.0. Viac o špecifikácii autentifikačného procesu GitHubu sa dozviete na stránke GitHub Docs.

Predtým, než začnete vytvárať rozšírenie M, musíte zaregistrovať novú aplikáciu na GitHube a nahradiť client_id súbory and client_secret príslušnými hodnotami pre vašu aplikáciu.

Poznámka k problémom s kompatibilitou vo Visual Studio:Power Query SDK používa ovládanie založené na Internet Exploreri na vyskakovanie OAuth dialógov. GitHub zrušil podporu verzie IE používanej týmto ovládacím prvkom, čo vám zabráni dokončiť udelenie oprávnenia pre vašu aplikáciu, ak sa spustí priamo vo Visual Studio. Alternatívou je načítať rozšírenie pomocou Power BI Desktop a dokončiť prvý OAuth flow tam. Keď vaša aplikácia získa prístup k účtu, ďalšie prihlásenia budú fungovať bez problémov vo Visual Studiu.

OAuth a Power BI

OAuth je forma delegovania prihlasovacích údajov. Prihlásením sa na GitHub a autorizáciou "aplikácie", ktorú vytvoríte pre GitHub, používateľ umožňuje vašej "aplikácii" prihlásiť sa za neho a získať dáta do Power BI. "Aplikácii" musia byť udelené práva na získavanie dát (získanie access_token) a na ich plánované obnovovanie (získať a použiť refresh_token). Vaša "aplikácia" v tomto kontexte je váš Data Connector, ktorý slúži na spúšťanie dotazov v Power BI. Power BI ukladá a spravuje access_token a refresh_token vo vašom mene.

Keď zadáte túto URL a GitHub úspešne autentifikuje a udelí oprávnenia, GitHub presmeruje na Power BI oauthredirect endpoint, aby Power BI mohol získať access_token a refresh_token.

Ako zaregistrovať GitHub aplikáciu

Vaša Power BI rozšírenie sa musí prihlásiť na GitHub. Aby ste to umožnili, zaregistrujete novú OAuth aplikáciu na GitHube na .https://github.com/settings/applications/new

1. Application name: Zadajte názov pre žiadosť o vaše rozšírenie M.
2. Authorization callback URL: Enter https://oauth.powerbi.com/views/oauthredirect.html.
3. Scope: V GitHube nastavte rozsah na user, repo.

Ako implementovať GitHub OAuth

Táto ukážka vás prevedie nasledujúcimi krokmi:

1. Vytvorte definíciu typu dátového zdroja, ktorá deklaruje, že podporuje OAuth.
2. Uveďte detaily, aby M engine mohol spustiť tok OAuth (StartLogin).
3. Preveďte kód prijatý z GitHubu na access_token (FinishLogin a TokenMethod).
4. Definujte funkcie, ktoré pristupujú k GitHub API (GithubSample.Contents).

Krok 1 - Vytvoriť definíciu dátového zdroja

Data Connector začína záznamom , ktorý popisuje rozšírenie, vrátane jeho jedinečného názvu (ktorý je názvom záznamu), podporovaných typov autentifikácie a priateľského zobrazovacieho názvu (štítku) pre zdroj dát. Pri podpore OAuth definícia obsahuje funkcie, ktoré implementujú kontrakt OAuth – v tomto prípade StartLogin a FinishLogin.

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

Krok 2 – Poskytnúť detaily, aby M engine mohol spustiť tok OAuth

GitHub OAuth flow začína, keď používateľov nasmerujete na stránku https://github.com/login/oauth/authorize . Aby sa používateľ mohol prihlásiť, musíte zadať niekoľko parametrov dotazu:

Nasledujúci úryvok kódu popisuje, ako implementovať funkciu StartLogin na spustenie login flow. Funkcia nadobúda resourceUrlStartLogin , state, a display hodnotu. Vo funkcii vytvorte , AuthorizeUrl ktorá spája autorizovaciu URL GitHub s nasledujúcimi parametrami:

• client_id: ID klienta získate po registrácii rozšírenia na GitHube zo stránky aplikácie GitHub.
• scope: Nastavte rozsah na "user, repo". Tým sa nastaví rozsah autorizácie (teda to, ku čomu chce vaša aplikácia pristupovať) pre používateľa.
• state: Interná hodnota, ktorú M motor prenáša.
• redirect_uri: Nastavte na 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
            ];

Ak je to prvýkrát, čo sa používateľ prihlasuje do vašej aplikácie (identifikovanej podľa client_id jej hodnoty), uvidí stránku, ktorá ho požiada o udelenie prístupu k vašej aplikácii. Pri ďalších pokusoch o prihlásenie budú žiadať ich prihlasovacie údaje.

Krok 3 – Preveďte kód prijatý z GitHubu na access_token

Ak používateľ dokončí autentifikačný proces, GitHub presmeruje späť na Power BI presmerovaciu URL s dočasným kódom v parametri, code ako aj na stav, ktorý ste zadali v predchádzajúcom kroku parametra state . Vaša FinishLogin funkcia extrahuje kód z parametra callbackUri a potom ho vymení za prístupový token (pomocou tejto funkcie TokenMethod ).

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

Na získanie prístupového tokenu na GitHube odovzdáte dočasný kód z GitHub Authorize Response. Vo funkcii TokenMethod formulujete POST požiadavku na access_token endpoint GitHubu (https://github.com/login/oauth/access_token). Pre koncový bod GitHubu sú požadované nasledujúce parametre:

Tu sú podrobné použité parametre pre hovor Web.Content .

Tento úryvok kódu popisuje, ako implementovať funkciu TokenMethod na výmenu autentifikačného kódu za prístupový token.

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;

Odpoveď JSON zo služby bude obsahovať access_token pole. Metóda TokenMethod konvertuje JSON odpoveď na M záznam pomocou Json.document a vracia ho do enginu.

Príklad odpovede:

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

Krok 4 - Definujte funkcie, ktoré pristupujú k GitHub API

Nasledujúci úryvok kódu exportuje dve funkcie (GithubSample.Contents a GithubSample.PagedTable) označením ako shared, a priradí ich k druhu GithubSample dátového zdroja.

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

Funkcia GithubSample.Contents je tiež zverejnená v používateľskom rozhraní (čo umožňuje jej zobrazenie v dialógovom okne Získať dáta ). Funkcia Value.ReplaceType sa používa na nastavenie parametra funkcie na priradený Url.Type typ.

Priradením týchto funkcií k druhu GithubSample zdroja dát automaticky použijú prihlasovacie údaje, ktoré používateľ zadal. Všetky funkcie M knižnice, ktoré boli povolené na rozšírenie (napríklad Web.Contents), automaticky zdedia tieto prihlasovacie údaje.

Pre viac informácií o tom, ako fungujú prihlasovacie údaje a autentifikácia, pozri Spracovanie autentifikácie.

Ukážková URL adresa

Tento konektor dokáže získať formátované dáta z ktoréhokoľvek z GitHub v3 REST API koncových bodov. Napríklad dotaz na stiahnutie všetkých commitov do repozitára Data Connectors by vyzeral takto:

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