Share via

GitHub 連線or 範例

  • 發行項

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_secret （ client_id 檔案）更新資料連線or 專案中的檔案。

如何實作 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 string 必要。 註冊時，您從 GitHub 收到的用戶端識別碼。
redirect_uri string 您應用程式中的 URL 會在授權後傳送使用者。 請參閱以下關于重新導向 URL 的詳細資料。 針對 M 延伸模組，必須是 redirect_uri 「 https://oauth.powerbi.com/views/oauthredirect.html" ;。
範圍 (scope) string 以逗號分隔的範圍清單。 如果未提供，範圍會預設為沒有應用程式有效權杖之使用者的空白範圍清單。 對於已經擁有應用程式有效權杖的使用者，使用者將不會顯示具有範圍清單的 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 string 必要。 註冊時，您從 GitHub 收到的用戶端識別碼。
client_secret string 必要。 註冊時從 GitHub 收到的用戶端密碼。
code string 必要。 您在 中 FinishLogin 收到的程式碼。
redirect_uri string 您應用程式中的 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.ContentsGithubSample.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 端點擷取格式化的資料。 例如，將所有認可提取至 Data 連線ors 存放庫的查詢看起來會像這樣：

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