Freigeben über

GitHub Connector-Beispiel

Die GitHub M-Erweiterung zeigt, wie Sie Unterstützung für einen OAuth 2.0-Protokollauthentifizierungsfluss hinzufügen. Weitere Informationen zu den Besonderheiten des Authentifizierungsflusses von GitHub finden Sie auf der GitHub-Dokumentationswebsite.

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

Hinweis zu Kompatibilitätsproblemen in Visual Studio:Das Power Query SDK verwendet ein internet Explorer-basiertes Steuerelement zum Popup-OAuth-Dialogfelder. GitHub hat die Unterstützung für die von diesem Steuerelement verwendete IE-Version nicht mehr unterstützt. Dadurch wird verhindert, dass Sie die Berechtigungserteilung für Ihre App abschließen, wenn sie in Visual Studio ausgeführt wird. Eine Alternative besteht darin, die Erweiterung mit Power BI Desktop zu laden und den ersten OAuth-Fluss dort abzuschließen. Nachdem Ihrer Anwendung Zugriff auf Ihr Konto gewährt wurde, funktionieren nachfolgende Anmeldungen von Visual Studio einwandfrei.

OAuth und Power BI

OAuth ist eine Form der Delegierung von Anmeldeinformationen. Wenn Sie sich bei GitHub anmelden und die "Anwendung" autorisieren, die Sie für GitHub erstellen, lässt der Benutzer Ihre "Anwendung" zu, sich in ihrem Auftrag anzumelden, um Daten in Power BI abzurufen. Der "Anwendung" muss Rechte zum Abrufen von Daten (abrufen eines access_token) und zum Aktualisieren der Daten in einem Zeitplan (Abrufen und Verwenden eines refresh_token) gewährt werden. Ihre "Anwendung" in diesem Kontext ist Ihr Datenconnector, der zum Ausführen von Abfragen in Power BI verwendet wird. Power BI speichert und verwaltet die access_token und refresh_token in Ihrem Auftrag.

Hinweis

Damit Power BI das access_token abrufen und verwenden kann, müssen Sie die Umleitungs-URL als https://oauth.powerbi.com/views/oauthredirect.html angeben.

Wenn Sie diese URL angeben und GitHub Berechtigungen erfolgreich authentifiziert und gewährt, leitet GitHub zum oauthredirect-Endpunkt von Power BI um, damit Power BI die access_token und refresh_token abrufen kann.

So registrieren Sie eine GitHub-App

Ihre Power BI-Erweiterung muss sich bei GitHub anmelden. Um dies zu aktivieren, registrieren Sie eine neue OAuth-Anwendung bei GitHub unter https://github.com/settings/applications/new.

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

Hinweis

Einer registrierten OAuth-Anwendung wird eine eindeutige Client-ID und ein geheimer Clientschlüssel zugewiesen. Der geheime Clientschlüssel sollte nicht freigegeben werden. Sie erhalten die Client-ID und den geheimen Clientschlüssel über die GitHub-Anwendungsseite. Aktualisieren Sie die Dateien in Ihrem Data Connector-Projekt mit der Client-ID (client_id Datei) und dem geheimen Clientschlüssel (client_secret Datei).

So implementieren Sie GitHub OAuth

Dieses Beispiel führt Sie durch die folgenden Schritte:

  1. Erstellen Sie eine Datenquellentypdefinition, die OAuth unterstützt.
  2. Geben Sie Details an, damit das M-Modul den OAuth-Fluss (StartLogin) starten kann.
  3. Konvertieren Sie den von GitHub empfangenen Code in eine access_token (FinishLogin und TokenMethod).
  4. Definieren von Funktionen, die auf die GitHub-API zugreifen (GithubSample.Contents).

Schritt 1 : Erstellen einer Datenquellendefinition

Ein Datenverbinder beginnt mit einem Datensatz, der die Erweiterung beschreibt, einschließlich des eindeutigen Namens (der der Name des Datensatzes ist), der unterstützten Authentifizierungstypen und eines benutzerfreundlichen Anzeigenamens (Bezeichnung) für die Datenquelle. Bei der Unterstützung von OAuth 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: Bereitstellen von Details, damit die M-Engine den OAuth-Ablauf starten kann

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

Name Typ Description
Kunden-ID Schnur Erforderlich. Die Client-ID, die Sie bei der Registrierung von GitHub erhalten haben.
Weiterleitungs-URI Schnur Die URL in Ihrer App, an die Benutzer nach der Autorisierung gesendet werden. Details zu Umleitungs-URLs finden Sie im Folgenden. Für M-Erweiterungen muss redirect_uri "https://oauth.powerbi.com/views/oauthredirect.html"";.
scope Schnur Eine durch Trennzeichen getrennte Liste von Bereichen. Wenn nicht angegeben, wird der Bereich standardmäßig auf eine leere Liste von Bereichen für Benutzer festgelegt, die kein gültiges Token für die App besitzen. Für Benutzer, die bereits über ein gültiges Token für die App verfügen, wird der Benutzer nicht die OAuth-Autorisierungsseite mit der Liste der Bereiche angezeigt. Stattdessen wird dieser Schritt des Flusses automatisch mit denselben Bereichen abgeschlossen, die zuletzt verwendet wurden, wenn der Benutzer den Fluss abgeschlossen hat.
Staat Schnur Eine nicht erratbare zufällige Zeichenfolge. Es wird verwendet, um vor websiteübergreifenden Anforderungsverfälschungsangriffen zu schützen.

Der folgende Codeausschnitt beschreibt, wie eine StartLogin Funktion implementiert wird, um den Anmeldefluss zu starten. Eine StartLogin-Funktion akzeptiert einen resourceUrl, state und display-Wert. Erstellen Sie in der Funktion eine AuthorizeUrl , die die GitHub-Autorisierungs-URL mit den folgenden Parametern verkettet:

  • client_id: Sie erhalten die Client-ID, nachdem Sie Ihre Erweiterung bei GitHub über die GitHub-Anwendungsseite registriert haben.
  • scope: Legen Sie den Bereich auf "user, repo" fest. Dadurch wird der Autorisierungsbereich festgelegt (d. h. worauf Ihre App zugreifen möchte) für den Benutzer.
  • state: Ein interner Wert, den die M-Engine übergibt.
  • redirect_uri: Auf .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
            ];

Wenn sich der Benutzer zum ersten Mal mit Ihrer App anmeldet (durch den client_id Wert identifiziert), wird eine Seite angezeigt, auf der er aufgefordert wird, Ihrer App Zugriff zu gewähren. Bei nachfolgenden Anmeldeversuchen werden ihre Anmeldeinformationen angefordert.

Schritt 3: Konvertieren des von GitHub empfangenen Codes in eine access_token

Wenn der Benutzer den Authentifizierungsfluss abgeschlossen hat, leitet GitHub zurück zur Power BI-Umleitungs-URL mit einem temporären Code in einem code Parameter sowie den Zustand, den Sie im vorherigen Schritt in einem state Parameter angegeben haben. Die FinishLogin Funktion extrahiert den Code aus dem callbackUri Parameter und wechselt ihn dann für ein Zugriffstoken (mithilfe der TokenMethod Funktion).

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

Um ein GitHub-Zugriffstoken abzurufen, übergeben Sie den temporären Code aus der GitHub Authorize Response. In der TokenMethod Funktion formulieren Sie eine POST-Anforderung an gitHubs access_token Endpunkt (https://github.com/login/oauth/access_token). Die folgenden Parameter sind für den GitHub-Endpunkt erforderlich:

Name Typ Description
Kunden-ID Schnur Erforderlich. Die Client-ID, die Sie bei der Registrierung von GitHub erhalten haben.
client_secret Schnur Erforderlich. Der geheime Clientschlüssel, den Sie bei der Registrierung von GitHub erhalten haben.
Code Schnur Erforderlich. Der Code, den Sie in FinishLogin empfangen haben.
Weiterleitungs-URI Schnur Die URL in Ihrer App, an die Benutzer nach der Autorisierung gesendet werden. Details zu den Umleitungs-URLs finden Sie im Folgenden.

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

Argument Description Wert
URL Die URL für die Website. https://github.com/login/oauth/access_token
options Ein Datensatz zum Steuern des Verhaltens dieser Funktion. In diesem Fall nicht verwendet
Query Fügen Sie der URL programmgesteuert Abfrageparameter hinzu. Content = Text.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
Code = Code,
redirect_uri = redirect_uri
]
))
Wobei
  • client_id: Client-ID von der GitHub-Anwendungsseite.
  • client_secret: Geheimer Clientschlüssel von der GitHub-Anwendungsseite.
  • code: Code in GitHub-Autorisierungsantwort.
  • redirect_uri: Die URL in Ihrer App, an die Benutzer nach der Autorisierung gesendet werden.
Headers Ein Datensatz mit zusätzlichen Headern für die HTTP-Anforderung. Headers= [
#"Content-type" = "application/x-www-form-urlencoded",
#"Accept" = "application/json"
]

Dieser Codeausschnitt beschreibt, wie eine TokenMethod Funktion implementiert wird, um einen Authentifizierungscode für 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 Diensts enthält ein access_token Feld. Die TokenMethod Methode konvertiert die JSON-Antwort in einen M-Eintrag mit Json.Document und gibt sie an das Modul zurück.

Beispielantwort:

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

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

Der folgende Codeausschnitt exportiert zwei Funktionen (GithubSample.Contents und GithubSample.PagedTable) durch Markieren sharedals , und ordnet sie dem GithubSample Datenquellentyp zu.

[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 GithubSample.Contents Funktion wird auch auf der Benutzeroberfläche veröffentlicht (sodass sie im Dialogfeld "Daten abrufen " angezeigt werden kann). Die Funktion Value.ReplaceType wird verwendet, um den Funktionsparameter auf den Url.Type zugewiesenen Typ festzulegen.

Durch das Zuordnen dieser Funktionen zum GithubSample Datenquellentyp werden automatisch die vom Benutzer bereitgestellten Anmeldeinformationen verwendet. Alle M-Bibliotheksfunktionen, die für die Erweiterbarkeit (z. B. Web.Contents) aktiviert wurden, erben diese Anmeldeinformationen automatisch.

Weitere Informationen zur Funktionsweise von Anmeldeinformationen und Authentifizierung finden Sie unter Umgang mit Authentifizierung.

Beispiel-URL

Dieser Connector kann formatierte Daten von einem der GitHub v3-REST-API-Endpunkte abrufen. Die Abfrage zum Abrufen aller Commits zum Datenconnectors-Repository würde beispielsweise wie folgt aussehen:

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