Sampel Konektor GitHub

Ekstensi GitHub M menunjukkan cara menambahkan dukungan untuk alur autentikasi protokol OAuth 2.0. Anda dapat mempelajari selengkapnya tentang spesifikasi alur autentikasi GitHub di situs Pengembang GitHub.

Sebelum mulai membuat ekstensi M, Anda perlu mendaftarkan aplikasi baru di GitHub, dan mengganti client_id file dan client_secret dengan nilai yang sesuai untuk aplikasi Anda.

Catatan tentang masalah kompatibilitas di Visual Studio: Power Query SDK menggunakan kontrol berbasis Internet Explorer untuk memunculkan dialog OAuth. GitHub telah menghentikan dukungannya untuk versi IE yang digunakan oleh kontrol ini, yang akan mencegah Anda menyelesaikan pemberian izin untuk aplikasi Anda jika dijalankan dari dalam Visual Studio. Alternatifnya adalah memuat ekstensi dengan Power BI Desktop dan menyelesaikan alur OAuth pertama di sana. Setelah aplikasi Anda diberikan akses ke akun Anda, login berikutnya akan berfungsi dengan baik dari Visual Studio.

OAuth dan Power BI

OAuth adalah bentuk delegasi kredensial. Dengan masuk ke GitHub dan mengotorisasi "aplikasi" yang Anda buat untuk GitHub, pengguna mengizinkan "aplikasi" Anda untuk masuk atas nama mereka untuk mengambil data ke Power BI. "Aplikasi" harus diberikan hak untuk mengambil data (mendapatkan access_token) dan untuk me-refresh data sesuai jadwal (dapatkan dan gunakan refresh_token). "Aplikasi" Anda dalam konteks ini adalah Konektor Data Anda yang digunakan untuk menjalankan kueri dalam Power BI. Power BI menyimpan dan mengelola access_token dan refresh_token atas nama Anda.

Saat Anda menentukan URL dan GitHub ini berhasil mengautentikasi dan memberikan izin, GitHub akan mengalihkan ke titik akhir oauthredirect PowerBI sehingga Power BI dapat mengambil access_token dan refresh_token.

Cara mendaftarkan aplikasi GitHub

Ekstensi Power BI Anda perlu masuk ke GitHub. Untuk mengaktifkan ini, Anda mendaftarkan aplikasi OAuth baru dengan GitHub di https://github.com/settings/applications/new.

1. Application name: Masukkan nama untuk aplikasi untuk ekstensi M Anda.
2. Authorization callback URL: Masukkan https://oauth.powerbi.com/views/oauthredirect.html.
3. Scope: Di GitHub, atur cakupan ke user, repo.

Cara menerapkan GitHub OAuth

Sampel ini akan memandikan Anda melalui langkah-langkah berikut:

1. Buat definisi Jenis Sumber Data yang menyatakan mendukung OAuth.
2. Berikan detail sehingga mesin M dapat memulai alur OAuth (StartLogin).
3. Konversi kode yang diterima dari GitHub menjadi access_token (FinishLogin dan TokenMethod).
4. Tentukan fungsi yang mengakses GITHub API (GithubSample.Contents).

Langkah 1 - Membuat definisi Sumber Data

Konektor Data dimulai dengan catatan yang menjelaskan ekstensi, termasuk nama uniknya (yang merupakan nama rekaman), jenis autentikasi yang didukung, dan nama tampilan (label) yang ramah untuk sumber data. Saat mendukung OAuth, definisi berisi fungsi yang mengimplementasikan kontrak OAuth—dalam hal ini, StartLogin dan FinishLogin.

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

Langkah 2 - Berikan detail sehingga mesin M dapat memulai alur OAuth

Alur GitHub OAuth dimulai saat Anda mengarahkan pengguna ke https://github.com/login/oauth/authorize halaman. Agar pengguna dapat masuk, Anda perlu menentukan sejumlah parameter kueri:

Cuplikan kode berikut menjelaskan cara mengimplementasikan StartLogin fungsi untuk memulai alur masuk. Fungsi StartLogin mengambil resourceUrlnilai , state, dan display . Dalam fungsi , buat AuthorizeUrl yang menggabungkan URL otorisasi GitHub dengan parameter berikut:

• client_id: Anda mendapatkan ID klien setelah mendaftarkan ekstensi Anda dengan GitHub dari halaman aplikasi GitHub.
• scope: Atur cakupan ke "user, repo". Ini mengatur cakupan otorisasi (yaitu, apa yang ingin diakses aplikasi Anda) untuk pengguna.
• state: Nilai internal yang diteruskan mesin M.
• redirect_uri: Atur ke 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
            ];

Jika ini pertama kalinya pengguna masuk dengan aplikasi Anda (diidentifikasi oleh nilainya client_id ), mereka akan melihat halaman yang meminta mereka untuk memberikan akses ke aplikasi Anda. Upaya masuk berikutnya hanya akan meminta kredensial mereka.

Langkah 3 - Mengonversi kode yang diterima dari GitHub menjadi access_token

Jika pengguna menyelesaikan alur autentikasi, GitHub mengalihkan kembali ke URL pengalihan Power BI dengan kode sementara dalam code parameter, serta status yang Anda berikan di langkah sebelumnya dalam state parameter. Fungsi Anda FinishLogin akan mengekstrak kode dari callbackUri parameter, lalu menukarnya dengan token akses (menggunakan TokenMethod fungsi ).

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

Untuk mendapatkan token akses GitHub, Anda meneruskan kode sementara dari Respons Otorisasi GitHub. Dalam fungsi , TokenMethod Anda merumuskan permintaan POST ke titik akhir access_token GitHub (https://github.com/login/oauth/access_token). Parameter berikut diperlukan untuk titik akhir GitHub:

Berikut adalah detail parameter yang digunakan untuk panggilan Web.Contents .

Cuplikan kode ini menjelaskan cara mengimplementasikan TokenMethod fungsi untuk bertukar kode autentikasi dengan token akses.

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;

Respons JSON dari layanan akan berisi bidang access_token. Metode ini TokenMethod mengonversi respons JSON menjadi rekaman M menggunakan Json.Document, dan mengembalikannya ke mesin.

Respons sampel:

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

Langkah 4 - Tentukan fungsi yang mengakses API GitHub

Cuplikan kode berikut mengekspor dua fungsi (GithubSample.Contents dan GithubSample.PagedTable) dengan menandainya sebagai shared, dan mengaitkannya dengan GithubSample Jenis Sumber Data.

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

Fungsi GithubSample.Contents ini juga diterbitkan ke UI (memungkinkannya muncul dalam dialog Dapatkan Data ). Fungsi Value.ReplaceType digunakan untuk mengatur parameter fungsi ke Url.Type jenis ascribed.

Dengan mengaitkan fungsi-fungsi ini dengan GithubSample jenis sumber data, fungsi tersebut akan secara otomatis menggunakan kredensial yang disediakan pengguna. Setiap fungsi pustaka M yang telah diaktifkan untuk ekstensibilitas (seperti Web.Contents) akan secara otomatis mewarisi kredensial ini juga.

Untuk detail selengkapnya tentang cara kerja kredensial dan autentikasi, lihat Menangani Autentikasi.

URL Sampel

Konektor ini dapat mengambil data yang diformat dari salah satu titik akhir REST API GitHub v3. Misalnya, kueri untuk menarik semua penerapan ke repositori Konektor Data akan terlihat seperti ini:

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