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 に登録します。
Application name
: M 拡張機能のアプリケーションの名前を入力します。Authorization callback URL
: 「https://oauth.powerbi.com/views/oauthredirect.html」と入力します。Scope
: GitHub でスコープをuser, repo
に設定します。
Note
登録された OAuth アプリケーションには、一意のクライアント ID とクライアント シークレットが割り当てられます。 クライアント シークレットを共有することはできません。 クライアント ID とクライアント シークレットは、GitHub アプリケーション ページから取得します。 クライアント ID (client_id
ファイル) とクライアント シークレット (client_secret
ファイル) を使用して、Data Connector プロジェクト内のファイルを更新します。
GitHub OAuth を実装する方法
このサンプルでは、次の手順を順に説明します。
- データ ソースの種類の定義を作成し、OAuth をサポートすることを宣言します。
- M エンジンが OAuth フローを開始できるよう、詳細を指定します (
StartLogin
)。 - GitHub から受け取ったコードを access_token に変換します (
FinishLogin
およびTokenMethod
)。 - 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( |
ヘッダー | HTTP 要求の追加ヘッダーを含むレコード。 | Headers= [ |
このコード スニペットでは、認証コードをアクセス トークンと交換する 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")