GitHub Connector Beispiel

Artikel
10/05/2023

Die GitHub M-Erweiterung zeigt, wie man Unterstützung für einen OAuth 2.0-Protokoll-Authentifizierungsablauf hinzufügen kann. Sie können mehr über die Besonderheiten des Authentifizierungsablaufs von GitHub auf der GitHub Developer Site erfahren.

Bevor Sie mit der Erstellung einer M-Erweiterung beginnen, müssen Sie eine neue App auf GitHub registrieren und die Dateien client_id und client_secret durch die entsprechenden Werte für Ihre App ersetzen.

Hinweis zu Kompatibilitätsproblemen in Visual Studio:Das Power Query SDK verwendet ein auf Internet Explorer basierendes Steuerelement, um OAuth-Dialogfelder aufzurufen. GitHub hat die Unterstützung für die von diesem Steuerelement verwendete IE-Version veraltet, was Sie daran hindert, die Berechtigungserteilung für Ihre Anwendung abzuschließen, wenn sie von Visual Studio aus ausgeführt wird. Eine Alternative besteht darin, die Erweiterung mit Power BI Desktop zu laden und den ersten OAuth-Flow dort durchzuführen. Nachdem Ihrer Anwendung der Zugriff auf Ihr Konto gewährt wurde, funktionieren nachfolgende Anmeldungen über Visual Studio problemlos.

OAuth und Power BI

OAuth ist eine Form der Delegation von Anmeldedaten. Durch die Anmeldung bei GitHub und die Autorisierung der „Anwendung“, die Sie für GitHub erstellen, erlaubt der Benutzer Ihrer „Anwendung“, sich in seinem Namen anzumelden, um Daten in Power BI abzurufen. Der „Anwendung“ muss das Recht eingeräumt werden, Daten abzurufen (ein access_token erhalten) und die Daten nach einem Zeitplan zu aktualisieren (ein refresh_token erhalten und verwenden). Ihre „Anwendung“ ist in diesem Zusammenhang Ihr Data Connector, mit dem Sie Abfragen in Power BI ausführen. Power BI speichert und verwaltet das access_token und refresh_token in Ihrem Namen.

Hinweis

Damit Power BI den access_token erhalten und verwenden kann, müssen Sie die Umleitungsurl als https://oauth.powerbi.com/views/oauthredirect.html angeben.

Wenn Sie diese URL angeben und GitHub sich erfolgreich authentifiziert und Berechtigungen erteilt, leitet GitHub zum oauthredirect-Endpunkt von PowerBI um, damit Power BI das access_token und refresh_token abrufen kann.

So registrieren Sie eine GitHub-Anwendung

Ihre Power BI-Erweiterung muss sich bei GitHub anmelden. Registrieren Sie zum Aktivieren eine neue OAuth-Anwendung bei GitHub unter https://github.com/settings/applications/new.

Application name: Geben Sie einen Namen für die Anwendung für Ihre M-Erweiterung ein.
Authorization callback URL: Geben Sie https://oauth.powerbi.com/views/oauthredirect.html ein.
Scope: In GitHub setzen Sie den Bereich auf user, repo.

Hinweis

Einer registrierten OAuth-Anwendung wird eine eindeutige Client-ID und ein Client-Geheimnis zugewiesen. Das Client Secret sollte nicht weitergegeben werden. Sie erhalten die Client-ID und das Client-Geheimnis von der GitHub-Anwendungsseite. Aktualisieren Sie die Dateien in Ihrem Data Connector Projekt mit der Client ID (client_id Datei) und dem Client Secret (client_secret Datei).

Wie man GitHub OAuth implementiert

In diesem Beispiel werden Sie durch die folgenden Schritte geführt:

Erstellen Sie eine Datenquellenart-Definition, die erklärt, dass sie OAuth unterstützt.
Geben Sie Details an, damit die M-Engine den OAuth-Flow starten kann (StartLogin).
Wandeln Sie den von GitHub erhaltenen Code in ein access_token um (FinishLogin und TokenMethod).
Definieren Sie Funktionen, die auf die GitHub-API (GithubSample.Contents) zugreifen.

Schritt 1: Erstellen einer Datenquellendefinition

Ein Data Connector beginnt mit einem Datensatz, der die Erweiterung beschreibt, einschließlich des eindeutigen Namens (der der Name des Datensatzes ist), der unterstützten Authentifizierungsart(en) und eines freundlichen Anzeigenamens (Label) für die Datenquelle. Wenn OAuth unterstützt wird, enthält die Definition die Funktionen, die den OAuth-Vertrag implementieren - in diesem Fall StartLogin und FinishLogin.

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

Schritt 2 - Angabe von Details, damit die M-Engine den OAuth-Flow starten kann

Der GitHub OAuth-Fluss beginnt, wenn Sie Benutzer auf die Seite https://github.com/login/oauth/authorize leiten. Damit sich der Benutzer anmelden kann, müssen Sie eine Reihe von Abfrageparametern angeben:

Name	Typ	Beschreibung
client_id	Zeichenfolge	Erforderlich. Die Client-ID, die Sie bei Ihrer Registrierung von GitHub erhalten haben.
redirect_uri	Zeichenfolge	Die URL in Ihrer Anwendung, an die Benutzer nach der Autorisierung weitergeleitet werden. Einzelheiten zu den Umleitungs-URLs finden Sie nachfolgend. Bei M-Erweiterungen muss die `redirect_uri` "https://oauth.powerbi.com/views/oauthredirect.html" sein.
scope	Zeichenfolge	Eine durch Kommata getrennte Liste von Geltungsbereichen. Wenn nichts angegeben wird, ist scope standardmäßig eine leere Liste von Bereichen für Benutzer, die kein gültiges Token für die Anwendung haben. Für Benutzer, die bereits ein gültiges Token für die App haben, wird dem Benutzer die OAuth-Autorisierungsseite mit der Liste der Bereiche nicht angezeigt. Stattdessen wird dieser Schritt des Ablaufs automatisch mit denselben Bereichen abgeschlossen, die beim letzten Mal verwendet wurden, als der Benutzer den Ablauf abgeschlossen hat.
state	Zeichenfolge	Eine nicht ermittelbare Zufallszeichenfolge. Es wird zum Schutz vor Cross-Site-Request-Forgery-Angriffen verwendet.

Der folgende Codeschnipsel beschreibt, wie eine StartLogin Funktion implementiert wird, um den Anmeldevorgang zu starten. Eine Funktion StartLogin nimmt einen resourceUrl-, state- und einen display-Wert an. Erstellen Sie in der Funktion eine AuthorizeUrl, die die GitHub-Autorisierungs-URL mit den folgenden Parametern verknüpft:

client_id: Sie erhalten die Client-ID, nachdem Sie Ihre Erweiterung bei GitHub auf der GitHub-Anwendungsseite registriert haben.
scope: Setzen Sie den Geltungsbereich auf "user, repo". Damit wird der Berechtigungsbereich (d. h. das, worauf Ihre Anwendung zugreifen möchte) für den Benutzer festgelegt.
state: Ein interner Wert, der von der M-Engine eingegeben wird.
redirect_uri: Stellen Sie auf https://oauth.powerbi.com/views/oauthredirect.html ein.

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
            ];

Wenn dies das erste Mal ist, dass sich der Benutzer mit Ihrer App anmeldet (identifiziert durch den Wert client_id ), wird er eine Seite sehen, die ihn auffordert, den Zugriff auf Ihre App zu gewähren. Bei weiteren Anmeldeversuchen werden sie einfach nach ihren Anmeldedaten gefragt.

Schritt 3 - Umwandlung des von GitHub erhaltenen Codes in ein access_token

Wenn der Benutzer den Authentifizierungsvorgang abschließt, leitet GitHub zurück zur Power BI-Umleitungs-URL mit einem temporären Code in einem code -Parameter sowie dem Status, den Sie im vorherigen Schritt in einem state -Parameter angegeben haben. Ihre Funktion FinishLogin extrahiert den Code aus dem Parameter callbackUri und tauscht ihn dann gegen ein Zugriffstoken aus (unter Verwendung der Funktion TokenMethod ).

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

Um ein GitHub-Zugangs-Token zu erhalten, übergeben Sie den temporären Code aus der GitHub-Autorisierungsantwort. In der Funktion TokenMethod formulieren Sie eine POST-Anfrage an den access_token-Endpunkt von GitHub (https://github.com/login/oauth/access_token). Die folgenden Parameter sind für den GitHub-Endpunkt erforderlich:

Name	Typ	Beschreibung
client_id	Zeichenfolge	Erforderlich. Die Client-ID, die Sie bei Ihrer Registrierung von GitHub erhalten haben.
client_secret	Zeichenfolge	Erforderlich. Das Client-Geheimnis, das Sie bei Ihrer Registrierung von GitHub erhalten haben.
code	Zeichenfolge	Erforderlich. Der Code, den Sie unter `FinishLogin` erhalten haben.
redirect_uri	Zeichenfolge	Die URL in Ihrer Anwendung, an die Benutzer nach der Autorisierung weitergeleitet werden. Einzelheiten zu den Umleitungs-URLs finden Sie nachfolgend.

Hier sind die Details der verwendeten Parameter für den Aufruf von Web.Contents.

Argument	Beschreibung	Wert
url	Die URL für die Website.	https://github.com/login/oauth/access_token
Optionen	Ein Datensatz zur Steuerung des Verhaltens dieser Funktion.	In diesem Fall nicht verwendet
Abfrage	Fügen Sie der URL programmatisch Abfrageparameter hinzu.	`Inhalt = Text.ToBinary( Uri.BuildQueryString( [ client_id = client_id, client_secret = client_secret, code = Code, redirect_uri = redirect_uri ] ))` Hierbei gilt: `client_id`: Client-ID von der GitHub-Anwendungsseite. `client_secret`: Client-Geheimnis von der GitHub-Anwendungsseite. `code`: Code in der GitHub-Autorisierungsantwort. `redirect_uri`: Die URL in Ihrer Anwendung, an die Benutzer nach der Autorisierung weitergeleitet werden.
Kopfzeilen	Ein Datensatz mit zusätzlichen Kopfzeilen für die HTTP-Anfrage.	`Kopfzeilen= [ #„Content-type“ = „application/x-www-form-urlencoded“, #Accept„ = “application/json" ]`

Dieses Codeschnipsel beschreibt, wie man eine TokenMethod Funktion implementiert, um einen Authentifizierungscode gegen ein Zugriffstoken auszutauschen.

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;

Die JSON-Antwort des Dienstes enthält ein access_token-Feld. Die Methode TokenMethod wandelt die JSON-Antwort mit Json.Document in einen M-Datensatz um und gibt ihn an die Engine zurück.

Beispielantwort:

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

Schritt 4 - Definieren von Funktionen, die auf die GitHub-API zugreifen

Das folgende Codeschnipsel exportiert zwei Funktionen (GithubSample.Contents und GithubSample.PagedTable), indem es sie als shared markiert und sie mit der Datenquelle GithubSample verknüpft.

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

Die Funktion GithubSample.Contents wird auch auf der Benutzeroberfläche veröffentlicht (sodass sie im Dialog Daten abrufen erscheint). Die Funktion Value.ReplaceType wird verwendet, um den Funktionsparameter auf den Url.Type zugeschriebenen Typ zu setzen.

Indem diese Funktionen mit dem Datenquellentyp GithubSample verknüpft werden, verwenden sie automatisch die Anmeldeinformationen, die der Benutzer angegeben hat. Alle M-Bibliotheksfunktionen, die für die Erweiterbarkeit aktiviert wurden (z. B. Web.Contents), erben automatisch auch diese Anmeldeinformationen.

Weitere Einzelheiten zur Funktionsweise von Anmeldeinformationen und Authentifizierung finden Sie unter Handhabung der Authentifizierung.

Beispiel-URL

Dieser Connector ist in der Lage, formatierte Daten von jedem der GitHub v3 REST API-Endpunkte abzurufen. Die Abfrage, um alle Commits zum Data Connectors Repository zu erhalten, würde zum Beispiel wie folgt aussehen:

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

Freigeben über