Jaa

GitHub-liitinmalli

  • Artikkeli

GitHub M -laajennus näyttää, miten voit lisätä tuen OAuth 2.0 -protokollatodentamisen työnkululle. Saat lisätietoja GitHubin todennustyönkulun ominaisuuksista GitHub-kehittäjäsivustosta.

Ennen kuin aloitat M-laajennuksen luomisen, sinun on rekisteröitävä uusi sovellus GitHubissa ja korvattava client_id client_secret -tiedostot sovellukseen sopivilla arvoilla.

Huomautus Visual Studion yhteensopivuusongelmista: Power Query SDK käyttää Internet Exploreriin perustuvaa ohjausobjektia OAuth-valintaikkunoiden ponnahdusikkunassa. GitHub on poistanut käytöstä tämän ohjausobjektin käyttämän IE-version tuen, mikä estää sinua suorittamasta sovelluksesi käyttöoikeuden myöntämistä, jos sitä käytetään Visual Studiossa. Vaihtoehtoisesti voit ladata laajennuksen Power BI Desktopilla ja suorittaa siellä ensimmäisen OAuth-työnkulun. Kun sovelluksesi on myöntänyt tilillesi käyttöoikeuden, myöhemmät kirjautumiset toimivat hyvin Visual Studiosta.

OAuth ja Power BI

OAuth on tunnistetietojen delegoinnin muoto. Kirjautumalla sisään GitHubiin ja valtuuttamalla GitHubille luomasi "sovelluksen" käyttäjä antaa "sovelluksesi" kirjautua sisään puolestaan tietojen noutamiseksi Power BI:hin. Sovellukselle on myönnettävä oikeudet tietojen noutamiseen (access_token) ja tietojen päivittämiseen aikataulun mukaisesti (refresh_token noutaminen ja käyttäminen). Tässä kontekstissa sovelluksesi on tietoyhdistin, jota käytetään kyselyiden suorittamiseen Power BI:ssä. Power BI tallentaa ja hallitsee access_token ja refresh_token puolestasi.

Muistiinpano

Jotta Power BI voi hankkia access_token ja käyttää sitä, sinun on määritettävä uudelleenohjauksen URL-osoite muodossa https://oauth.powerbi.com/views/oauthredirect.html.

Kun määrität tämän URL-osoitteen ja GitHub todentaa ja myöntää käyttöoikeudet, GitHub ohjaa uudelleen PowerBI:n oauthredirect-päätepisteeseen, jotta Power BI voi noutaa access_token ja refresh_token.

GitHub-sovelluksen rekisteröiminen

Power BI -laajennuksen on kirjauduttava GitHubiin. Jos haluat ottaa tämän käyttöön, rekisteröi uusi OAuth-sovellus GitHubissa osoitteessa https://github.com/settings/applications/new.

  1. Application name: Anna sovellukselle nimi M-laajennukselle.
  2. Authorization callback URL: Kirjoita https://oauth.powerbi.com/views/oauthredirect.html.
  3. Scope: Määritä GitHubissa vaikutusalueen arvoksi user, repo.

Muistiinpano

Rekisteröidylle OAuth-sovellukselle määritetään yksilöivä asiakastunnus ja asiakkaan salasana. Asiakkaan salaista koodia ei pidä jakaa. Saat Asiakastunnuksen ja asiakkaan salasanan GitHub-sovellussivulta. Päivitä Data Connector -projektisi tiedostoilla Client ID (client_id tiedosto) ja Client Secret (client_secret tiedosto).

GitHub OAuthin käyttöönotto

Tässä mallissa käydään läpi seuraavat vaiheet:

  1. Luo tietolähteen lajimääritelmä, joka ilmoittaa tukevansa OAuth-todennusta.
  2. Anna tiedot, jotta M-moduuli voi käynnistää OAuth-työnkulun (StartLogin).
  3. Muunna GitHubista saatu koodi access_token (FinishLogin ja TokenMethod).
  4. Määritä funktiot, jotka käyttävät GitHub-ohjelmointirajapintaa (GithubSample.Contents).

Vaihe 1 – Luo tietolähteen määritys

Tietoyhdistin alkaa tietueella, joka kuvaa laajennusta, mukaan lukien sen yksilöivä nimi (joka on tietueen nimi), tuetut todennustyypit) ja kutsumanimi (selite) tietolähteelle. Kun tuet OAuth-todennusta, määritelmä sisältää funktiot, jotka toteuttavat OAuth-sopimuksen – tässä tapauksessa StartLogin ja FinishLogin.

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

Vaihe 2 – Anna tiedot, jotta M-moduuli voi käynnistää OAuth-työnkulun

GitHub OAuth -työnkulku käynnistyy, kun ohjaat käyttäjiä https://github.com/login/oauth/authorize sivulle. Jotta käyttäjä kirjautuu sisään, sinun on määritettävä joukko kyselyparametreja:

Nimi Laji Kuvaus
client_id merkkijono Pakollinen. Asiakastunnus, jonka sait GitHubista rekisteröityessäsi.
redirect_uri merkkijono Sovelluksessasi oleva URL-osoite, johon käyttäjät lähetetään valtuutuksen jälkeen. Lisätietoja uudelleenohjauksen URL-osoitteista on alla. M-laajennuksia redirect_uri varten on oltava "https://oauth.powerbi.com/views/oauthredirect.html".
laajuus merkkijono Pilkuin eroteltu luettelo vaikutusalueista. Jos vaikutusaluetta ei anneta, vaikutusalueena on tyhjä luettelo niiden käyttäjien vaikutusalueista, joilla ei ole kelvollista tunnusta sovellukselle. Käyttäjille, joilla on jo sovelluksen kelvollinen tunnus, käyttäjälle ei näytetä OAuth-valtuutussivua, jolla on luettelo vaikutusalueista. Sen sijaan työnkulun tämä vaihe täydentyy automaattisesti samoilla vaikutusalueilla, joita käytettiin, kun käyttäjä viimeksi suoritti työnkulun.
state merkkijono Arvailematon satunnaismerkkijono. Sitä käytetään suojautumiseen väärennöshyökkäyksiltä sivustojen välisiltä pyynnöiltä.

Seuraavassa koodikatkelmassa kuvataan, miten voit käynnistää kirjautumisen funktion StartLogin avulla. Funktiolla on -resourceUrl, state- ja display -StartLoginarvo. Luo -funktiossa - AuthorizeUrl toiminto, joka liittää GitHub-valtuutus-URL-osoitteen seuraavilla parametreilla:

  • client_id: Saat asiakastunnuksen, kun olet rekisteröinyt laajennuksen GitHubiin GitHub-sovellussivulta.
  • scope: Määritä vaikutusalueeksi "user, repo". Tämä määrittää valtuutuksen laajuuden (eli sen, mitä sovelluksesi haluaa käyttää) käyttäjälle.
  • state: Sisäinen arvo, jonka M-moduuli välittää.
  • redirect_uri: Määritä arvoksi 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
            ];

Jos käyttäjä kirjautua sisään sovellukseen ensimmäistä kertaa (sen client_id arvon mukaan tunnistettuna), hän näkee sivun, jossa häntä pyydetään myöntämään käyttöoikeus sovellukseen. Myöhemmissä kirjautumisyrityksissä pyydetään vain heidän tunnistetietojaan.

Vaihe 3 – Muunna GitHubista saatu koodi access_token

Jos käyttäjä suorittaa todennustyönkulun, GitHub uudelleenohjaa takaisin Power BI -uudelleenohjauksen URL-osoitteeseen parametrin tilapäisellä koodilla code sekä parametrin edellisessä vaiheessa state antamaasi tilaan. Funktio FinishLogin poimii koodin parametrista callbackUri ja vaihtaa sen käyttöoikeustietueeksi (funktion TokenMethod avulla).

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

Saat GitHub-käyttöoikeustietueen välittämällä tilapäisen koodin GitHub Authorize Response -kohteesta. Funktiossa TokenMethod muotoilet POST-pyynnön GitHubin access_token päätepisteeseen (https://github.com/login/oauth/access_token). GitHub-päätepisteeseen vaaditaan seuraavat parametrit:

Nimi Laji Kuvaus
client_id merkkijono Pakollinen. Asiakastunnus, jonka sait GitHubista rekisteröityessäsi.
client_secret merkkijono Pakollinen. Asiakassalaisuus, jonka sait GitHubista rekisteröityessäsi.
koodi merkkijono Pakollinen. Koodi, jonka sait kohteessa FinishLogin.
redirect_uri merkkijono Sovelluksessasi oleva URL-osoite, johon käyttäjät lähetetään valtuutuksen jälkeen. Lisätietoja uudelleenohjauksen URL-osoitteista on alla.

Tässä ovat Web.Contents-kutsun käytetyt parametrit.

Argumentti Kuvaus Arvo
URL-osoite Verkkosivuston URL-osoite. https://github.com/login/oauth/access_token
options Tietue, jolla ohjataan tämän funktion toimintaa. Ei käytetä tässä tapauksessa
Kysely Lisää kyselyparametrit ohjelmallisesti URL-osoitteeseen. Sisältö = Text.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
code = code,
redirect_uri = redirect_uri
]
))
Missä
  • client_id: Asiakastunnus GitHub-sovellussivulta.
  • client_secret: Asiakassalaisuus GitHub-sovellussivulta.
  • code: Koodi GitHub-valtuutuksen vastauksessa.
  • redirect_uri: Sovelluksessasi oleva URL-osoite, johon käyttäjät lähetetään valtuutuksen jälkeen.
Otsikot Tietue, jolla on lisäotsikot HTTP-pyynnölle. Headers= [
#"Content-type" = "application/x-www-form-urlencoded",
#"Hyväksy" = "application/json"
]

Tässä koodikatkelmassa kuvataan, miten voit toteuttaa funktion TokenMethod todennuskoodin vaihtamiseksi käyttöoikeustietueeksi.

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;

Palvelun JSON-vastaus sisältää access_token kentän. Menetelmä TokenMethod muuntaa JSON-vastauksen M-tietueeksi Json.Documentin avulla ja palauttaa sen moduuliin.

Mallivastaus:

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

Vaihe 4 – Määritä funktiot, jotka käyttävät GitHub-ohjelmointirajapintaa

Seuraava koodikatkelma vie kaksi funktiota (GithubSample.Contents ja GithubSample.PagedTable) merkitsemällä ne arvoiksi sharedja liittämällä ne tietolähteen GithubSample lajiin.

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

Funktio GithubSample.Contents julkaistaan myös käyttöliittymään (jolloin se näkyy Nouda tiedot -valintaikkunassa). Value.ReplaceType-funktion avulla funktion parametri määritetään määritetylle Url.Type tyypille.

Liittämällä nämä funktiot GithubSample tietolähdelajiin ne käyttävät automaattisesti käyttäjän antamia tunnistetietoja. Kaikki M-kirjastofunktiot, jotka on otettu käyttöön laajennettaviksi (kuten Web.Contents), perivät myös nämä tunnistetiedot automaattisesti.

Lisätietoja tunnistetietojen ja todentamisen toiminnasta on artikkelissa Todentamisen käsittely.

URL-malliosoite

Tämä liitin voi noutaa muotoiltuja tietoja mistä tahansa GitHub v3 REST -ohjelmointirajapinnan päätepisteestä. Esimerkiksi kysely, joka hakee kaikki vahvistukset tietoyhdistimien säilöön, näyttäisi seuraavalta:

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