GitHub-összekötő minta

A GitHub M bővítmény bemutatja, hogyan adhat támogatást az OAuth 2.0 protokollhitelesítési folyamathoz. A GitHub hitelesítési folyamatának jellemzőiről a GitHub Docs webhelyén tudhat meg többet.

Az M-bővítmény létrehozásának megkezdése előtt regisztrálnia kell egy új alkalmazást a GitHubon, és le kell cserélnie a client_idclient_secret fájlokat az alkalmazás megfelelő értékeire.

Megjegyzés a Visual Studio kompatibilitási problémáiról:A Power Query SDK egy Internet Explorer-alapú vezérlővel jeleníti meg az OAuth-párbeszédpaneleket. A GitHub elavulttá tette a vezérlő által használt IE-verzió támogatását, ami megakadályozza, hogy a Visual Studióból való futtatás esetén az alkalmazás engedély-megadását végrehajtsa. Másik lehetőségként töltse be a bővítményt a Power BI Desktoppal, és ott végezze el az első OAuth-folyamatot. Miután az alkalmazás hozzáférést kapott a fiókjához, a későbbi bejelentkezések jól fognak működni a Visual Studióban.

OAuth és Power BI

Az OAuth a hitelesítő adatok delegálásának egy formája. Ha bejelentkezik a GitHubra, és engedélyezi a GitHubhoz létrehozott "alkalmazást", a felhasználó engedélyezi az "alkalmazás" számára, hogy a nevükben jelentkezzen be, hogy adatokat kérjen le a Power BI-ba. Az "alkalmazásnak" jogosultságot kell biztosítani az adatok lekérésére (access_token) és az adatok ütemezés szerinti frissítésére (refresh_token lekérésére és használatára). Ebben a kontextusban az "alkalmazás" az a Data Connector, amellyel lekérdezéseket futtathat a Power BI-ban. A Power BI az Ön nevében tárolja és kezeli a access_token és a refresh_token.

Megjegyzés:

Ha engedélyezni szeretné a Power BI számára a access_token beszerzését és használatát, meg kell adnia az átirányítási URL-címet a következőként https://oauth.powerbi.com/views/oauthredirect.html: .

Ha megadja ezt az URL-címet, és a GitHub sikeresen hitelesíti és engedélyeket ad meg, a GitHub átirányítja a Power BI oauthredirect végpontjára, hogy a Power BI lekérhesse a access_token és refresh_token.

GitHub-alkalmazás regisztrálása

A Power BI-bővítménynek be kell jelentkeznie a GitHubra. Ennek engedélyezéséhez regisztráljon egy új OAuth-alkalmazást a GitHubon: https://github.com/settings/applications/new.

1. Application name: Adja meg az alkalmazás nevét az M-bővítményhez.
2. Authorization callback URL: Írja be a következőt: https://oauth.powerbi.com/views/oauthredirect.html.
3. Scope: A GitHubon állítsa a hatókört a következőre user, repo: .

Megjegyzés:

A regisztrált OAuth-alkalmazásokhoz egyedi ügyfélazonosító és ügyfélkód tartozik. Az ügyfélkulcsot nem szabad megosztani. Az ügyfélazonosítót és az ügyfél titkos kódját a GitHub alkalmazásoldaláról szerezheti be. Frissítse a Data Connector-projektben lévő fájlokat az ügyfélazonosítóval (client_id fájl) és az ügyfél titkos kódjával (client_secret fájl).

A GitHub OAuth implementálása

Ez a minta végigvezeti a következő lépéseken:

1. Hozzon létre egy adatforrástípus-definíciót, amely deklarálja, hogy támogatja az OAuth-ot.
2. Adja meg a részleteket, hogy az M motor elindíthassa az OAuth-folyamatot (StartLogin).
3. Konvertálja a GitHubról kapott kódot egy access_tokenre (FinishLogin és TokenMethod).
4. A GitHub API-t (GithubSample.Contents) elérő függvények definiálása.

1. lépés – Adatforrás-definíció létrehozása

Az adatösszekötők a bővítményt leíró rekordokkal kezdődnek, beleértve annak egyedi nevét (amely a rekord neve), a támogatott hitelesítési típusokat és az adatforrás rövid megjelenítendő nevét (címkéjét). Az OAuth támogatásakor a definíció tartalmazza az OAuth-szerződést megvalósító függvényeket – ebben az esetben StartLogin és FinishLogin.

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

2. lépés – Adja meg a részleteket, hogy az M motor elindíthassa az OAuth-folyamatot

A GitHub OAuth-folyamat akkor indul el, amikor a felhasználókat a https://github.com/login/oauth/authorize lapra irányítja. Ahhoz, hogy a felhasználó bejelentkezjen, több lekérdezési paramétert kell megadnia:

Név	Típus	Description
client_id	karakterlánc	Kötelező. A GitHubról a regisztrációkor kapott ügyfélazonosító.
redirect_uri	karakterlánc	Az alkalmazás azon URL-címe, ahová a felhasználók az engedélyezés után kerülnek. További információ az átirányítási URL-címekről. Az M-bővítmények esetében a redirect_uri következőnek kell lennie: "https://oauth.powerbi.com/views/oauthredirect.html".
hatókör	karakterlánc	A hatókörök vesszővel tagolt listája. Ha nincs megadva, a hatókör alapértelmezés szerint üres lista lesz azon felhasználók számára, akiknek nincs érvényes jogkivonatuk az alkalmazáshoz. Azoknak a felhasználóknak, akik már rendelkeznek érvényes jogkivonattal az alkalmazáshoz, nem jelenik meg az OAuth engedélyezési oldala a hatókörök listájával. Ehelyett a folyamat ezen lépése automatikusan ugyanazokkal a hatókörökkel fejeződik be, amelyeket a felhasználó legutóbb a folyamat befejezésekor használt.
state	karakterlánc	Egy kitalálhatatlan véletlenszerű karakterlánc. A webhelyek közötti kérelem hamisítási támadások elleni védelemre szolgál.

Az alábbi kódrészlet bemutatja, hogyan implementálhat egy függvényt StartLogin a bejelentkezési folyamat elindításához. A StartLogin függvény egy resourceUrl, state és display értéket vesz fel. A függvényben hozzon létre egy olyan fájlt AuthorizeUrl , amely összefűzi a GitHub engedélyezési URL-címét a következő paraméterekkel:

• client_id: A Bővítmény GitHubon való regisztrálása után az ügyfél-azonosítót a GitHub alkalmazásoldalán kapja meg.
• scope: A hatókör beállítása "user, repo" értékre. Ez beállítja a felhasználó engedélyezési hatókörét (vagyis azt, amelyhez az alkalmazás hozzá szeretne férni).
• state: Egy belső érték, amelyet az M motor átad.
• redirect_uri: Beállítás: 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
            ];

Ha ez az első alkalom, hogy a felhasználó bejelentkezik az alkalmazással (amelyet annak client_id értéke azonosít), megjelenik egy oldal, amely arra kéri őket, hogy adjanak hozzáférést az alkalmazáshoz. A későbbi bejelentkezési kísérletek a hitelesítő adataikat kérik.

3. lépés – A GitHubtól kapott kód átalakítása access_token

Ha a felhasználó befejezi a hitelesítési folyamatot, a GitHub visszairányítja a Power BI átirányítási URL-címére egy code paraméter ideiglenes kódjával, valamint a paraméter előző lépésében state megadott állapottal. A FinishLogin függvény kinyeri a kódot a callbackUri paraméterből, majd kicseréli egy hozzáférési jogkivonatra (a TokenMethod függvény használatával).

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

A GitHub hozzáférési jogkivonatának lekéréséhez át kell adnia az ideiglenes kódot a GitHub engedélyezési válaszából. A függvényben TokenMethod POST kérést fogalmaz meg a GitHub access_token végpontjára (https://github.com/login/oauth/access_token). A GitHub-végponthoz a következő paraméterek szükségesek:

Név	Típus	Description
client_id	karakterlánc	Kötelező. A GitHubról a regisztrációkor kapott ügyfélazonosító.
client_secret	karakterlánc	Kötelező. A GitHubról a regisztrációkor kapott ügyféltitk.
kód	karakterlánc	Kötelező. A kapott FinishLoginkód.
redirect_uri	karakterlánc	Az alkalmazás URL-címe, ahová a felhasználók az engedélyezés után kerülnek. Az átirányítási URL-címekről az alábbi részletekben olvashat.

Íme a Web.Contents híváshoz használt paraméterek részletei.

Argument	Description	Érték
URL-cím	A webhely URL-címe.	https://github.com/login/oauth/access_token
options	A függvény viselkedését vezérlő rekord.	Ebben az esetben nem használatos
Query	Programozott módon adjon hozzá lekérdezési paramétereket az URL-címhez.	Content = Text.ToBinary( Uri.BuildQueryString( [ client_id = client_id, client_secret = client_secret, code = code, redirect_uri = redirect_uri ] )) Where client_id: Ügyfélazonosító a GitHub alkalmazásoldaláról. client_secret: Ügyfélkód a GitHub alkalmazásoldaláról. code: Kód a GitHub engedélyezési válaszában. redirect_uri: Az alkalmazás URL-címe, ahol a felhasználók az engedélyezés után lesznek elküldve.
Fejlécek	Egy rekord további fejlécekkel a HTTP-kéréshez.	Fejlécek= [ #"Content-type" = "application/x-www-form-urlencoded", #"Accept" = "application/json" ]

Ez a kódrészlet azt ismerteti, hogyan implementálhat függvényt TokenMethod a hozzáférési jogkivonat hitelesítési kódjának cseréjéhez.

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;

A szolgáltatás JSON-válasza egy access_token mezőt tartalmaz. A TokenMethod metódus a JSON-választ M rekordmá alakítja a Json.Document használatával, és visszaadja a motornak.

Mintaválasz:

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

4. lépés – A GitHub API-t elérő függvények meghatározása

Az alábbi kódrészlet két függvényt exportál (GithubSample.Contents és GithubSample.PagedTable) úgy, hogy megjelöli őket, sharedés társítja őket az GithubSample adatforrás típusához.

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

A GithubSample.Contents függvény a felhasználói felületen is közzé lesz téve (lehetővé téve, hogy megjelenjen az Adatok lekérése párbeszédpanelen). A Value.ReplaceType függvénnyel a függvényparamétert a Url.Type hozzárendelt típusra állíthatja be.

Ha ezeket a függvényeket az GithubSample adatforrás típusával társítja, automatikusan a felhasználó által megadott hitelesítő adatokat fogják használni. A bővíthetőség érdekében engedélyezett M-kódtár-függvények (például a Web.Contents) is automatikusan öröklik ezeket a hitelesítő adatokat.

A hitelesítő adatok és a hitelesítés működésével kapcsolatos további részletekért lásd: A hitelesítés kezelése.

Minta URL-cím

Ez az összekötő képes formázott adatokat lekérni bármelyik GitHub v3 REST API-végpontról. Az adatösszekötők adattárában az összes véglegesítés lekérésére szolgáló lekérdezés például így néz ki:

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