Przykład łącznika usługi GitHub

Artykuł
08/29/2023

Rozszerzenie GitHub M pokazuje, jak dodać obsługę przepływu uwierzytelniania protokołu OAuth 2.0. Więcej informacji na temat specyfiki przepływu uwierzytelniania usługi GitHub można dowiedzieć się w witrynie dla deweloperów usługi GitHub.

Przed rozpoczęciem tworzenia rozszerzenia języka M musisz zarejestrować nową aplikację w usłudze GitHub i zastąpić client_id pliki i client_secret odpowiednimi wartościami dla aplikacji.

Uwaga dotycząca problemów ze zgodnością w programie Visual Studio: zestaw POWER Query SDK używa kontrolki opartej na programie Internet Explorer do wyskakujących okien dialogowych protokołu OAuth. Usługa GitHub wycofała obsługę wersji programu IE używanej przez tę kontrolkę, co uniemożliwi ukończenie udzielania uprawnień dla aplikacji w przypadku uruchamiania z poziomu programu Visual Studio. Alternatywą jest załadowanie rozszerzenia za pomocą programu Power BI Desktop i ukończenie pierwszego przepływu OAuth. Po udzieleniu aplikacji dostępu do konta kolejne logowania będą działać prawidłowo z poziomu programu Visual Studio.

OAuth i Power BI

OAuth to forma delegowania poświadczeń. Logując się do usługi GitHub i autoryzując aplikację utworzoną dla usługi GitHub, użytkownik może zalogować się w ich imieniu w celu pobrania danych do usługi Power BI. "Aplikacja" musi mieć przyznane prawa do pobierania danych (uzyskiwanie access_token) i odświeżanie danych zgodnie z harmonogramem (pobieranie i używanie refresh_token). Twoja "aplikacja" w tym kontekście to Łącznik danych używany do uruchamiania zapytań w usłudze Power BI. Usługa Power BI przechowuje i zarządza access_token i refresh_token w Twoim imieniu.

Uwaga

Aby umożliwić usłudze Power BI uzyskiwanie i używanie access_token, należy określić adres URL przekierowania jako https://oauth.powerbi.com/views/oauthredirect.html.

Po określeniu tego adresu URL i usługi GitHub pomyślnie uwierzytelnia się i przyznajesz uprawnienia, usługa GitHub przekierowuje do punktu końcowego oauthredirect usługi Power BI, aby usługa Power BI mogła pobrać access_token i refresh_token.

Jak zarejestrować aplikację GitHub

Rozszerzenie usługi Power BI musi zalogować się do usługi GitHub. Aby to włączyć, zarejestruj nową aplikację OAuth w usłudze GitHub pod adresem https://github.com/settings/applications/new.

Application name: wprowadź nazwę aplikacji dla rozszerzenia M.
Authorization callback URL: Wprowadź .https://oauth.powerbi.com/views/oauthredirect.html
Scope: W usłudze GitHub ustaw zakres na user, repo.

Uwaga

Zarejestrowana aplikacja OAuth ma przypisany unikatowy identyfikator klienta i klucz tajny klienta. Klucz tajny klienta nie powinien być udostępniany. Identyfikator klienta i klucz tajny klienta są uzyskiwane ze strony aplikacji GitHub. Zaktualizuj pliki w projekcie łącznika danych przy użyciu identyfikatora klienta (client_id pliku) i klucza tajnego klienta (client_secret pliku).

Jak zaimplementować uwierzytelnianie OAuth w usłudze GitHub

Ten przykład przeprowadzi Cię przez następujące kroki:

Utwórz definicję rodzaju źródła danych, która deklaruje, że obsługuje protokół OAuth.
Podaj szczegóły, aby aparat M mógł uruchomić przepływ OAuth (StartLogin).
Przekonwertuj kod otrzymany z usługi GitHub na access_token (FinishLogin i TokenMethod).
Definiowanie funkcji, które uzyskują dostęp do interfejsu API usługi GitHub (GithubSample.Contents).

Krok 1. Tworzenie definicji źródła danych

Łącznik danych rozpoczyna się od rekordu, który opisuje rozszerzenie, w tym jego unikatową nazwę (czyli nazwę rekordu), obsługiwane typy uwierzytelniania i przyjazną nazwę wyświetlaną (etykietę) dla źródła danych. W przypadku obsługi protokołu OAuth definicja zawiera funkcje implementujące kontrakt OAuth — w tym przypadku StartLogin i FinishLogin.

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

Krok 2. Podaj szczegóły, aby aparat M mógł uruchomić przepływ OAuth

Przepływ OAuth usługi GitHub jest uruchamiany po kierowaniu https://github.com/login/oauth/authorize użytkowników do strony. Aby użytkownik zalogował się, należy określić kilka parametrów zapytania:

Nazwisko	Pisz	Opis
client_id	string	Wymagany. Identyfikator klienta otrzymany z usługi GitHub po zarejestrowaniu.
redirect_uri	string	Adres URL w aplikacji, pod którym użytkownicy będą wysyłani po autoryzacji. Zobacz szczegóły poniżej dotyczące adresów URL przekierowania. W przypadku rozszerzeń `redirect_uri` języka M parametr musi mieć wartość "https://oauth.powerbi.com/views/oauthredirect.html".
zakres	string	Rozdzielona przecinkami lista zakresów. Jeśli nie zostanie podana, zakres zostanie domyślnie ustawiony na pustą listę zakresów dla użytkowników, którzy nie mają prawidłowego tokenu dla aplikacji. W przypadku użytkowników, którzy mają już prawidłowy token dla aplikacji, użytkownik nie będzie wyświetlany na stronie autoryzacji OAuth z listą zakresów. Zamiast tego ten krok przepływu zostanie automatycznie ukończony z tymi samymi zakresami, które były używane podczas ostatniego ukończenia przepływu przez użytkownika.
stan	string	Nie do odgadnięcia losowy ciąg. Służy do ochrony przed atakami fałszerzowymi żądań między witrynami.

Poniższy fragment kodu opisuje sposób implementowania StartLogin funkcji w celu uruchomienia przepływu logowania. Funkcja StartLogin przyjmuje resourceUrlwartość , statei display . W funkcji utwórz obiekt AuthorizeUrl , który łączy adres URL autoryzacji usługi GitHub z następującymi parametrami:

client_id: Identyfikator klienta otrzymasz po zarejestrowaniu rozszerzenia w usłudze GitHub ze strony aplikacji GitHub.
scope: Ustaw zakres na "user, repo". Spowoduje to ustawienie zakresu autoryzacji (czyli tego, do czego aplikacja chce uzyskać dostęp) dla użytkownika.
state: wartość wewnętrzna przekazywana przez aparat M.
redirect_uri: ustaw wartość 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
            ];

Jeśli po raz pierwszy użytkownik loguje się za pomocą aplikacji (zidentyfikowanej przez jej client_id wartość), zostanie wyświetlona strona z prośbą o udzielenie dostępu do aplikacji. Kolejne próby logowania będą po prostu prosić o podanie poświadczeń.

Krok 3. Konwertowanie kodu otrzymanego z usługi GitHub na access_token

Jeśli użytkownik ukończy przepływ uwierzytelniania, usługa GitHub przekierowuje z powrotem do adresu URL przekierowania usługi Power BI przy użyciu kodu tymczasowego w parametrze code , a także stanu podanego w poprzednim kroku w parametrze state . Funkcja FinishLogin wyodrębni kod z parametru callbackUri , a następnie wymieni go na token dostępu (przy użyciu TokenMethod funkcji).

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

Aby uzyskać token dostępu usługi GitHub, należy przekazać kod tymczasowy z repozytorium GitHub Authorize Response. TokenMethod W funkcji sformujesz żądanie POST do punktu końcowego access_token usługi GitHub (https://github.com/login/oauth/access_token). Następujące parametry są wymagane dla punktu końcowego usługi GitHub:

Nazwisko	Pisz	Opis
client_id	string	Wymagany. Identyfikator klienta otrzymany z usługi GitHub po zarejestrowaniu.
client_secret	string	Wymagany. Po zarejestrowaniu wpis tajny klienta otrzymany z usługi GitHub.
code	string	Wymagany. Kod otrzymany w pliku `FinishLogin`.
redirect_uri	string	Adres URL w aplikacji, pod którym użytkownicy będą wysyłani po autoryzacji. Zobacz szczegóły poniżej dotyczące adresów URL przekierowania.

Poniżej przedstawiono szczegóły używane parametry wywołania Web.Contents .

Argument	Opis	Wartość
Adres URL	Adres URL witryny sieci Web.	https://github.com/login/oauth/access_token
options	Rekord do kontrolowania zachowania tej funkcji.	Nieużyj w tym przypadku
Query	Programowe dodawanie parametrów zapytania do adresu URL.	`Content = Text.ToBinary( Uri.BuildQueryString( [ client_id = client_id, client_secret = client_secret, code = code, redirect_uri = redirect_uri ] ))` Gdzie `client_id`: Identyfikator klienta ze strony aplikacji GitHub. `client_secret`: Wpis tajny klienta ze strony aplikacji GitHub. `code`: Kod w odpowiedzi autoryzacji w usłudze GitHub. `redirect_uri`: adres URL w aplikacji, pod którym użytkownicy będą wysyłani po autoryzacji.
Nagłówki	Rekord z dodatkowymi nagłówkami dla żądania HTTP.	`Nagłówki = [ #"Content-type" = "application/x-www-form-urlencoded", #"Accept" = "application/json" ]`

W tym fragmencie kodu opisano sposób implementowania TokenMethod funkcji w celu wymiany kodu uwierzytelniania dla tokenu dostępu.

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;

Odpowiedź JSON z usługi będzie zawierać pole access_token. Metoda TokenMethod konwertuje odpowiedź JSON na rekord M przy użyciu pliku Json.Document i zwraca ją do aparatu.

Przykładowa odpowiedź:

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

Krok 4. Definiowanie funkcji, które uzyskują dostęp do interfejsu API usługi GitHub

Poniższy fragment kodu eksportuje dwie funkcje (GithubSample.Contents i GithubSample.PagedTable) przez oznaczenie ich jako sharedi kojarzy je z typem GithubSample źródła danych.

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

Funkcja GithubSample.Contents jest również publikowana w interfejsie użytkownika (umożliwiając jej wyświetlenie w oknie dialogowym Pobieranie danych ). Funkcja Value.ReplaceType służy do ustawiania parametru funkcji na Url.Type przypisany typ.

Skojarzenie tych funkcji z rodzajem GithubSample źródła danych spowoduje automatyczne użycie poświadczeń dostarczonych przez użytkownika. Wszystkie funkcje biblioteki M, które zostały włączone na potrzeby rozszerzalności (np. Web.Contents), również automatycznie dziedziczą te poświadczenia.

Aby uzyskać więcej informacji na temat działania poświadczeń i uwierzytelniania, zobacz Obsługa uwierzytelniania.

Przykładowy adres URL

Ten łącznik może pobrać sformatowane dane z dowolnego punktu końcowego interfejsu API REST usługi GitHub w wersji 3. Na przykład zapytanie w celu ściągnięcia wszystkich zatwierdzeń w repozytorium łączników danych będzie wyglądać następująco:

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

Udostępnij za pośrednictwem