GitHub Connectorvoorbeeld
De GitHub M-extensie laat zien hoe u ondersteuning toevoegt voor een OAuth 2.0-protocolverificatiestroom. Meer informatie over de specifieke informatie over de verificatiestroom van GitHub kunt u vinden op 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 bestanden en vervangen door de juiste waarden client_id client_secret voor uw app.
Opmerking over compatibiliteitsproblemen in Visual Studio: de Power Query SDK maakt gebruik van een Internet Explorer op basis van een besturingselement voor pop-up van OAuth-dialoogvensters. GitHub heeft de ondersteuning voor de versie van IE die door dit besturingselement wordt gebruikt, afgeschaft, waardoor u de machtigingsverkening voor uw app niet kunt voltooien als deze wordt uitgevoerd vanuit Visual Studio. U kunt de extensie ook laden met Power BI Desktop en daar de eerste OAuth-stroom voltooien. 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 delegatie van referenties. Door zich aan te melden bij GitHub en de toepassing te autoriseren die u voor GitHub maakt, staat de gebruiker uw toepassing toe om zich namens hen aan te melden om gegevens op te halen in Power BI. Aan de toepassing moeten rechten worden verleend om gegevens op te halen (een access_token ophalen) en om de gegevens volgens een schema te vernieuwen (een refresh_token ophalen en refresh_token). Uw 'toepassing' in deze context is uw gegevensconnector die wordt gebruikt om query's uit te voeren binnen Power BI. Power BI de opslag en het beheer van access_token en refresh_token namens u.
Notitie
Als u Power BI wilt toestaan de omleidings-URL te verkrijgen access_token gebruiken, moet u de omleidings-URL opgeven als https://oauth.powerbi.com/views/oauthredirect.html .
Wanneer u deze URL opgeeft en GitHub machtigingen verifieert en verleent, wordt GitHub omgeleid naar het oauthredirect-eindpunt van PowerBI, zodat Power BI de access_token en refresh_token kan ophalen.
Een app voor GitHub registreren
Uw Power BI moet zich aanmelden bij GitHub. Als u dit wilt inschakelen, registreert u een nieuwe OAuth-toepassing met GitHub op https://github.com/settings/applications/new .
Application name: Voer een naam in voor de toepassing voor uw M-extensie.Authorization callback URL: Voer https://oauth.powerbi.com/views/oauthredirect.html in.Scope: Stel GitHub in opuser, repo.
Notitie
Aan een geregistreerde OAuth-toepassing worden een unieke client-id en een clientgeheim toegewezen. Het clientgeheim mag niet worden gedeeld. U krijgt de client-id en het clientgeheim op de pagina GitHub clienttoepassing. Werk de bestanden in uw Data Connector-project bij met de client-id client_id (bestand) en het clientgeheim client_secret (bestand).
OAuth GitHub implementeren
In dit voorbeeld doorloop u de volgende stappen:
- Maak een definitie van Het soort gegevensbron die declareer dat deze OAuth ondersteunt.
- Geef details op zodat de M-engine de OAuth-stroom () kan
StartLoginstarten. - Converteert de code die is ontvangen van GitHub naar een access_token (
FinishLoginenTokenMethod). - Functies definiëren die toegang hebben tot GitHub API (
GithubSample.Contents).
Stap 1: een gegevensbrondefinitie maken
Een gegevensconnector begint met een record waarin de extensie wordt beschreven, met inbegrip van de unieke naam (dit is de naam van de record), ondersteunde verificatietype(s) en een beschrijvende weergavenaam (label) voor de gegevensbron.
Bij het ondersteunen van OAuth bevat de definitie de functies die het OAuth-contract in dit geval — implementeren, 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 pagina https://github.com/login/oauth/authorize leidt.
De gebruiker kan zich alleen aanmelden als u een aantal queryparameters opgeeft:
| Naam | 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 naar worden verzonden na autorisatie. Zie de details hieronder over omleidings-URL's. Voor M-extensies redirect_uri moet " https://oauth.powerbi.com/views/oauthredirect.html " zijn. |
| scope | tekenreeks | Een door komma's gescheiden lijst met scopes. Als dit niet is opgegeven, wordt het bereik standaard ingesteld op een lege lijst met scopes voor gebruikers die geen geldig token voor de app hebben. Voor gebruikers die al een geldig token voor de app hebben, wordt de OAuth-autorisatiepagina met de lijst met scopes niet weergegeven. In plaats daarvan wordt deze stap van de stroom automatisch voltooid met dezelfde scopes die de laatste keer zijn gebruikt dat de gebruiker de stroom heeft voltooid. |
| staat | tekenreeks | Een niet-gissende willekeurige tekenreeks. Het wordt gebruikt om te beveiligen tegen aanvallen met aanvraagvervalsing op andere plaatsen. |
In het volgende codefragment wordt beschreven hoe u een functie StartLogin implementeert om de aanmeldingsstroom te starten.
Een StartLogin functie heeft de waarde , en resourceUrl state display .
Maak in de functie een die AuthorizeUrl de url samenvoegt GitHub met de volgende parameters:
client_id: U krijgt de client-id nadat u de extensie hebt geregistreerd bij GitHub de GitHub toepassingspagina.scope: Stel bereik in op "user, repo". Hiermee stelt u het autorisatiebereik (dat wil zeggen, wat uw app wil openen) in voor de gebruiker.state: Een interne waarde die door de M-engine wordt door geven.redirect_uri: stel in 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 bij uw app aanlogt (aangeduid met de waarde), wordt er een pagina weergegeven waarin wordt gevraagd om toegang te verlenen client_id tot uw app. Bij volgende aanmeldingspogingen wordt gewoon om hun referenties gevraagd.
Stap 3: converteert de code die is ontvangen van GitHub naar een access_token
Als de gebruiker de verificatiestroom voltooit, wordt GitHub teruggeleid naar de omleidings-URL van Power BI met een tijdelijke code in een parameter, evenals de status die u in de vorige stap in een parameter hebt code state opgegeven. Met FinishLogin uw functie wordt de code uit de parameter callbackUri geëxtrahed en vervolgens omwisseld voor een toegangs token (met behulp van de TokenMethod functie ).
FinishLogin = (context, callbackUri, state) =>
let
Parts = Uri.Parts(callbackUri)[Query]
in
TokenMethod(Parts[code]);
Als u een GitHub-toegangs token wilt krijgen, geeft u de tijdelijke code door van de GitHub Authorize Response. In de TokenMethod functie formuleert u een POST-aanvraag voor GitHub van access_token eindpunt ( https://github.com/login/oauth/access_token ).
De volgende parameters zijn vereist voor het GitHub eindpunt:
| Naam | 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 in FinishLogin . |
| redirect_uri | tekenreeks | De URL in uw app waar gebruikers naar worden verzonden na autorisatie. Hieronder vindt u meer informatie over omleidings-URL's. |
Hier zijn de parameters die worden gebruikt voor de aanroep Web.Contents.
| Argument | Description | Waarde |
|---|---|---|
| url | De URL voor de website. | https://github.com/login/oauth/access_token |
| opties | Een record om het gedrag van deze functie te bepalen. | In dit geval niet gebruikt |
| Query’s uitvoeren | Voeg programmatisch queryparameters toe aan de URL. | Content = Text.ToBinary(Waar
|
| Kopteksten | Een record met extra headers voor de HTTP-aanvraag. | Headers= [ |
In dit codefragment wordt beschreven hoe u een functie implementeert om een TokenMethod auth-code voor een toegangsteken uit te wisselen.
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.Documenten retourneert dit naar de engine.
Voorbeeldreactie:
{
"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a",
"scope":"user,repo",
"token_type":"bearer"
}
Stap 4: functies definiëren die toegang hebben tot GitHub API
Met het volgende codefragment exporteert u twee functies ( en ) door ze te markeren als en koppelt u deze GithubSample.Contents GithubSample.PagedTable aan het Soort shared GithubSample gegevensbron.
[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 naar de gebruikersinterface (zodat deze kan worden weergegeven in het dialoogvenster Gegevens verzamelen). De functie Value.ReplaceType wordt gebruikt om de functieparameter in te stellen op Url.Type het toegekende type.
Door deze functies te koppelen aan het soort gegevensbron, gebruiken ze automatisch de referenties die de gebruiker GithubSample heeft opgegeven. Alle functies van de M-bibliotheek die zijn ingeschakeld voor extensibility (zoals Web.Contents), nemen deze referenties ook automatisch over.
Zie Verificatie verwerken voor meer informatie over de manier waarop referenties en verificatie werken.
Voorbeeld-URL
Met deze connector kunnen opgemaakte gegevens worden opgehaald uit elk van de GitHub v3 REST API eindpunten. De query voor het pullen van alle commits naar de gegevensconnector-repo ziet er bijvoorbeeld als volgende uit:
GithubSample.Contents("https://api.github.com/repos/microsoft/dataconnectors/commits")