トレーニング
モジュール
オープンソースの Microsoft Power Platform カスタム コネクタを認定および作成する - Training
Microsoft Power Platform GitHub リポジトリ内のすべてのユーザーがカスタム コネクタを利用する方法について説明します。
このブラウザーはサポートされなくなりました。
Microsoft Edge にアップグレードすると、最新の機能、セキュリティ更新プログラム、およびテクニカル サポートを利用できます。
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 は、資格情報の委任の一形式です。 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 を取得できるようになります。
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
に設定します。注意
登録された OAuth アプリケーションには、一意のクライアント ID とクライアント シークレットが割り当てられます。 クライアント シークレットを共有することはできません。 クライアント ID とクライアント シークレットは、GitHub アプリケーション ページから取得します。 クライアント ID (client_id
ファイル) とクライアント シークレット (client_secret
ファイル) を使用して、Data Connector プロジェクト内のファイルを更新します。
このサンプルでは、次の手順を順に説明します。
StartLogin
)。FinishLogin
および TokenMethod
)。GithubSample.Contents
)。データ コネクタは、一意の名前 (レコードの名前)、サポートされている認証の種類、データ ソースの表示名 (ラベル) など、拡張機能を記述するレコードで始まります。
OAuth をサポートする場合、この定義には、OAuth コントラクトを実装する関数 (この場合は StartLogin
と FinishLogin
) が含まれます。
//
// Data Source definition
//
GithubSample = [
Authentication = [
OAuth = [
StartLogin = StartLogin,
FinishLogin = FinishLogin
]
],
Label = Extension.LoadString("DataSourceLabel")
];
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
値で識別される) と、アプリへのアクセス権を付与するページが表示されます。 それ以降のログイン試行では、単に資格情報が要求されます。
ユーザーが認証フローを完了すると、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"
}
次のコード スニペットでは、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 など) でも、これらの資格情報が自動的に継承されます。
資格情報と認証の仕組みの詳細については、「認証の処理」を参照してください。
このコネクタは、任意の GitHub v3 REST API エンドポイントからフォーマット済みデータを取得できます。 たとえば、すべてのコミットをデータ コネクタ リポジトリにプルするクエリは、こちらのようになります。
GithubSample.Contents("https://api.github.com/repos/microsoft/dataconnectors/commits")
トレーニング
モジュール
オープンソースの Microsoft Power Platform カスタム コネクタを認定および作成する - Training
Microsoft Power Platform GitHub リポジトリ内のすべてのユーザーがカスタム コネクタを利用する方法について説明します。