分享方式：

GitHub 連接器範例

  • 文章

GitHub M 延伸模組示範如何新增 OAuth 2.0 通訊協定驗證流程的支援。 您可以在 GitHub 開發人員網站上深入瞭解 GitHub 驗證流程的詳細數據。

開始建立 M 擴充功能之前，您必須在 GitHub 上註冊新的應用程式，並將和 client_secret 檔案取代client_id為應用程式的適當值。

注意 Visual Studio 中的相容性問題：Power Query SDK 會使用 Internet Explorer 型控件來快顯 OAuth 對話框。GitHub 已取代其對此控件所使用 IE 版本的支援，如此一來，如果從 Visual Studio 內執行，您將無法完成應用程式的許可權授與。替代方法是使用Power BI Desktop 載入延伸模組，並在該處完成第一個 OAuth 流程。在您的應用程式獲得帳戶存取權之後，後續登入將會從Visual Studio正常運作。

OAuth 和 Power BI

OAuth 是認證委派的形式。 藉由登入 GitHub 並授權您為 GitHub 建立的「應用程式」，使用者即允許「應用程式」代表他們登入，以將數據擷取至 Power BI。 「應用程式」必須獲得擷取數據的許可權（取得access_token），並依排程重新整理數據（取得和使用refresh_token）。 此內容中的「應用程式」是用來在Power BI內執行查詢的數據連接器。 Power BI 會代表您儲存和管理access_token及refresh_token。

注意

若要允許 Power BI 取得並使用access_token，您必須將重新導向 URL 指定為 https://oauth.powerbi.com/views/oauthredirect.html。

當您指定此 URL 和 GitHub 成功驗證並授與許可權時，GitHub 會重新導向至 PowerBI 的 oauthredirect 端點，讓 Power BI 可以擷取access_token和refresh_token。

如何註冊 GitHub 應用程式

您的 Power BI 擴充功能必須登入 GitHub。 若要啟用此功能，請在 向 GitHub https://github.com/settings/applications/new註冊新的 OAuth 應用程式。

  1. Application name：輸入 M 延伸模組之應用程式的名稱。
  2. Authorization callback URL：輸入 https://oauth.powerbi.com/views/oauthredirect.html。
  3. Scope：在 GitHub 中，將範圍設定為 user, repo。

注意

已註冊的 OAuth 應用程式會獲指派唯一的用戶端識別碼和客戶端密碼。 不應該共用客戶端密碼。 您可以從 GitHub 應用程式頁面取得用戶端識別碼和客戶端密碼。 使用用戶端識別碼（檔案）和客戶端密碼（client_idclient_secret檔案）更新 Data Connector 專案中的檔案。

如何實作 GitHub OAuth

此範例將逐步引導您完成下列步驟：

  1. 建立宣告其支援 OAuth 的數據源種類定義。
  2. 提供詳細數據，讓 M 引擎可以啟動 OAuth 流程 （StartLogin）。
  3. 將從 GitHub 收到的程式代碼轉換成access_token （FinishLogin 和 TokenMethod）。
  4. 定義可存取 GitHub API 的函式 （GithubSample.Contents）。

步驟 1 - 建立數據源定義

數據連接器會以描述延伸模組的記錄開始，包括其唯一名稱（也就是記錄的名稱）、支援的驗證類型（s），以及數據源的易記顯示名稱（標籤）。 支援 OAuth 時，定義會包含實作 OAuth 合約的函式，在此案例中為 StartLogin 和 FinishLogin。

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

步驟 2 - 提供詳細數據，讓 M 引擎可以啟動 OAuth 流程

當您將使用者導向頁面 https://github.com/login/oauth/authorize 時，GitHub OAuth 流程就會開始。 若要讓使用者登入，您必須指定一些查詢參數：

名稱 類型​​ 描述
client_id 字串 必要。 註冊時，您從 GitHub 收到的用戶端識別碼。
redirect_uri 字串 您應用程式中的 URL 會在授權後傳送使用者。 請參閱以下關於重新導向 URL 的詳細數據。 針對 M 延伸模組，必須是 redirect_uri “https://oauth.powerbi.com/views/oauthredirect.html"。
範圍 (scope) 字串 以逗號分隔的範圍清單。 如果未提供，範圍會預設為沒有應用程式有效令牌之使用者的空白範圍清單。 對於已經擁有應用程式有效令牌的使用者，使用者將不會顯示具有範圍清單的 OAuth 授權頁面。 相反地，流程的這個步驟會自動完成使用者上次完成流程時所使用的相同範圍。
state 字串 無法猜測的隨機字串。 它用來防範跨網站要求偽造攻擊。

下列代碼段描述如何實作函 StartLogin 式來啟動登入流程。 函 StartLogin 式接受 resourceUrl、 state和 display 值。 在函式中，建立 AuthorizeUrl ，以下列參數串連 GitHub 授權 URL：

  • client_id：從 GitHub 應用程式頁面向 GitHub 註冊擴充功能之後，您會取得用戶端識別碼。
  • scope：將範圍設定為 “user, repo ” 這會為使用者設定授權範圍（也就是您的應用程式想要存取的內容）。
  • state：M 引擎傳入的內部值。
  • redirect_uri：設定為 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
            ];

如果這是使用者第一次使用您的應用程式登入（由其 client_id 值識別），他們會看到一個頁面，要求他們授與應用程式的存取權。 後續登入嘗試只會要求其認證。

步驟 3 - 將從 GitHub 收到的程式代碼轉換成access_token

如果使用者完成驗證流程，GitHub 會以參數中的 code 暫存程序代碼，以及您在參數上一 state 個步驟中提供的狀態，重新導向回 Power BI 重新導向 URL。 您的 FinishLogin 函式會從 參數擷 callbackUri 取程式代碼，然後將它交換為存取令牌（使用函 TokenMethod 式）。

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

若要取得 GitHub 存取令牌，您可以從 GitHub 授權回應傳遞暫存程式代碼。 在函式中 TokenMethod ，您會對 GitHub 的access_token端點 （https://github.com/login/oauth/access_token） 制定 POST 要求。 GitHub 端點需要下列參數：

名稱 類型​​ 描述
client_id 字串 必要。 註冊時，您從 GitHub 收到的用戶端識別碼。
client_secret 字串 必要。 註冊時從 GitHub 收到的客戶端密碼。
code 字串 必要。 您在 中 FinishLogin收到的程式代碼。
redirect_uri 字串 您應用程式中的 URL 會在授權後傳送使用者。 請參閱以下關於重新導向 URL 的詳細數據。

以下是 Web.Contents 呼叫所使用的參數詳細數據。

Argument 描述 值
URL 網站的 URL。 https://github.com/login/oauth/access_token
電子商務選項中 控制此函式行為的記錄。 在此案例中未使用
查詢 以程序設計方式將查詢參數新增至URL。 Content = Text.ToBinary（
Uri.BuildQueryString（
[
client_id = client_id，
client_secret = client_secret，
code = code，
redirect_uri = redirect_uri
]
))
其中
  • client_id：來自 GitHub 應用程式頁面的用戶端識別碼。
  • client_secret：來自 GitHub 應用程式頁面的客戶端密碼。
  • code：GitHub 授權回應中的程序代碼。
  • redirect_uri：應用程式中的 URL，使用者將在授權後傳送。
標頭 具有 HTTP 要求其他標頭的記錄。 Headers= [
#“Content-type” = “application/x-www-form-urlencoded”，
#“Accept” = “application/json”
]

此代碼段描述如何實作函 TokenMethod 式，以交換存取令牌的驗證碼。

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;

來自服務的 JSON 回應將包含access_token欄位。 方法 TokenMethod 會使用 Json.Document 將 JSON 回應轉換成 M 記錄，並將它傳回至引擎。

範例回應：

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

步驟 4 - 定義可存取 GitHub API 的函式

下列代碼段會將兩個函式導出為GithubSample.Contents GithubSample.PagedTableshared，並將其與GithubSample數據源種類產生關聯。

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

函式 GithubSample.Contents 也會發佈至 UI（允許它出現在 [ 取得資料 ] 對話框中。 Value.ReplaceType 函式是用來將函式參數設定為Url.Type指定的型別。

藉由將這些函式與 GithubSample 數據源種類產生關聯，它們會自動使用使用者提供的認證。 任何已啟用擴充性 （例如 Web.Contents） 的 M 連結庫函式也會自動繼承這些認證。

如需認證和驗證運作方式的詳細資訊，請參閱 處理驗證。

範例 URL

此連接器可以從任何 GitHub v3 REST API 端點擷取格式化的數據。 例如，將所有認可提取至數據連接器存放庫的查詢看起來會像這樣：

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