Zdieľať cez

Ukážka konektora GitHub

  • Článok

Rozšírenie jazyka M GitHub ukazuje, ako pridať podporu pre postup overovania protokolu OAuth 2.0. Ďalšie informácie o podrobnostiach postupu overovania v GitHube nájdete na lokalite pre vývojárov GitHubu.

Skôr než začnete vytvárať rozšírenie jazyka M, musíte si zaregistrovať novú aplikáciu v službe GitHub a nahradiť client_id súbory a client_secret príslušnými hodnotami pre aplikáciu.

Poznámka k problémom s kompatibilitou vo Visual Studiu: Súprava Power Query SDK používa ovládací prvok Založený na Internet Exploreri na kontextové dialógové okná OAuth. GitHub už nepoužíva svoju podporu verzie IE používanej týmto ovládacím prvkom, čo vám zabráni dokončiť udelenie povolenia pre aplikáciu v prípade spustenia v rámci Visual Studia. Alternatívou je načítanie rozšírenia s aplikáciou Power BI Desktop a dokončenie prvého postupu OAuth. Po udelení prístupu k vášmu kontu budú následné prihlásenia z Visual Studia fungovať dobre.

OAuth a Power BI

OAuth je forma delegovania poverení. Po prihlásení do GitHubu a autorizovaní "aplikácie", ktorú ste vytvorili pre GitHub, používateľ umožňuje vašej "aplikácii" prihlásiť sa v ich mene a načítať údaje do služby Power BI. Aplikácia musí mať udelené práva na načítanie údajov (získanie access_token) a na obnovenie údajov podľa plánu (získanie a používanie refresh_token). Vaša "aplikácia" v tomto kontexte predstavuje váš údajový konektor používaný na spúšťanie dotazov v rámci služby Power BI. Power BI ukladá a spravuje access_token a refresh_token vo vašom mene.

Poznámka

Ak chcete službe Power BI povoliť získanie a používanie access_token, musíte zadať URL adresu presmerovania ako https://oauth.powerbi.com/views/oauthredirect.html.

Keď zadáte túto URL adresu a GitHub úspešne overí a udelí povolenia, GitHub sa presmeruje na koncový bod oauthredirect služby PowerBI, aby služba Power BI mohla načítať access_token a refresh_token.

Registrácia aplikácie GitHub

Vaše rozšírenie Power BI sa musí prihlásiť do služby GitHub. Ak to chcete povoliť, zaregistrujte novú aplikáciu OAuth v GitHube na lokalite https://github.com/settings/applications/new.

  1. Application name: Zadajte názov aplikácie pre svoje rozšírenie jazyka M.
  2. Authorization callback URL: Zadajte reťazec https://oauth.powerbi.com/views/oauthredirect.html.
  3. Scope: V službe GitHub nastavte rozsah na user, repo.

Poznámka

Registrovaná aplikácia OAuth má priradené jedinečné ID klienta a tajný kľúč klienta. Tajný kľúč klienta by sa nemal zdieľať. ID klienta a tajný kľúč klienta získate na stránke aplikácie GitHub. Aktualizujte súbory v projekte konektora Data Connector pomocou ID klienta (client_id súbor) a tajného kľúča klienta (client_secret súboru).

Implementácia overovania OAuth v službe GitHub

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

  1. Vytvorte definíciu Druh zdroja údajov, ktorá deklaruje, že podporuje OAuth.
  2. Zadajte podrobnosti, aby nástroj jazyka M mohol spustiť postup OAuth (StartLogin).
  3. Konvertujte kód prijatý zo služby GitHub na access_token (FinishLogin a TokenMethod).
  4. Definujte funkcie, ktoré pristupujú k rozhraniam API služby GitHub (GithubSample.Contents).

Krok 1 – vytvorte definíciu zdroja údajov

Konektor 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 overenia a popisného zobrazovaného názvu (označenia) zdroja údajov. Pri podpore overovania OAuth definícia obsahuje funkcie, ktoré implementujú zmluvu OAuth – v tomto prípade StartLogin a FinishLogin.

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

Krok 2 – zadajte podrobnosti, aby nástroj M mohol spustiť postup OAuth.

Postup OAuth v službe GitHub sa spustí, keď nasmerujete používateľov na https://github.com/login/oauth/authorize stránku. Na prihlásenie používateľa je potrebné zadať niekoľko parametrov dotazu:

Name Zadať Description
client_id povrázok Povinné. ID klienta, ktoré ste získali od GitHubu pri registrácii.
redirect_uri povrázok URL adresa aplikácie, kam sa používatelia odošlú po overení. Nižšie nájdete podrobnosti o URL adresách presmerovania. V prípade rozšírení jazyka M musí byť parameter redirect_uri "https://oauth.powerbi.com/views/oauthredirect.html".
rozsah povrázok Zoznam rozsahov oddelených čiarkou. Ak nie je zadaný, rozsah sa predvolene nastaví na prázdny zoznam rozsahov pre používateľov, ktorí nemajú platný token pre aplikáciu. Používateľom, ktorí už majú platný token aplikácie, sa používateľovi nezobrazí stránka oprávnenia OAuth so zoznamom rozsahov. Namiesto toho sa tento krok postupu automaticky dokončí s rovnakými rozsahmi, ktoré sa použili pri poslednom dokončení postupu používateľom.
štát povrázok Neuhádnuteľný náhodný reťazec. Používa sa na ochranu pred útokmi naprieč žiadosťami o falzifikáty lokality.

Nasledujúci zlomok kódu popisuje implementáciu StartLogin funkcie na spustenie postupu prihlásenia. Funkcia StartLogin použije resourceUrlhodnotu , statea display . Vytvorte vo funkcii zreťazenie AuthorizeUrl URL adresy služby GitHub pomocou nasledujúcich parametrov:

  • client_id: ID klienta získate po registrácii rozšírenia v službe GitHub na stránke aplikácie GitHub.
  • scope: Nastavte rozsah na hodnotu .user, repo Tým sa nastaví rozsah oprávnenia (t. j. to, ku čomu chce vaša aplikácia pristupovať) používateľa.
  • state: Vnútorná hodnota, ktorú odovzdá motor M.
  • redirect_uri: Nastavte na https://oauth.powerbi.com/views/oauthredirect.htmlhodnotu .
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 sa používateľ do vašej aplikácie prihlasuje po prvýkrát (identifikovaný jej client_id hodnotou), zobrazí sa mu stránka so žiadosťou o udelenie prístupu k vašej aplikácii. Následné pokusy o prihlásenie budú jednoducho žiadať o ich poverenia.

Krok 3 – Konvertovanie kódu prijatého zo služby GitHub na access_token

Po dokončení postupu overovania presmeruje služba GitHub späť na URL adresu presmerovania služby Power BI s dočasným kódom code v parametri, ako aj 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 TokenMethod funkcie).

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

Ak chcete získať prístupový token pre GitHub, odošlite dočasný kód z GitHubu Authorize Response. Vo funkcii TokenMethod vytvoríte požiadavku POST do koncového bodu access_token služby GitHub (https://github.com/login/oauth/access_token). Pre koncový bod služby GitHub sa vyžadujú nasledujúce parametre:

Name Zadať Description
client_id povrázok Povinné. ID klienta, ktoré ste získali od GitHubu pri registrácii.
client_secret povrázok Povinné. Tajný kľúč klienta, ktorý ste získali od GitHubu, keď ste sa zaregistrovali.
kód povrázok Povinné. Kód, ktorý ste dostali v FinishLogin.
redirect_uri povrázok URL adresa aplikácie, kam sa používatelia odošlú po overení. Nižšie nájdete podrobnosti o URL adresách presmerovania.

Tu sú podrobnosti použité parametre pre volanie Web.Contents .

Argument Description Value
url URL adresa webovej lokality. https://github.com/login/oauth/access_token
Možnosti Záznam na ovládanie správania tejto funkcie. Nepoužíva sa v tomto prípade
Query Programovo pridá parametre dotazu do URL adresy. Content = Text.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
code = code,
redirect_uri = redirect_uri
]
))
Kde
  • client_id: ID klienta zo stránky aplikácie GitHub.
  • client_secret: Tajný kľúč klienta zo stránky aplikácie GitHub.
  • code: Kód v odpovedi na autorizáciu GitHub.
  • redirect_uri: URL adresa vo vašej aplikácii, kam sa používatelia odošlú po overení.
Hlavičky Záznam s ďalšími hlavičkami pre požiadavku HTTP. Headers= [
#"Content-type" = "application/x-www-form-urlencoded",
#"Prijať" = "aplikácia/json"
]

Tento zlomok kódu popisuje implementáciu TokenMethod funkcie na výmenu overané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ť pole access_token. Metóda TokenMethod konvertuje odpoveď JSON na záznam jazyka M pomocou funkcie Json.Document a vráti ju do nástroja.

Vzorová odpoveď:

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

Krok 4 – definujte funkcie, ktoré pristupujú k API GitHubu

Nasledujúci zlomok kódu exportuje dve funkcie (GithubSample.Contents a GithubSample.PagedTable) tak, že ich označí ako shareda priradí ich k druhu GithubSample zdroja údajov.

[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 sa publikuje aj do používateľského rozhrania (čo umožňuje, aby sa zobrazovala v dialógovom okne Získať údaje ). Funkcia Value.ReplaceType sa používa na nastavenie parametra funkcie na Url.Type pripísaný typ.

Priradením týchto funkcií k druhu GithubSample zdroja údajov sa automaticky použijú poverenia, ktoré používateľ poskytol. Všetky funkcie knižnice jazyka M, ktoré boli povolené na rozšíriteľnosť (napríklad Web.Contents), tieto poverenia automaticky zdedia tiež.

Ďalšie informácie o tom, ako prihlasovacie údaje a overovanie fungujú, nájdete v téme Spracovanie overovania.

Vzorová URL adresa

Tento konektor je schopný načítať formátované údaje z ľubovoľného koncového bodu rozhrania GitHub v3 REST API. Napríklad dotaz, ktorý má vyžiadať všetky záväzky do odkladacieho priestoru údajových konektorov, by vyzeral takto:

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