Ukázka Připojení oru GitHubu

Článek
12/13/2023

Rozšíření GitHub M ukazuje, jak přidat podporu pro tok ověřování protokolu OAuth 2.0. Další informace o specifikách toku ověřování GitHubu najdete na webu Pro vývojáře GitHubu.

Než začnete vytvářet rozšíření M, musíte zaregistrovat novou aplikaci na GitHubu a nahradit client_id soubory client_secret odpovídajícími hodnotami pro vaši aplikaci.

Poznámka k problémům s kompatibilitou v sadě Visual Studio: Sada Power Query SDK používá k automaticky otevíraným dialogovým oknům OAuth ovládací prvek založený na Internet Exploreru. GitHub přestal podporovat verzi IE, kterou tento ovládací prvek používá, což vám zabrání v dokončení udělení oprávnění pro aplikaci, pokud běží v sadě Visual Studio. Alternativou je načtení rozšíření pomocí Power BI Desktopu a dokončení prvního toku OAuth. Po udělení přístupu k vašemu účtu budou následná přihlášení v sadě Visual Studio fungovat správně.

OAuth a Power BI

OAuth je forma delegování přihlašovacích údajů. Když se přihlásíte k GitHubu a autorizujete "aplikaci", kterou vytvoříte pro GitHub, uživatel umožní, aby se vaše "aplikace" přihlásila svým jménem, aby načetla data do Power BI. "Aplikace" musí mít udělená práva k načtení dat (získání access_token) a k aktualizaci dat podle plánu (získání a použití refresh_token). Vaše "aplikace" v tomto kontextu je váš datový Připojení or používaný ke spouštění dotazů v Power BI. Power BI ukládá a spravuje access_token a refresh_token vaším jménem.

Poznámka:

Pokud chcete Power BI povolit získání a používání access_token, musíte zadat adresu URL přesměrování jako https://oauth.powerbi.com/views/oauthredirect.html.

Když zadáte tuto adresu URL a GitHub úspěšně ověří a udělíte oprávnění, GitHub se přesměruje na koncový bod oauthredirect PowerBI, aby Power BI mohl načíst access_token a refresh_token.

Postup registrace aplikace GitHub

Vaše rozšíření Power BI se musí přihlásit k GitHubu. Pokud to chcete povolit, zaregistrujete novou aplikaci OAuth v GitHubu na adrese https://github.com/settings/applications/new.

Application name: Zadejte název aplikace pro vaše rozšíření M.
Authorization callback URL: Zadejte https://oauth.powerbi.com/views/oauthredirect.html.
Scope: V GitHubu nastavte obor na user, repo.

Poznámka:

Zaregistrované aplikaci OAuth je přiřazeno jedinečné ID klienta a tajný klíč klienta. Tajný klíč klienta by se neměl sdílet. ID klienta a tajný klíč klienta získáte ze stránky aplikace GitHub. Aktualizujte soubory v projektu Data Připojení or pomocí ID klienta (client_idsouboru) a tajného klíče klienta (client_secretsouboru).

Implementace OAuth GitHubu

Tato ukázka vás provede následujícími kroky:

Vytvořte definici typu zdroje dat, která deklaruje, že podporuje OAuth.
Zadejte podrobnosti, aby modul M mohl spustit tok OAuth (StartLogin).
Převeďte kód přijatý z GitHubu na access_token (FinishLogin a TokenMethod).
Definujte funkce, které přistupuje k rozhraní API GitHubu (GithubSample.Contents).

Krok 1 : Vytvoření definice zdroje dat

Datový Připojení or začíná záznamem, který popisuje rozšíření, včetně jeho jedinečného názvu (což je název záznamu), podporovaných typů ověřování a popisného zobrazovaného názvu (popisku) pro zdroj dat. Při podpoře OAuth obsahuje definice funkce, které implementují kontrakt OAuth – v tomto případě StartLogin a FinishLogin.

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

Krok 2 – Zadání podrobností, aby modul M mohl spustit tok OAuth

Tok OAuth GitHubu se spustí, když uživatele nasměrujete na https://github.com/login/oauth/authorize stránku. Aby se uživatel přihlásil, musíte zadat několik parametrů dotazu:

Name	Typ	Popis
client_id	string	Povinný: ID klienta, které jste obdrželi z GitHubu při registraci.
redirect_uri	string	Adresa URL ve vaší aplikaci, kde se uživatelé po autorizaci posílají. Podrobnosti o adresách URL pro přesměrování najdete níže. Pro rozšíření `redirect_uri` M musí být "https://oauth.powerbi.com/views/oauthredirect.html".
rozsah	string	Čárkami oddělený seznam oborů. Pokud není zadaný, nastaví se výchozí obor na prázdný seznam oborů pro uživatele, kteří nemají platný token pro aplikaci. Pro uživatele, kteří už mají platný token pro aplikaci, se uživateli nezobrazí stránka autorizace OAuth se seznamem oborů. Místo toho se tento krok toku automaticky dokončí se stejnými obory, které se použily při posledním dokončení toku uživatelem.
state	string	Nechtěný náhodný řetězec. Používá se k ochraně před útoky proti padělání požadavků mezi weby.

Následující fragment kódu popisuje, jak implementovat StartLogin funkci pro spuštění toku přihlášení. Funkce StartLogin přebírá hodnotu resourceUrl, statea display hodnotu. Ve funkci vytvořte, AuthorizeUrl která zřetězí adresu URL autorizace GitHubu s následujícími parametry:

client_id: ID klienta získáte po registraci rozšíření na GitHubu ze stránky aplikace GitHub.
scope: Nastavte obor na "user, repo". Tím se nastaví obor autorizace (to znamená, k čemu chce vaše aplikace přistupovat) pro uživatele.
state: Vnitřní hodnota, kterou modul M předává.
redirect_uri: Nastavit 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
            ];

Pokud se uživatel přihlašuje k vaší aplikaci poprvé (identifikovaný podle její client_id hodnoty), zobrazí se stránka, která ho požádá o udělení přístupu k vaší aplikaci. Následné pokusy o přihlášení se jednoduše zobrazí žádost o jejich přihlašovací údaje.

Krok 3 : Převod kódu přijatého z GitHubu na access_token

Pokud uživatel dokončí tok ověřování, GitHub přesměruje zpět na adresu URL přesměrování Power BI s dočasným kódem v parametru code a také stav, který jste zadali v předchozím kroku parametru state . Vaše FinishLogin funkce extrahuje kód z parametru callbackUri a pak ho vymění za přístupový token (pomocí TokenMethod funkce).

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

Pokud chcete získat přístupový token GitHubu, předáte dočasný kód z autorizovací odpovědi GitHubu. TokenMethod Ve funkci formulujete požadavek POST na koncový bod access_token GitHubu (https://github.com/login/oauth/access_token). Pro koncový bod GitHubu se vyžadují následující parametry:

Name	Typ	Popis
client_id	string	Povinný: ID klienta, které jste obdrželi z GitHubu při registraci.
tajný klíč klienta	string	Povinný: Tajný klíč klienta, který jste dostali z GitHubu při registraci.
code	string	Povinný: Kód, který jste obdrželi v `FinishLogin`souboru .
redirect_uri	string	Adresa URL ve vaší aplikaci, kde se uživatelé po autorizaci posílají. Podrobnosti o adresách URL pro přesměrování najdete níže.

Tady jsou podrobnosti o použitých parametrech volání Web.Contents .

Argument	Popis	Hodnota
url	Adresa URL webu.	https://github.com/login/oauth/access_token
options	Záznam pro řízení chování této funkce.	V tomto případě se nepoužívá
Dotaz	Do adresy URL můžete přidat parametry dotazu prostřednictvím kódu programu.	`Content = Text.ToBinary( Uri.BuildQueryString( [ client_id = client_id, client_secret = client_secret, code = kód, redirect_uri = redirect_uri ] ))` Kde `client_id`: ID klienta ze stránky aplikace GitHub. `client_secret`: Tajný klíč klienta ze stránky aplikace GitHub. `code`: Kód v odpovědi na autorizaci GitHubu `redirect_uri`: Adresa URL ve vaší aplikaci, kde se uživatelé po autorizaci posílají.
Hlavičky	Záznam s dalšími hlavičkami pro požadavek HTTP.	`Headers= [ #"Content-type" = "application/x-www-form-urlencoded", #"Accept" = "application/json" ]`

Tento fragment kódu popisuje, jak implementovat TokenMethod funkci pro výměnu ověřovacího kódu pro pří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;

Odpověď JSON ze služby bude obsahovat pole access_token. Metoda TokenMethod převede odpověď JSON na záznam M pomocí Json.Document a vrátí ji do modulu.

Ukázková odpověď:

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

Krok 4 – Definování funkcí, které přistupuje k rozhraní API GitHubu

Následující fragment kódu exportuje dvě funkce (GithubSample.Contents a GithubSample.PagedTable) tak, že je označí jako shareda přidruží je k GithubSample druhu zdroje dat.

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

Funkce GithubSample.Contents je také publikovaná v uživatelském rozhraní (což umožňuje zobrazení v dialogovém okně Získat data ). Funkce Value.ReplaceType slouží k nastavení parametru funkce na Url.Type přiřazený typ.

Když tyto funkce přidružíte k GithubSample druhu zdroje dat, automaticky použijí přihlašovací údaje, které uživatel zadal. Všechny funkce knihovny M, které byly povoleny pro rozšiřitelnost (například Web.Contents), automaticky zdědí i tyto přihlašovací údaje.

Další podrobnosti o tom, jak fungují přihlašovací údaje a ověřování, najdete v tématu Zpracování ověřování.

Ukázková adresa URL

Tento konektor dokáže načíst naformátovaná data z libovolného koncového bodu rozhraní REST API GitHubu v3. Například dotaz pro přijetí všech potvrzení do úložiště Data Připojení orů by vypadal takto:

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

Sdílet prostřednictvím