GitHub コネクタのサンプル

  • [アーティクル]

GitHub M 拡張機能は、OAuth 2.0 プロトコル認証フローのサポートを追加する方法を示しています。 GitHub の認証フローの詳細については、GitHub 開発者サイトで確認できます。

M 拡張機能を作成する前に、GitHub に新しいアプリを登録し、client_id と client_secret の各ファイルを、アプリに適切な値に置き換える必要があります。

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 を格納し管理します。

Note

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 へのログインが必要です。 これを有効にするには、https://github.com/settings/applications/new で新しい OAuth アプリケーションを GitHub に登録します。

  1. Application name: M 拡張機能のアプリケーションの名前を入力します。
  2. Authorization callback URL: 「https://oauth.powerbi.com/views/oauthredirect.html」と入力します。
  3. Scope: GitHub でスコープを user, repo に設定します。

Note

登録された OAuth アプリケーションには、一意のクライアント ID とクライアント シークレットが割り当てられます。 クライアント シークレットを共有することはできません。 クライアント ID とクライアント シークレットは、GitHub アプリケーション ページから取得します。 クライアント ID (client_id ファイル) とクライアント シークレット (client_secret ファイル) を使用して、Data Connector プロジェクト内のファイルを更新します。

GitHub OAuth を実装する方法

このサンプルでは、次の手順を順に説明します。

  1. データ ソースの種類の定義を作成し、OAuth をサポートすることを宣言します。
  2. M エンジンが OAuth フローを開始できるよう、詳細を指定します (StartLogin)。
  3. GitHub から受け取ったコードを access_token に変換します (FinishLogin および TokenMethod)。
  4. GitHub API にアクセスする関数を定義します (GithubSample.Contents)。

手順 1 - データ ソース定義を作成する

データ コネクタは、一意の名前 (レコードの名前)、サポートされている認証の種類、データ ソースの表示名 (ラベル) など、拡張機能を記述するレコードで始まります。 OAuth をサポートする場合、この定義には、OAuth コントラクトを実装する関数 (この場合は StartLogin と FinishLogin) が含まれます。

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

手順 2 - M エンジンが OAuth フローを開始できるように詳細を指定する

GitHub OAuth フローは、ユーザーが https://github.com/login/oauth/authorize ページに移動すると開始されます。 ユーザーがログインするには、複数のクエリ パラメーターを指定する必要があります。

名前 タイプ 説明
client_id string 必須。 登録時に GitHub から受信したクライアント ID。
redirect_uri string 承認後にユーザーがリダイレクトされるアプリ内の URL。 リダイレクト URL の詳細については、以下を参照してください。 M 拡張機能の場合、redirect_uri は https://oauth.powerbi.com/views/oauthredirect.html" である必要があります。
scope string スコープのコンマ区切りの一覧。 指定しない場合、スコープの既定値は、アプリの有効なトークンがないユーザーのスコープの空の一覧になります。 アプリの有効なトークンを既に持っているユーザーの場合、ユーザーには、スコープの一覧が表示された OAuth 承認ページは表示されません。 代わりに、フローのこのステップは、ユーザーがフローを最後に完了した時点と同じスコープで自動的に完了します。
state string 推測できないランダム文字列。 クロスサイト リクエスト フォージェリ攻撃から保護するために使用されます。

次のコード スニペットでは、ログイン フローを開始する StartLogin 関数を実装する方法について説明します。 StartLogin 関数は、resourceUrl、state、display などの値を取ります。 この関数で、GitHub 認証 URL を次のパラメーターと連結する AuthorizeUrl を作成します。

  • client_id: GitHub アプリケーション ページから拡張機能を GitHub に登録した後、クライアント ID を取得します。
  • 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 パラメーターの一時コードで Power BI リダイレクト URL にリダイレクトし、前の手順で state パラメーターに指定された状態に戻ります。 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 から受信したクライアント ID。
client_secret string 必須。 登録時に GitHub から受信したクライアント シークレット。
code string 必須。 FinishLogin で受信したコード。
redirect_uri string 承認後にユーザーがリダイレクトされるアプリ内の URL。 リダイレクト URL の詳細については、以下を参照してください。

Web.Contents 呼び出しに使用されるパラメーターの詳細をこちらに示します。

引数 説明 Value
url Web サイトの URL。 https://github.com/login/oauth/access_token
options この関数の動作を制御するレコード。 この場合は使用されません
クエリ プログラムによってクエリ パラメーターを URL に追加します。 Content = Text.ToBinary(
Uri.BuildQueryString(
[
client_id = client_id,
client_secret = client_secret,
code = code,
redirect_uri = redirect_uri
]
))
Where
  • client_id: GitHub アプリケーション ページからのクライアント ID。
  • 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 にアクセスする関数を定義する

次のコード スニペットでは、2 つの関数 (GithubSample.Contents と GithubSample.PagedTable) を shared としてマークしてエクスポートし、それらをデータ ソースの種類 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 に関連付けると、ユーザーが指定した資格情報が自動的に使用されます。 機能拡張が有効になっている M ライブラリ関数 (Web.Contents など) でも、これらの資格情報が自動的に継承されます。

資格情報と認証の仕組みの詳細については、「認証の処理」を参照してください。

サンプル URL

このコネクタは、任意の GitHub v3 REST API エンドポイントからフォーマット済みデータを取得できます。 たとえば、すべてのコミットをデータ コネクタ リポジトリにプルするクエリは、こちらのようになります。

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