Power Automate 用の Microsoft Graph JSON Batch カスタムコネクタを作成する

[アーティクル]
Developer (初級)
完了まで 37 分

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 アプリ登録を作成する

残り 34 分

この演習では、カスタムコネクタの委任されたアクセス許可を提供するために使用する新しい Azure Active Directory アプリケーションを作成します。

ブラウザーを開き、 Microsoft Entra 管理センターに移動し、グローバル管理者アカウントを使用してログインします。

左側のナビゲーションで [Microsoft Entra ID] を 選択し、[ ID] を展開し、[ アプリケーション] を展開して、[ アプリの登録] を選択します。

アプリの登録のスクリーンショット

[アプリ の登録 ] ブレードの上部にある [新しい登録] メニュー項目を選択します。

Azure Active Directory 管理センターの [アプリの登録] ブレードのスクリーンショット

[名前] フィールドに「MS Graph Batch App」と入力します。 [ サポートされているアカウントの種類 ] セクション で、[任意の組織のディレクトリにあるアカウント] を選択します。 [ リダイレクト URI ] セクションは空白のままにし、[ 登録] を選択します。

Azure Active Directory 管理センターの [アプリケーションの登録] ブレードのスクリーンショット

[ MS Graph Batch App] ブレードで、 アプリケーション (クライアント) ID をコピーします。これは、次の演習で必要になります。

登録されたアプリケーションページのスクリーンショット

[MS Graph Batch App] ブレードの [管理] セクションで[API アクセス許可] エントリを選択します。 [API アクセス許可] で [アクセス許可の追加] を選択 します。

[API アクセス許可] ブレードのスクリーンショット

[ API のアクセス許可の要求 ] ブレードで、 Microsoft Graph を選択し、[ 委任されたアクセス許可] を選択します。 groupを検索し、委任されたすべてのグループの読み取りと書き込みのアクセス許可を選択します。ブレードの下部にある [ アクセス許可の追加] を選択します。

[API のアクセス許可の要求] ブレードのスクリーンショット

[MS Graph Batch App] ブレードの [管理] セクションで [証明書とシークレット] エントリを選択し、[新しいクライアントシークレット] を選択します。説明を入力し、期間を選択し、[ 追加] を選択します。

[証明書とシークレット] ブレードのスクリーンショット

新しいシークレットの値をコピーします。これは、次の演習で必要になります。

新しいクライアントシークレットのスクリーンショット

重要

このブレードを閉じるとシークレットにアクセスできなくなりますので、この手順は重要です。このシークレットをテキストエディターに保存して、今後の演習で使用します。

Teams プロパティなど、Microsoft Graph を介してアクセス可能な追加サービスの管理を有効にするには、特定のサービスの管理を有効にするために、追加の適切なスコープを選択する必要があります。たとえば、OneNote Notebook または Planner プラン、バケット、タスクを作成できるようにソリューションを拡張するには、関連する API に必要なアクセス許可スコープを追加する必要があります。

カスタムコネクタを作成する

残り 29 分

この演習では、Microsoft Power Automate または Azure Logic Apps で使用できる新しいカスタムコネクタを作成します。 OpenAPI 定義ファイルは、Microsoft Graph $batch エンドポイントの正しいパスと、単純なインポートを有効にする追加の設定で事前構築されています。

ブラウザーを開き、[ Microsoft Power Automate] に移動します。 Microsoft 365 テナント管理者アカウントでサインインします。左側のメニューで [ カスタムコネクタ ] を選択します。メニュー にカスタムコネクタ が存在しない場合は、[ その他] を選択し、[ すべて検出] を選択します。

Microsoft Graph 用のカスタムコネクタを作成するには、次の 2 つのオプションがあります。

空白から作成する
OpenAPI ファイルをインポートする

空白から作成する
OpenAPI ファイルをインポートする

[ カスタムコネクタ ] ページで、右上の [ 新しいカスタムコネクタ ] リンクを選択し、ドロップダウンメニュー の [空の項目から作成 ] を選択します。

Microsoft Power Automate の [新しいカスタムコネクタ] ドロップダウンメニューのスクリーンショット

[コネクタ名] テキストボックスに「MS Graph Batch Connector」と入力します。 Choose Continue.

コネクタ構成の [ 全般] ページで、次のようにフィールドに入力します。

スキーム: HTTPS
ホスト: graph.microsoft.com
ベース URL: /

[ セキュリティ ] ボタンを選択して続行します。

コネクタ構成の [全般] タブのスクリーンショット

[ セキュリティ ] ページで、次のようにフィールドに入力します。

API によって実装される認証を選択します。 OAuth 2.0
ID プロバイダー: Azure Active Directory
クライアント ID: 前の演習で作成したアプリケーション ID
クライアントシークレット: 前の演習で作成したキー
ログイン URL: https://login.windows.net
テナント ID: common
リソース URL: https://graph.microsoft.com (末尾 /) なし
スコープ: 空白のままにします

[ 定義 ] ボタンを選択して続行します。

コネクタ構成の [セキュリティ] タブのスクリーンショット

[ 定義 ] ページで、[ 新しいアクション ] を選択し、次のようにフィールドに入力します。

概要: Batch
説明: Execute Batch with Delegate Permission
操作 ID: Batch
可視性: important

コネクタ構成の [定義] タブのスクリーンショット

[サンプルからインポート] を選択して要求を作成し、次のようにフィールドに入力します。

動詞: POST
URL: https://graph.microsoft.com/v1.0/$batch
ヘッダー: 空白のままにします
本文: {}

[インポート] を選択します。

コネクタ構成の [サンプルからインポート] ダイアログのスクリーンショット

右上の [ コネクタの作成 ] を選択します。

テキストエディターを使用して、 MSGraph-Delegate-Batch.swagger.json という名前の新しい空のファイルを作成し、次のコードを追加します。

{
  "swagger": "2.0",
  "info": {
    "title": "MS Graph Batch Connector",
    "description": "",
    "version": "1.0"
  },
  "host": "graph.microsoft.com",
  "basePath": "/",
  "schemes": [
    "https"
  ],
  "consumes": [],
  "produces": [],
  "paths": {
    "/v1.0/$batch": {
      "post": {
        "responses": {
          "default": {
            "description": "default",
            "schema": {}
          }
        },
        "summary": "Batch",
        "description": "Execute Batch with Delegate Permission",
        "operationId": "Batch",
        "x-ms-visibility": "important",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": false,
            "schema": {
              "type": "object",
              "properties": {}
            }
          }
        ]
      }
    }
  },
  "definitions": {},
  "parameters": {},
  "responses": {},
  "securityDefinitions": {
    "oauth2_auth": {
      "type": "oauth2",
      "flow": "accessCode",
      "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
      "tokenUrl": "https://login.windows.net/common/oauth2/authorize",
      "scopes": {}
    }
  },
  "security": [
    {
      "oauth2_auth": []
    }
  ],
  "tags": []
}

[ カスタムコネクタ ] ページで、右上の [新しいカスタムコネクタ ] リンクを選択し、ドロップダウンメニューの [ OpenAPI ファイルのインポート ] 項目を選択します。

[コネクタ名] テキストボックスに「MS Graph Batch Connector」と入力します。フォルダーアイコンを選択して OpenAPI ファイルをアップロードします。作成した MSGraph-Delegate-Batch.swagger.json ファイルを参照します。 [ 続行] を選択して OpenAPI ファイルをアップロードします。

コネクタの構成ページで、ナビゲーションメニューの [ セキュリティ ] リンクを選択します。フィールドに次のように入力します。

API によって実装される認証を選択します。 OAuth 2.0
ID プロバイダー: Azure Active Directory
クライアント ID: 前の演習で作成したアプリケーション ID
クライアントシークレット: 前の演習で作成したキー
ログイン URL: https://login.windows.net
テナント ID: common
リソース URL: https://graph.microsoft.com (末尾 /) なし
スコープ: 空白のままにします

右上の [ コネクタの作成 ] を選択します。

コネクタが作成されたら、[セキュリティ] タブから生成されたリダイレクト URL をコピーします。

生成されたリダイレクト URL のスクリーンショット

前の演習で作成した Microsoft Entra ポータルで、登録済みのアプリケーションに戻ります。左側のメニューで [ 認証 ] を選択します。 [プラットフォームを追加] を選択して、[Web] を選択します。前の手順からコピーしたリダイレクト URL を [リダイレクト URI] に入力し、[ 構成] を選択します。

Azure portal の [応答 URL] ブレードのスクリーンショット

Graph エクスプローラーでバッチ処理をテストする

残り 22 分

新しいコネクタを使用するフローを作成する前に、 Microsoft Graph Explorer を使用して、Microsoft Graph での JSON バッチ処理の機能と機能の一部を検出します。

ブラウザーで Microsoft Graph エクスプローラーを開きます。 Microsoft 365 テナント管理者アカウントでサインインします。 サンプルクエリから Batch を検索します。

左側のメニューで [ 並列 GET の実行 ] サンプルクエリを選択します。画面の右上にある [ クエリの実行 ] ボタンを選択します。

グラフエクスプローラーの [サンプルクエリ] タブのスクリーンショット

このサンプルバッチ操作では、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"
    }
  ]
}

v1.0 が選択された Graph Explorer でのバッチクエリのスクリーンショット

次に、バージョンセレクタードロップダウンを使用して beta エンドポイントに変更し、まったく同じ要求を行います。

graph-explore-4

返される結果の違いは何ですか? いくつかの違いを特定するために、他のクエリを試してください。

/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"
          }
        }
      }
    }
  ]
}

バッチ内の各要求は、状態コードと結果またはエラー情報を返します。個々のバッチ操作の成功または失敗を判断するには、各応答を処理する必要があります。

フローの作成

残り 17 分

この演習では、前の演習で作成したカスタムコネクタを使用して 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値を選択します。

Microsoft Flow の動的コンテンツメニューのスクリーンショット

[バッチ 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'のようなエラーが発生した場合、式は正しく、見つからないフローアクションを参照している可能性があります。参照しているアクション名が正確に一致していることを確認します。

[ 手動操作] ラジオボタンを選択し、[ テスト] を選択します。スペースのない名前を指定し、[ フローの実行 ] を選択してチームを作成します。

[フローの実行] ダイアログのスクリーンショット

最後に、[ 完了 ] を選択してアクティビティログを表示します。フローが完了すると、Office 365 グループとチームが構成されています。 [バッチ] アクション項目を選択して、JSON Batch 呼び出しの結果を表示します。 Batch PUT-team アクションのoutputsは、次の図のようなチームの関連付けが成功するために、状態コードが 201 である必要があります。

成功したフローアクティビティログのスクリーンショット

フローを拡張する

残り 7 分

前の演習で作成したフローでは、 $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 つのチャネルが含まれていることを確認します。

新しいチームとチャネルが表示された Teams アプリのスクリーンショット

上記の Batch POST-channels アクションは別のアクションとしてこのチュートリアルで実装されていますが、チャネルを作成するための呼び出しは、 Batch PUT-team アクションの追加の呼び出しとして追加される可能性があります。これにより、チームとすべてのチャネルが 1 回のバッチ呼び出しで作成されます。自分で試してみてください。

最後に、 JSON バッチ処理の呼び出しでは、要求ごとに HTTP 状態コードが返されることに注意してください。運用プロセスでは、結果の後処理を Apply to each アクションと組み合わせて、個々の応答に 201 の状態コードが含まれているか、受信したその他の状態コードを補正することができます。

次の方法で共有

Power Automate 用の Microsoft Graph JSON Batch カスタムコネクタを作成する

前提条件

フィードバック

Azure AD アプリ登録を作成する

カスタムコネクタを作成する

コネクタを承認する

Graph エクスプローラーでバッチ処理をテストする

フローの作成

フローを拡張する

おめでとうございます。

フィードバック

次の方法で共有

Power Automate 用の Microsoft Graph JSON Batch カスタム コネクタを作成する

前提条件

フィードバック

Azure AD アプリ登録を作成する

カスタム コネクタを作成する

コネクタを承認する

Graph エクスプローラーでバッチ処理をテストする

フローの作成

フローを拡張する

おめでとうございます。

フィードバック

Power Automate 用の Microsoft Graph JSON Batch カスタムコネクタを作成する

カスタムコネクタを作成する