Delen via

Voorbeeld van GitHub-connector

  • Artikel

De GitHub M-extensie laat zien hoe u ondersteuning toevoegt voor een OAuth 2.0-protocolverificatiestroom. Meer informatie over de specifieke kenmerken van de verificatiestroom van GitHub vindt u op de GitHub Developer-site.

Voordat u aan de slag gaat met het maken van een M-extensie, moet u een nieuwe app registreren op GitHub en de client_id bestanden client_secret vervangen door de juiste waarden voor uw app.

Opmerking over compatibiliteitsproblemen in Visual Studio: de Power Query SDK maakt gebruik van een op Internet Explorer gebaseerd besturingselement voor het pop-upvenster van OAuth. GitHub heeft de ondersteuning voor de versie van IE die door dit besturingselement wordt gebruikt afgeschaft, waardoor u de machtigingstoekenning voor uw app niet kunt voltooien als deze wordt uitgevoerd vanuit Visual Studio. Een alternatief is het laden van de extensie met Power BI Desktop en het voltooien van de eerste OAuth-stroom daar. Nadat uw toepassing toegang heeft gekregen tot uw account, werken volgende aanmeldingen prima vanuit Visual Studio.

OAuth en Power BI

OAuth is een vorm van referentiesdelegering. Door u aan te melden bij GitHub en de toepassing te autoriseren die u voor GitHub maakt, staat de gebruiker toe dat uw 'toepassing' zich namens hen kan aanmelden om gegevens op te halen in Power BI. De toepassing moet rechten krijgen om gegevens op te halen (een access_token ophalen) en om de gegevens volgens een schema te vernieuwen (een refresh_token ophalen en gebruiken). Uw 'toepassing' in deze context is uw gegevensconnector die wordt gebruikt om query's uit te voeren in Power BI. Power BI slaat de access_token en refresh_token namens u op en beheert deze.

Notitie

Als u wilt toestaan dat Power BI de access_token kan verkrijgen en gebruiken, moet u de omleidings-URL opgeven als https://oauth.powerbi.com/views/oauthredirect.html.

Wanneer u deze URL opgeeft en GitHub machtigingen heeft geverifieerd en verleend, wordt GitHub omgeleid naar het oauthredirect-eindpunt van Power BI, zodat Power BI de access_token en refresh_token kan ophalen.

Een GitHub-app registreren

Uw Power BI-extensie moet zich aanmelden bij GitHub. Als u dit wilt inschakelen, registreert u een nieuwe OAuth-toepassing bij GitHub op https://github.com/settings/applications/new.

  1. Application name: Voer een naam in voor de toepassing voor uw M-extensie.
  2. Authorization callback URL: Voer in https://oauth.powerbi.com/views/oauthredirect.html.
  3. Scope: Stel in GitHub het bereik in op user, repo.

Notitie

Aan een geregistreerde OAuth-toepassing wordt een unieke client-id en clientgeheim toegewezen. Het clientgeheim mag niet worden gedeeld. U krijgt de client-id en het clientgeheim op de gitHub-toepassingspagina. Werk de bestanden in uw gegevensconnectorproject bij met de client-id (client_id bestand) en clientgeheim (client_secret bestand).

GitHub OAuth implementeren

In dit voorbeeld worden de volgende stappen beschreven:

  1. Maak een definitie van het type gegevensbron waarmee wordt aangegeven dat deze ondersteuning biedt voor OAuth.
  2. Geef details op zodat de M-engine de OAuth-stroom (StartLogin) kan starten.
  3. Converteer de code die u van GitHub hebt ontvangen naar een access_token (FinishLogin en TokenMethod).
  4. Definieer functies die toegang hebben tot de GitHub-API (GithubSample.Contents).

Stap 1: een definitie van een gegevensbron maken

Een gegevensconnector begint met een record die de extensie beschrijft, inclusief de unieke naam (de naam van de record), ondersteunde verificatietypen en een beschrijvende weergavenaam (label) voor de gegevensbron. Bij het ondersteunen van OAuth bevat de definitie de functies die het OAuth-contract implementeren, in dit geval StartLogin en FinishLogin.

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

Stap 2: geef details op zodat de M-engine de OAuth-stroom kan starten

De GitHub OAuth-stroom wordt gestart wanneer u gebruikers naar de https://github.com/login/oauth/authorize pagina leidt. Als de gebruiker zich aanmeldt, moet u een aantal queryparameters opgeven:

Name Type Description
client_id tekenreeks Vereist. De client-id die u hebt ontvangen van GitHub toen u zich registreerde.
redirect_uri tekenreeks De URL in uw app waar gebruikers na autorisatie worden verzonden. Hieronder vindt u meer informatie over omleidings-URL's. Voor M-extensies moet de ' redirect_uri ;' zijnhttps://oauth.powerbi.com/views/oauthredirect.html".
bereik tekenreeks Een door komma's gescheiden lijst met bereiken. Als dit niet is opgegeven, wordt het bereik standaard ingesteld op een lege lijst met bereiken voor gebruikers die geen geldig token voor de app hebben. Voor gebruikers die al een geldig token voor de app hebben, wordt de gebruiker niet weergegeven op de pagina OAuth-autorisatie met de lijst met bereiken. In plaats daarvan wordt deze stap van de stroom automatisch voltooid met dezelfde bereiken die de laatste keer zijn gebruikt dat de gebruiker de stroom heeft voltooid.
staat tekenreeks Een niet te raden willekeurige tekenreeks. Het wordt gebruikt om te beschermen tegen aanvallen met vervalsing van aanvragen op meerdere sites.

In het volgende codefragment wordt beschreven hoe u een StartLogin functie implementeert om de aanmeldingsstroom te starten. Een StartLogin functie heeft een resourceUrl, stateen display waarde. Maak in de functie een AuthorizeUrl url die de GitHub-autorisatie-URL samenvoegt met de volgende parameters:

  • client_id: U krijgt de client-id nadat u uw extensie bij GitHub hebt geregistreerd vanaf de GitHub-toepassingspagina.
  • scope: Stel het bereik in op 'user, repo'. Hiermee stelt u het autorisatiebereik in (dat wil de app openen) voor de gebruiker.
  • state: Een interne waarde die de M-motor doorgeeft.
  • redirect_uri: Ingesteld op 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
            ];

Als dit de eerste keer is dat de gebruiker zich aanmeldt met uw app (geïdentificeerd met client_id de waarde), ziet hij een pagina waarin wordt gevraagd om toegang te verlenen tot uw app. Volgende aanmeldingspogingen vragen gewoon om hun referenties.

Stap 3: converteer de code die u van GitHub hebt ontvangen naar een access_token

Als de gebruiker de verificatiestroom voltooit, wordt GitHub omgeleid naar de omleidings-URL van Power BI met een tijdelijke code in een code parameter, evenals de status die u in de vorige stap in een state parameter hebt opgegeven. Met uw FinishLogin functie wordt de code uit de callbackUri parameter geëxtraheerd en vervolgens uitgewisseld voor een toegangstoken (met behulp van de TokenMethod functie).

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

Als u een GitHub-toegangstoken wilt ophalen, geeft u de tijdelijke code van het GitHub-autorisatieantwoord door. In de TokenMethod functie formuleert u een POST-aanvraag naar het access_token-eindpunt (https://github.com/login/oauth/access_token) van GitHub. De volgende parameters zijn vereist voor het GitHub-eindpunt:

Name Type Description
client_id tekenreeks Vereist. De client-id die u hebt ontvangen van GitHub toen u zich registreerde.
client_secret tekenreeks Vereist. Het clientgeheim dat u hebt ontvangen van GitHub toen u zich registreerde.
code tekenreeks Vereist. De code die u hebt ontvangen.FinishLogin
redirect_uri tekenreeks De URL in uw app waar gebruikers na autorisatie worden verzonden. Hieronder vindt u meer informatie over omleidings-URL's.

Hier vindt u de details die worden gebruikt voor de aanroep Web.Contents .

Argument Beschrijving Waarde
URL De URL voor de website. https://github.com/login/oauth/access_token
Opties Een record voor het beheren van het gedrag van deze functie. Niet gebruikt in dit geval
Query Voeg programmatisch queryparameters toe aan de URL. Content = Text.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
code = code,
redirect_uri = redirect_uri
]
))
Waar
  • client_id: Client-id van de GitHub-toepassingspagina.
  • client_secret: Clientgeheim van de GitHub-toepassingspagina.
  • code: Code in gitHub-autorisatieantwoord.
  • redirect_uri: de URL in uw app waar gebruikers na autorisatie worden verzonden.
Kopteksten Een record met extra headers voor de HTTP-aanvraag. Headers = [
#"Content-type" = "application/x-www-form-urlencoded",
#"Accepteren" = "application/json"
]

In dit codefragment wordt beschreven hoe u een TokenMethod functie implementeert voor het uitwisselen van een verificatiecode voor een toegangstoken.

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;

Het JSON-antwoord van de service bevat een access_token veld. De TokenMethod methode converteert het JSON-antwoord naar een M-record met behulp van Json.Document en retourneert het naar de engine.

Voorbeeldantwoord:

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

Stap 4: Functies definiëren die toegang hebben tot de GitHub-API

Met het volgende codefragment worden twee functies (GithubSample.Contents en GithubSample.PagedTable) geëxporteerd door ze te markeren als shareden te koppelen aan het GithubSample gegevensbrontype.

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

De GithubSample.Contents functie wordt ook gepubliceerd in de gebruikersinterface (zodat deze kan worden weergegeven in het dialoogvenster Gegevens ophalen). De functie Value.ReplaceType wordt gebruikt om de functieparameter in te stellen op het Url.Type getscribeerde type.

Door deze functies te koppelen aan het GithubSample type gegevensbron, gebruiken ze automatisch de referenties die de gebruiker heeft opgegeven. Alle M-bibliotheekfuncties die zijn ingeschakeld voor uitbreidbaarheid (zoals Web.Contents), nemen deze referenties ook automatisch over.

Zie Verificatie verwerken voor meer informatie over de werking van referenties en verificatie.

Voorbeeld-URL

Deze connector kan opgemaakte gegevens ophalen uit alle GitHub v3 REST API-eindpunten. De query voor het ophalen van alle doorvoeringen naar de opslagplaats gegevensconnectors ziet er bijvoorbeeld als volgt uit:

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