Przykład łącznika usługi GitHub

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 GitHub Docs.

Przed rozpoczęciem tworzenia rozszerzenia języka M musisz zarejestrować nową aplikację na GitHub i zastąpić pliki client_id i client_secret odpowiednimi wartościami dla Twojej 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 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, jeśli zostanie uruchomiona 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 GitHub i autoryzując aplikację, którą utworzyli dla GitHub, użytkownik pozwala aplikacji zalogować się w jego imieniu, aby pobrać dane do 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 / Notatka

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 gdy GitHub pomyślnie uwierzytelni się i przyzna uprawnienia, GitHub przekierowuje do punktu końcowego oauthredirect Power BI, aby Power BI mogło pobrać access_token i refresh_token.

Jak zarejestrować aplikację GitHub

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

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

Uwaga / Notatka

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

W tym przykładzie przedstawiono następujące kroki:

1. Utwórz definicję rodzaju źródła danych, która deklaruje, że obsługuje protokół OAuth.
2. Podaj szczegóły, aby silnik M mógł uruchomić przepływ OAuth (StartLogin).
3. Przekonwertuj kod otrzymany z usługi GitHub na access_token (FinishLogin i TokenMethod).
4. 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 silnik M mógł rozpocząć przepływ OAuth

Przepływ OAuth usługi GitHub rozpoczyna się, kiedy kierujesz użytkowników na stronę https://github.com/login/oauth/authorize. Aby użytkownik zalogował się, należy określić kilka parametrów zapytania:

Name	Typ	Description
identyfikator_klienta	ciąg	Wymagane. Identyfikator klienta otrzymany z usługi GitHub po zarejestrowaniu.
redirect_uri	ciąg	Adres URL w aplikacji, na który użytkownicy będą przekierowywani po autoryzacji. Zobacz szczegółowe informacje na temat adresów URL przekierowania. W przypadku rozszerzeń M parametr redirect_uri musi mieć wartość "https://oauth.powerbi.com/views/oauthredirect.html".
zakres	ciąg	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, używając tych samych zakresów, które były używane ostatnim razem, kiedy użytkownik ukończył przepływ.
stan	ciąg	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 wartości resourceUrl, state i 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 silnik 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ą wymagały podania 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 odpowiedzi autoryzacyjnej GitHub. W funkcji TokenMethod sformułujesz żądanie POST do punktu końcowego access_token GitHub (https://github.com/login/oauth/access_token). Następujące parametry są wymagane dla punktu końcowego usługi GitHub:

Name	Typ	Description
identyfikator_klienta	ciąg	Wymagane. Identyfikator klienta otrzymany z usługi GitHub po zarejestrowaniu.
client_secret	ciąg	Wymagane. Tajny klucz klienta, który otrzymałeś z GitHub po zarejestrowaniu.
kod	ciąg	Wymagane. Kod otrzymany w pliku FinishLogin.
redirect_uri	ciąg	Adres URL w aplikacji, na który użytkownicy będą przekierowywani po autoryzacji. Szczegółowe informacje dotyczące przekierowań adresów URL znajdziesz poniżej.

Oto szczegóły używanych parametrów dla wywołania Web.Contents.

Argument	Description	Wartość
URL	Adres URL witryny sieci Web.	https://github.com/login/oauth/access_token
options	Rekord do kontrolowania zachowania tej funkcji.	Nie używane 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, kod = kod, redirect_uri = redirect_uri ] )) Where client_id: Identyfikator klienta ze strony aplikacji GitHub. client_secret: Tajny klucz klienta ze strony aplikacji GitHub. code: Kod w odpowiedzi autoryzacyjnej GitHub. redirect_uri: URL w aplikacji, do którego 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 Json.Document i zwraca ją do silnika.

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")