Power Automate 用の Microsoft Graph JSON Batch カスタム コネクタを作成する
Microsoft Power Automate には、230 を超える既定のコネクタがあります。 これらのコネクタの多くは、Microsoft Graph を使用して Microsoft 製品の特定のエンドポイントと通信します。 さらに、Api 全体をカバーするために Microsoft Graph と直接通信するコネクタがないため、サービスの基本的な構成要素を使用して Power Automate から Microsoft Graph を直接呼び出す必要がある場合があります。
Microsoft Graph を直接呼び出すシナリオに対処するだけでなく、多くの Microsoft Graph API エンドポイントでは 委任されたアクセス許可のみがサポートされています。 Microsoft Power Automate の HTTP コネクタを使用すると、Microsoft Graph の呼び出しなど、非常に柔軟な統合が可能になります。 ただし、HTTP コネクタには、特定の委任されたアクセス許可シナリオを有効にするためにユーザーの資格情報をキャッシュする機能がありません。 このような場合は、Microsoft Graph API のラッパーを提供し、委任されたアクセス許可を使用して API を使用できるように、カスタム コネクタを作成できます。
このラボでは、上記の両方のシナリオについて説明します。 まず、 委任されたアクセス許可を必要とする Microsoft Graph との統合を有効にするカスタム コネクタを作成します。 次に、 $batch要求エンドポイントを使用して、アプリに "サインイン" ユーザーが存在する必要がある委任されたアクセス許可を使用しながら、Microsoft Graph の完全な機能へのアクセスを提供します。
注:
これは、Microsoft Power Automate と Azure Logic Apps で使用するカスタム コネクタの作成に関するチュートリアルです。 このチュートリアルでは、 カスタム コネクタの概要 を読んでプロセスを理解していることを前提としています。
前提条件
この投稿でこの演習を完了するには、次のものが必要です。
- Microsoft 365 テナントへの管理者アクセス。 Microsoft 365 テナントをお持ちでない場合は、 Microsoft 365 開発者プログラムを通じてテナントの資格を得る可能性があります。詳細については、 FAQ を参照してください。 または、 1 か月間の無料試用版にサインアップするか、Microsoft 365 プランを購入することもできます。
- Premium ライセンスを使用した Microsoft Power Automate へのアクセス。 詳細については、「 Power Automate ライセンスに関する FAQ 」を参照してください。 Premium ライセンスをお持ちでない場合は、90 日間の試用版にサインアップできます。
フィードバック
GitHub リポジトリで、このチュートリアルに関するフィードバックをお寄せください。
Azure AD アプリ登録を作成する
この演習では、カスタム コネクタの委任されたアクセス許可を提供するために使用する新しい Azure Active Directory アプリケーションを作成します。
ブラウザーを開き、 Microsoft Entra 管理センター に移動し、グローバル管理者アカウントを使用してログインします。
左側のナビゲーションで [Microsoft Entra ID] を 選択し、[ ID] を展開し、[ アプリケーション] を展開して、[ アプリの登録] を選択します。
[アプリ の登録 ] ブレードの上部にある [新しい登録] メニュー項目 を 選択します。
![Azure Active Directory 管理センターの [アプリの登録] ブレードのスクリーン ショット](images/power-automate/new-registration.png)
[名前] フィールドに「MS Graph Batch App」と入力します。 [ サポートされているアカウントの種類 ] セクション で、[任意の組織のディレクトリにあるアカウント] を選択します。 [ リダイレクト URI ] セクションは空白のままにし、[ 登録] を選択します。
![Azure Active Directory 管理センターの [アプリケーションの登録] ブレードのスクリーン ショット](images/power-automate/register-an-app.png)
[ MS Graph Batch App] ブレードで、 アプリケーション (クライアント) ID をコピーします。 これは、次の演習で必要になります。
[MS Graph Batch App] ブレードの [管理] セクションで[API アクセス許可] エントリを選択します。 [API アクセス許可] で [アクセス許可の追加] を選択 します。
![[API アクセス許可] ブレードのスクリーン ショット](images/power-automate/api-permissions.png)
[ API のアクセス許可の要求 ] ブレードで、 Microsoft Graph を選択し、[ 委任されたアクセス許可] を選択します。
groupを検索し、委任されたすべてのグループの読み取りと書き込みのアクセス許可を選択します。 ブレードの下部にある [ アクセス許可の追加] を選択します。
![[API のアクセス許可の要求] ブレードのスクリーン ショット](images/power-automate/select-permissions.png)
[MS Graph Batch App] ブレードの [管理] セクションで [証明書とシークレット] エントリを選択し、[新しいクライアント シークレット] を選択します。 説明を入力し、期間を選択し、[ 追加] を選択します。
![[証明書とシークレット] ブレードのスクリーン ショット](images/power-automate/create-client-secret.png)
新しいシークレットの値をコピーします。 これは、次の演習で必要になります。
重要
このブレードを閉じるとシークレットにアクセスできなくなりますので、この手順は重要です。 このシークレットをテキスト エディターに保存して、今後の演習で使用します。
Teams プロパティなど、Microsoft Graph を介してアクセス可能な追加サービスの管理を有効にするには、特定のサービスの管理を有効にするために、追加の適切なスコープを選択する必要があります。 たとえば、OneNote Notebook または Planner プラン、バケット、タスクを作成できるようにソリューションを拡張するには、関連する API に必要なアクセス許可スコープを追加する必要があります。
カスタム コネクタを作成する
この演習では、Microsoft Power Automate または Azure Logic Apps で使用できる新しいカスタム コネクタを作成します。 OpenAPI 定義ファイルは、Microsoft Graph $batch エンドポイントの正しいパスと、単純なインポートを有効にする追加の設定で事前構築されています。
ブラウザーを開き、[ Microsoft Power Automate] に移動します。 Microsoft 365 テナント管理者アカウントでサインインします。 左側のメニューで [ カスタム コネクタ ] を選択します。 メニュー にカスタム コネクタ が存在しない場合は、[ その他] を選択し、[ すべて検出] を選択します。
Microsoft Graph 用のカスタム コネクタを作成するには、次の 2 つのオプションがあります。
- 空白から作成する
- OpenAPI ファイルをインポートする
[ カスタム コネクタ ] ページで、右上の [ 新しいカスタム コネクタ ] リンクを選択し、ドロップダウン メニュー の [空の項目から作成 ] を選択します。
![Microsoft Power Automate の [新しいカスタム コネクタ] ドロップダウン メニューのスクリーン ショット](images/power-automate/new-connector.png)
[コネクタ名] テキスト ボックスに「MS Graph Batch Connector」と入力します。 Choose Continue.
コネクタ構成の [ 全般] ページで、次のようにフィールドに入力します。
- スキーム: HTTPS
-
ホスト:
graph.microsoft.com -
ベース URL:
/
[ セキュリティ ] ボタンを選択して続行します。
![コネクタ構成の [全般] タブのスクリーン ショット](images/power-automate/general-tab.png)
[ セキュリティ ] ページで、次のようにフィールドに入力します。
-
API によって実装される認証を選択します。
OAuth 2.0 -
ID プロバイダー:
Azure Active Directory - クライアント ID: 前の演習で作成したアプリケーション ID
- クライアント シークレット: 前の演習で作成したキー
-
ログイン URL:
https://login.windows.net -
テナント ID:
common -
リソース URL:
https://graph.microsoft.com(末尾 /) なし - スコープ: 空白のままにします
[ 定義 ] ボタンを選択して続行します。
![コネクタ構成の [セキュリティ] タブのスクリーン ショット](images/power-automate/security-tab.png)
[ 定義 ] ページで、[ 新しいアクション ] を選択し、次のようにフィールドに入力します。
-
概要:
Batch -
説明:
Execute Batch with Delegate Permission -
操作 ID:
Batch -
可視性:
important
![コネクタ構成の [定義] タブのスクリーン ショット](images/power-automate/definition-tab.png)
[サンプルからインポート] を選択して要求を作成し、次のようにフィールドに入力します。
-
動詞:
POST -
URL:
https://graph.microsoft.com/v1.0/$batch - ヘッダー: 空白のままにします
-
本文:
{}
[インポート] を選択します。
![コネクタ構成の [サンプルからインポート] ダイアログのスクリーン ショット](images/power-automate/import-sample.png)
右上の [ コネクタの作成 ] を選択します。
コネクタが作成されたら、[セキュリティ] タブから生成されたリダイレクト URL をコピーします。
前の演習で作成した Microsoft Entra ポータルで、登録済みのアプリケーションに戻ります。 左側のメニューで [ 認証 ] を選択します。 [プラットフォームを追加] を選択して、[Web] を選択します。 前の手順からコピーしたリダイレクト URL を [リダイレクト URI] に入力し、[ 構成] を選択します。
![Azure portal の [応答 URL] ブレードのスクリーン ショット](images/power-automate/update-app-reg.png)
コネクタを承認する
コネクタを使用する準備ができていることを確認する最後の構成手順は、カスタム コネクタを承認してテストして、キャッシュされた接続を作成することです。
重要
次の手順では、管理者特権でログインする必要があります。
Microsoft Power Automate で、左側のメニューで [接続] を選択します。 メニューに [接続] が表示されない場合は、[ その他] を選択します。 [ 新しい接続 ] リンクを選択します。
カスタム コネクタを見つけて接続を完了するには、そのコネクタを選択し、[ 作成] を選択します。 Microsoft 365 テナント管理者の Azure Active Directory アカウントでサインインします。
要求されたアクセス許可の入力を求められたら、[ 組織に代わって同意 する] をオンにし、[ 同意 ] を選択してアクセス許可を承認します。
アクセス許可を承認すると、Power Automate で接続が作成されます。
カスタム コネクタが構成され、有効になりました。 アクセス許可が適用され、使用可能になるのに遅延が生じる可能性がありますが、コネクタが構成されました。
Graph エクスプローラーでバッチ処理をテストする
新しいコネクタを使用するフローを作成する前に、 Microsoft Graph Explorer を 使用して、Microsoft Graph での JSON バッチ処理の機能と機能の一部を検出します。
ブラウザーで Microsoft Graph エクスプローラー を開きます。 Microsoft 365 テナント管理者アカウントでサインインします。 サンプル クエリから Batch を検索します。
左側のメニューで [ 並列 GET の実行 ] サンプル クエリを選択します。 画面の右上にある [ クエリの実行 ] ボタンを選択します。
![グラフ エクスプローラーの [サンプル クエリ] タブのスクリーン ショット](images/power-automate/sample-queries.png)
このサンプル バッチ操作では、3 つの HTTP GET 要求をバッチ処理し、 /v1.0/$batch Graph エンドポイントに 1 つの HTTP POST を発行します。
{
"requests": [
{
"url": "/me?$select=displayName,jobTitle,userPrincipalName",
"method": "GET",
"id": "1"
},
{
"url": "/me/messages?$filter=importance eq 'high'&$select=from,subject,receivedDateTime,bodyPreview",
"method": "GET",
"id": "2"
},
{
"url": "/me/events",
"method": "GET",
"id": "3"
}
]
}
返される応答を次に示します。 Microsoft Graph によって返される応答の配列に注意してください。 バッチ処理された要求に対する応答は、POST 内の要求の順序とは異なる順序で表示される場合があります。
id プロパティを使用して、個々のバッチ要求を特定のバッチ応答に関連付ける必要があります。
注:
読みやすくするために応答が切り捨てられました。
{
"responses": [
{
"id": "1",
"status": 200,
"headers": {...},
"body": {...}
},
{
"id": "3",
"status": 200,
"headers": {...},
"body": {...}
}
{
"id": "2",
"status": 200,
"headers": {...},
"body": {...}
}
]
}
各応答には、 id、 status、 headers、および body プロパティが含まれます。 要求の status プロパティがエラーを示している場合、 body には要求から返されたエラー情報が含まれます。
要求の操作の順序を確認するために、 dependsOn プロパティを使用して個々の要求をシーケンスできます。
JSON バッチ処理では、シーケンス処理と依存関係操作に加えて、基本パスが想定され、相対パスからの要求が実行されます。 各バッチ要求要素は、指定した /v1.0/$batch または /beta/$batch エンドポイントから実行されます。 これは、 /beta エンドポイントが追加の出力を返す可能性があるため、 /v1.0 エンドポイントでは返されない可能性があるため、大きな違いがあります。
たとえば、 Microsoft Graph エクスプローラーで次の 2 つのクエリを実行します。
- URL
/meを使用して/v1.0/$batchエンドポイントにクエリを実行します (下の要求をコピーして貼り付けます)。
{
"requests": [
{
"id": 1,
"url": "/me",
"method": "GET"
}
]
}
次に、バージョン セレクタードロップダウンを使用して beta エンドポイントに変更し、まったく同じ要求を行います。
返される結果の違いは何ですか? いくつかの違いを特定するために、他のクエリを試してください。
/v1.0 および /beta エンドポイントとは異なる応答コンテンツに加えて、アクセス許可の同意が付与されていないバッチ要求が行われた場合に発生する可能性のあるエラーを理解することが重要です。 たとえば、OneNote Notebook を作成するためのバッチ要求項目を次に示します。
{
"id": 1,
"url": "/groups/65c5ecf9-3311-449c-9904-29a2c76b9a50/onenote/notebooks",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Meeting Notes"
}
}
ただし、OneNote Notebooks を作成するアクセス許可が付与されていない場合は、次の応答が受信されます。 状態コード 403 (Forbidden) と、指定された OAuth トークンを示すエラー メッセージには、要求されたアクションを完了するために必要なスコープが含まれていないことに注意してください。
{
"responses": [
{
"id": "1",
"status": 403,
"headers": {
"Cache-Control": "no-cache"
},
"body": {
"error": {
"code": "40004",
"message": "The OAuth token provided does not have the necessary scopes to complete the request.
Please make sure you are including one or more of the following scopes: Notes.ReadWrite.All,
Notes.Read.All (you provided these scopes: Group.Read.All,Group.ReadWrite.All,User.Read,User.Read.All)",
"innerError": {
"request-id": "92d50317-aa06-4bd7-b908-c85ee4eff0e9",
"date": "2018-10-17T02:01:10"
}
}
}
}
]
}
バッチ内の各要求は、状態コードと結果またはエラー情報を返します。 個々のバッチ操作の成功または失敗を判断するには、各応答を処理する必要があります。
フローの作成
この演習では、前の演習で作成したカスタム コネクタを使用して Microsoft チームを作成および構成するフローを作成します。 このフローでは、カスタム コネクタを使用して POST 要求を送信して Office 365 統合グループを作成し、グループの作成が完了するまで遅延の間一時停止し、グループを Microsoft チームに関連付ける PUT 要求を送信します。
最後に、フローは次の図のようになります。
ブラウザーで Microsoft Power Automate を 開き、Office 365 テナント管理者アカウントでサインインします。 左側のナビゲーションで [ マイ フロー ] を選択します。 [ 新しいフロー]、[ インスタント クラウド フロー] の順に選択します。 [フロー名] に「Create Team」と入力し、[このフローをトリガーする方法を選択する] で [手動でフローをトリガーする] を選択します。
[作成] を選択します。
[フロー項目を 手動でトリガー する] を選択し、[ 入力の追加] を選択し、[ テキスト ] を選択し、タイトルとして「 Name 」と入力します。
[フロー項目を手動でトリガーする] で [+] を選択し、[アクションの追加] を選択します。 検索ボックスに「 Batch 」と入力し、[ ランタイム ] ドロップダウンを [カスタム] に設定します。
MS Graph Batch Connector アクションを追加します。 省略記号を選択し、このアクションの名前を Batch POST-groups に変更します。
[ 高度なパラメーター ] ドロップダウンで、[本文] を選択 します。 アクションの [本文 ] テキスト ボックスに次のコードを追加します。
{
"requests": [
{
"url": "/groups",
"method": "POST",
"id": 1,
"headers": { "Content-Type": "application/json" },
"body": {
"description": "REPLACE",
"displayName": "REPLACE",
"groupTypes": ["Unified"],
"mailEnabled": true,
"mailNickname": "REPLACE",
"securityEnabled": false
}
}
]
}
各REPLACEプレースホルダーを置き換えるには、[動的コンテンツの追加] メニューから手動トリガーからName値を選択します。
[バッチ POST グループ] 項目の下にある [+] を選択し、[アクションの追加] を選択します。
delayを検索し、[遅延] アクションを追加し、1 分間構成します。
[遅延] 項目で [+] を選択し、[アクションの追加] を選択します。
MS Graph Batch Connector アクションを追加します。 省略記号を選択し、このアクションの名前を Batch PUT-team に変更します。
[ 高度なパラメーター ] ドロップダウンで、[本文] を選択 します。 アクションの [本文 ] テキスト ボックスに次のコードを追加します。
{
"requests": [
{
"id": 1,
"url": "/groups/REPLACE/team",
"method": "PUT",
"headers": {
"Content-Type": "application/json"
},
"body": {
"memberSettings": {
"allowCreateUpdateChannels": true
},
"messagingSettings": {
"allowUserEditMessages": true,
"allowUserDeleteMessages": true
},
"funSettings": {
"allowGiphy": true,
"giphyContentRating": "strict"
}
}
}
]
}
REPLACE プレースホルダーを選択し、動的コンテンツ ウィンドウで [式] を選択します。 式に次の数式を追加 します。
body('Batch_POST-groups').responses[0].body.id
この数式は、最初のアクションの結果からグループ ID を使用することを指定します。
[ 保存] を選択し、[ テスト ] を選択してフローを実行します。
ヒント
The template validation failed: 'The action(s) 'Batch_POST-groups' referenced by 'inputs' in action 'Batch_2' are not defined in the template'のようなエラーが発生した場合、式は正しく、見つからないフロー アクションを参照している可能性があります。 参照しているアクション名が正確に一致していることを確認します。
[ 手動 操作] ラジオ ボタンを選択し、[ テスト] を選択します。 スペースのない名前を指定し、[ フローの実行 ] を選択してチームを作成します。
![[フローの実行] ダイアログのスクリーン ショット](images/power-automate/run-flow.png)
最後に、[ 完了 ] を選択してアクティビティ ログを表示します。 フローが完了すると、Office 365 グループとチームが構成されています。 [バッチ] アクション項目を選択して、JSON Batch 呼び出しの結果を表示します。
Batch PUT-team アクションのoutputsは、次の図のようなチームの関連付けが成功するために、状態コードが 201 である必要があります。
フローを拡張する
前の演習で作成したフローでは、 $batch API を使用して、Microsoft Graph に対して 2 つの個別の要求を行います。
$batch エンドポイントをこのように呼び出すと、いくつかの利点と柔軟性が提供されますが、$batch エンドポイントの真の機能は、1 回の$batch呼び出しで Microsoft Graph に対して複数の要求を実行する場合に発生します。 この演習では、統合グループの作成とチームの関連付けの例を拡張して、1 つの $batch 要求にチームの複数の既定のチャネルの作成を含めます。
ブラウザーで Microsoft Power Automate を 開き、Microsoft 365 テナント管理者アカウントでサインインします。 前の手順で作成したフローを選択し、[ 編集] を選択します。
[ 新しいステップ ] を選択し、検索ボックスに「 Batch 」と入力します。
MS Graph Batch Connector アクションを追加します。 省略記号を選択し、このアクションの名前を Batch POST-channels に変更します。
アクションの 本文 テキスト ボックスに次のコードを追加します。
{
"requests": [
{
"id": 1,
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Marketing Collateral",
"description": "Marketing collateral and documentation."
}
},
{
"id": 2,
"dependsOn": [
"1"
],
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Vendor Contracts",
"description": "Vendor documents, contracts, agreements and schedules."
}
},
{
"id": 3,
"dependsOn": [
"2"
],
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "General Client Agreements",
"description": "General Client documents and agreements."
}
}
]
}
上記の 3 つの要求では dependsOn プロパティを使用してシーケンスの順序を指定しており、それぞれが POST 要求を実行して新しいチームに新しいチャネルを作成します。
REPLACE プレースホルダーの各インスタンスを選択し、動的コンテンツ ウィンドウで [式] を選択します。 式に次の数式を追加 します。
body('Batch_PUT-team').responses[0].body.id
[ 保存] を選択し、[ テスト ] を選択してフローを実行します。 [トリガー アクションを 実行します] ラジオ ボタンを選択し、[ 保存] & [テスト] を選択します。 [名前] フィールドにスペースを含まない一意のグループ名を入力し、[フローの実行] を選択してフローを実行します。
フローが開始されたら、[ 完了 ] ボタンを選択してアクティビティ ログを表示します。 フローが完了すると、 Batch POST-channels アクションの最終的な出力には、作成されたチャネルごとに 201 HTTP 状態応答があります。
Microsoft Teamsに移動し、Microsoft 365 テナント管理者アカウントでサインインします。 作成したチームが表示され、 $batch 要求によって作成された 3 つのチャネルが含まれていることを確認します。
上記の Batch POST-channels アクションは別のアクションとしてこのチュートリアルで実装されていますが、チャネルを作成するための呼び出しは、 Batch PUT-team アクションの追加の呼び出しとして追加される可能性があります。 これにより、チームとすべてのチャネルが 1 回のバッチ呼び出しで作成されます。 自分で試してみてください。
最後に、 JSON バッチ 処理の呼び出しでは、要求ごとに HTTP 状態コードが返されることに注意してください。 運用プロセスでは、結果の後処理を Apply to each アクションと組み合わせて、個々の応答に 201 の状態コードが含まれているか、受信したその他の状態コードを補正することができます。
おめでとうございます。
Power Automate Microsoft Graph チュートリアルを完了しました。 Microsoft Graph を呼び出す作業用カスタム コネクタが作成されたので、新しい機能を試して追加できます。 Microsoft Graph でアクセスできるすべてのデータについては、 Microsoft Graph の概要 に関するページを参照してください。
フィードバック
GitHub リポジトリで、このチュートリアルに関するフィードバックをお寄せください。
このセクションに問題がある場合 このセクションを改善できるよう、フィードバックをお送りください。