OpenAPI 拡張機能からカスタムコネクタを作成する

Microsoft Copilot Studio、Azure Logic Apps、Microsoft Power Automate、または Microsoft Power Apps 用のカスタムコネクタを作成する方法の 1 つは、OpenAPI 定義ファイルを提供することです。 OpenAPI 定義ファイルは、API の操作とパラメーターを記述する、言語に依存しない、コンピューターで読み取り可能なドキュメントです。 OpenAPI のすぐに使用できる機能と共に、Logic Apps と Power Automate 用のカスタムコネクタを作成するときに、次の OpenAPI 拡張機能を含めることもできます。

summary
x-ms-summary
description
x-ms-visibility
x-ms-api-annotation
x-ms-operation-context
x-ms-capabilities
x-ms-trigger
x-ms-trigger-hint
x-ms-notification-content
x-ms-notification-url
x-ms-url-encoding
x-ms-dynamic-values and x-ms-dynamic-list
x-ms-dynamic-schema and x-ms-dynamic-properties

以下のセクションでは、これらの拡張機能について説明します。

概要

アクション (操作) のタイトルを指定します。

適用対象: 操作推奨: の場合は文章式で使用します。例:「イベントがカレンダーに追加されたとき」または「メールを送信する」

各操作の概要。

"actions" {
  "Send_an_email": {
    /// Other action properties here...
    "summary": "Send an email",
    /// Other action properties here...
  }
},

x-ms-summary

エンティティのタイトルを指定します。

適用対象: パラメーター、応答スキーマ推奨: の場合はタイトルケースを使用します。例: カレンダー ID、件名、イベントの説明

各エンティティの "x-ms-summary"。

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            /// Other parameters here...
            "x-ms-summary": "Subject",
            /// Other parameters here...
        }]
    }
},

説明

操作の機能またはエンティティの形式と関数に関する詳細な説明を提供します。

適用対象: 操作、パラメーター、応答スキーマ推奨: の場合は文のケースを使用します。例: "この操作は、予定表に新しいイベントが追加されたときにトリガーされます"、"メールの件名を指定する"。

各操作やエンティティに対する「description」。

"actions" {
    "Send_an_email": {
        "description": "Specify the subject of the mail",
        /// Other action properties here...
    }
},

x-ms-visibility

ユーザーに対するエンティティの可視性を指定します。

有効な値: 、、適用対象: 操作、パラメーター、スキーマ

ユーザーは常に操作とパラメーターを最初に確認します。
ユーザーには、追加のメニューを使用する場合にのみ、操作とパラメーターが表示されます。
ユーザーには、操作とパラメーターが表示されません。

注意

およびであるパラメーターの場合、その既定値を指定する必要があります。

例: [ 詳細表示 ] メニューと [詳細オプションの表示 ] メニューでは、操作とパラメーター非表示になります。

操作とパラメーターを表示または非表示にする場合の "x-ms-visibility"。

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            "name": "Subject",
            "type": "string",
            "description": "Specify the subject of the mail",
            "x-ms-summary": "Subject",
            "x-ms-visibility": "important",
            /// Other parameter properties here...
        }]
        /// Other action properties here...
    }
},

x-ms-api-annotation

操作のバージョン管理とライフサイクル管理に使用します。

適用対象: 操作

—操作ファミリフォルダーを示す文字列。
—リビジョン番号を示す整数。
—代替 API の情報と操作を含むオブジェクト。

"x-ms-api-annotation": {
        "family": "ListFolder",
        "revision": 1,
        "replacement": {
          "api": "SftpWithSsh",
          "operationId": "ListFolder"
        }
      }

x-ms-operation-context

トリガーに依存するフローをテストできるように、このプロパティを使用してトリガーの発生をシミュレートします。

適用対象: 操作

"x-ms-operation-context": {
        "simulate": {
          "operationId": "GetItems_V2",
          "parameters": {
            "$top": 1
          }
        }

x-ms-capabilities

コネクタレベルでこのプロパティを使用すると、コネクタが提供する機能の概要 (特定の操作を含む) が示されます。

適用対象: コネクタ

"x-ms-capabilities": {
  "testConnection": {
    "operationId": "GetCurrentUser"
  },
}

操作レベルでこのプロパティを使用すると、ユーザーが指定できるチャンクアップロードと静的チャンクサイズが操作でサポートされていることを識別します。

適用対象: 操作

チャンク転送がサポートされているかどうかを示すブール値。

"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

現在の操作が 1 つのイベントを生成するトリガーであるかどうかを示します。このフィールドがない場合、操作はです。

適用対象: 操作

—オブジェクトの応答
—アレイ応答

"x-ms-trigger": "batch"

x-ms-trigger-hint

トリガー操作のイベントを発生させる方法について説明します。

適用対象: 操作

"x-ms-trigger-hint": "To see it work, add a task in Outlook."

x-ms-notification-content

Webhook 通知要求のスキーマ定義が含まれます。このスキーマは、外部サービスが通知 URL に投稿する Webhook ペイロードを定義します。

適用先: リソース

"x-ms-notification-content": {
      "schema": {
        "$ref": "#/definitions/WebhookPayload"
      }
    },

x-ms-notification-url

ブール値を使用して、このパラメーターまたは Webhook 登録操作のフィールドに Webhook 通知 URL を含めるかどうかを指定します。

適用対象: パラメーターと入力フィールド

"x-ms-notification-url": true

x-ms-url-encoding

現在のパスパラメーターで、ダブル URL エンコード () と単一 URL エンコード () のどちらを使用するかを指定します。このフィールドが見つからない場合は、既定でエンコードされます。

適用対象: パスのパラメーター

"x-ms-url-encoding": "double"

x-ms-dynamic-values

動的な値は、ユーザーが操作の入力パラメーターを選択するためのオプションのリストです。 

適用対象: パラメーター

リストを表示するための動的な値。

動的な値を使用する方法

注意

パスの文字列は、先頭のスラッシュを含まない JSON ポインターです。したがって、/property/childProperty は JSON ポインターで、property/childProperty パスの文字列です。

動的な値は、次の 2 つの方法で定義できます。

の使用

名前	必須	内容
`operationId`	はい	値を返す操作。
`parameters`	はい	dynamic-values の操作を実行するために必要な入力パラメーターを提供するオブジェクト。
`value-collection`	いいえ	応答ペイロード内のオブジェクトの配列に対して評価するパス文字列。 value-collection が指定されていない場合、応答は配列として評価されます。
`value-title`	いいえ	値の説明を参照する value-collection 内のオブジェクトのパス文字列。
`value-path`	いいえ	パラメータ値を参照する value-collection 内のオブジェクトのパス文字列。

"x-ms-dynamic-values": {
    "operationId": "PopulateDropdown",
    "value-path": "name",
    "value-title": "properties/displayName",
    "value-collection": "value",
    "parameters": {
        "staticParameter": "<value>",
        "dynamicParameter": {
            "parameter": "<name of the parameter to be referenced>"
        }
    }
}

注意

動的な値を使用すると、パラメーター参照があいまいになる可能性があります。たとえば、次の操作の定義では、動的値はフィールド ID を参照します。定義では、参照がパラメーター ID とプロパティのどちらであるかを明確にしません。

{
    "summary": "Tests dynamic values with ambiguous references",
    "description": "Tests dynamic values with ambiguous references.",
    "operationId": "TestDynamicValuesWithAmbiguousReferences",
    "parameters": [{
        "name": "id",
        "in": "path",
        "description": "The request id.",
        "required": true
    }, {
        "name": "requestBody",
        "in": "body",
        "description": "query text.",
        "required": true,
        "schema": {
            "description": "Input body to execute the request",
            "type": "object",
            "properties": {
                "id": {
                    "description": "The request Id",
                    "type": "string"
                },
                "model": {
                    "description": "The model",
                    "type": "string",
                    "x-ms-dynamic-values": {
                        "operationId": "GetSupportedModels",
                        "value-path": "name",
                        "value-title": "properties/displayName",
                        "value-collection": "value",
                        "parameters": {
                            "requestId": {
                                "parameter": "id"
                            }
                        }
                    }
                }
            }
        }
    }],
    "responses": {
        "200": {
            "description": "OK",
            "schema": {
                "type": "object"
            }
        },
        "default": {
            "description": "Operation Failed."
        }
    }
}

の使用

パラメーターを明確に参照することはできません。この機能は将来提供される可能性があります。操作で新しい更新プログラムを利用する場合は、新しい拡張機能のをと共に追加します。また、動的拡張機能がパラメーター内のプロパティを参照する場合は、新しい拡張機能をと共に追加する必要があります。プロパティを指すパラメーター参照は、パス文字列として表現する必要があります。
- —このプロパティは、静的な値フィールドまたはソース操作のプロパティへの動的参照を使用して呼び出される動的操作の各入力プロパティを定義するオブジェクトです。これらのオプションの両方を次のセクションで定義します。
- —これは、入力パラメーターに使用するリテラル値です。以下の例では、GetDynamicList 操作の version という操作名の入力パラメーターは、静的な値 2.0 を使用して定義されています。
```
{
    "operationId": "GetDynamicList",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```
- —これは完全なパラメーター参照パスで、パラメーター名の後に参照するプロパティのパス文字列が続きます。たとえば、操作 GetDynamicList の property1 という名前の入力プロパティは、パラメータ destinationInputParam1 の下にあり、property1 というプロパティ名でソース操作のパラメタ sourceInputParam1 への動的な参照を定義します。
```
{
    "operationId": "GetDynamicList",
      "parameters": {
          "destinationInputParam1/property1": {
            "parameterReference": "sourceInputParam1/property1"
    }
  }
}
```

注意

既定値で内部としてマークされているプロパティを参照するには、の代わりに、ここでの定義で既定値を静的な値として使用します。を使用して定義されている場合、一覧の既定値は使用されません。

名前	必須	内容
`operationId`	はい	リストを返す操作。
`parameters`	はい	動的なリスト操作を呼び出すのに必要な入力パラメーターを提供するオブジェクト。
`itemsPath`	いいえ	応答ペイロード内のオブジェクトの配列に対して評価するパス文字列。が指定されていない場合、応答は配列として評価されます。
`itemTitlePath`	いいえ	値の説明を参照する、内のオブジェクトのパス文字列。
`itemValuePath`	いいえ	項目の値を参照する、内のオブジェクトのパス文字列。

では、参照しているプロパティのパス文字列でパラメーター参照を使用します。これらのパラメーター参照は、動的操作パラメーター参照のキーと値の両方に使用します。

{
  "summary": "Tests dynamic values with ambiguous references",
  "description": "Tests dynamic values with ambiguous references.",
  "operationId": "TestDynamicListWithAmbiguousReferences",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "The request id.",
      "required": true
    },
    {
      "name": "requestBody",
      "in": "body",
      "description": "query text.",
      "required": true,
      "schema": {
        "description": "Input body to execute the request",
        "type": "object",
        "properties": {
          "id": {
            "description": "The request id",
            "type": "string"
          },
          "model": {
            "description": "The model",
            "type": "string",
            "x-ms-dynamic-values": {
              "operationId": "GetSupportedModels",
              "value-path": "name",
              "value-title": "properties/displayName",
              "value-collection": "cardTypes",
              "parameters": {
                "requestId": {
                  "parameter": "id"
                }
              }
            },
            "x-ms-dynamic-list": {
              "operationId": "GetSupportedModels",
              "itemsPath": "cardTypes",
              "itemValuePath": "name",
              "itemTitlePath": "properties/displayName",
              "parameters": {
                "requestId": {
                  "parameterReference": "requestBody/id"
                }
              }
            }
          }
        }
      }
    }
  ],
  "responses": {
    "200": {
      "description": "OK",
      "schema": {
        "type": "object"
      }
    },
    "default": {
      "description": "Operation Failed."
    }
  }
}

x-ms-dynamic-schema

動的スキーマは、現在のパラメーターまたは応答のスキーマが動的であることを示します。このオブジェクトでは、このフィールドの値で定義されている操作を呼び出し、動的にスキーマを検出し、ユーザー入力を収集するための適切なユーザーインターフェイスを表示または使用可能なフィールドを表示できます。

適用対象: パラメーター、応答

次の図は、ユーザーがリストから選択した項目に基づいて、入力フォームがどのように変化するかを示しています。

ユーザーが行った選択に基づいてフォームが変化します。

次の図は、ユーザーがドロップダウンリストから選択した項目に基づいて、出力がどのように変化するかを示しています。このバージョンでは、ユーザーは車を選択しています:

ユーザーが車を選択します。

このバージョンでは、ユーザーは食べ物を選択しています。

ユーザーが食べ物を選択します。

動的なスキーマを使用する方法

注意

動的スキーマは、次の 2 つの方法で定義できます。

名前	必須	内容
`operationId`	はい	スキーマを返す操作。
`parameters`	はい	スキーマ操作を呼び出すのに必要な入力パラメーターを提供するオブジェクト。
`value-path`	いいえ	スキーマを持つプロパティを参照するパス文字列。 このプロパティを指定しない場合、応答にはルートオブジェクトのプロパティにスキーマが含まれていると見なされます。指定した場合、成功した応答にはプロパティが含まれている必要があります。空のスキーマまたは未定義のスキーマの場合、この値は null である必要があります。

  {
  "name": "dynamicListSchema",
  "in": "body",
  "description": "Dynamic schema for items in the selected list",
  "schema": {
      "type": "object",
      "x-ms-dynamic-schema": {
          "operationId": "GetListSchema",
          "parameters": {
              "listID": {
                  "parameter": "listID-dynamic"
              }
          },
          "value-path": "items"
      }
    }
  }

注意

パラメーターにあいまいな参照が含まれている場合があります。たとえば、次の操作の定義では、動的スキーマは query という名前のフィールドを参照していますが、パラメーターオブジェクトの query と文字列プロパティの query/query のどちらを参照しているかを定義から確定的に判断することはできません。

{

    "summary": "Tests dynamic schema with ambiguous references",
    "description": "Tests dynamic schema with ambiguous references.",
    "operationId": "TestDynamicSchemaWithAmbiguousReferences",
    "parameters": [{
        "name": "query",
        "in": "body",
        "description": "query text.",
        "required": true,
        "schema": {
            "description": "Input body to execute the request",
            "type": "object",
            "properties": {
                "query": {
                    "description": "Query Text",
                    "type": "string"
                }
            }
        },
        "x-ms-summary": "query text"
    }],
    "responses": {
        "200": {
            "description": "OK",
            "schema": {
                "x-ms-dynamic-schema": {
                    "operationId": "GetDynamicSchema",
                    "parameters": {
                        "query": {
                            "parameter": "query"
                        }
                    },
                    "value-path": "schema/valuePath"
                }
            }
        },
        "default": {
            "description": "Operation Failed."
        }
    }
}

オープンソースコネクタの例

コネクタ	シナリオ	リンク
発券業務	選択したイベントの詳細のスキーマを取得する	発券業務

パラメータを明確に参照する方法はありません。この機能は将来提供される可能性があります。操作で新しい更新プログラムを利用する場合は、新しい拡張機能のをと共に追加します。また、動的拡張機能がパラメーター内のプロパティを参照する場合は、新しい拡張機能をと共に追加する必要があります。プロパティを指すパラメーター参照は、パス文字列として表現する必要があります。

—このプロパティは、静的な値フィールドまたはソース操作のプロパティへの動的参照を使用して呼び出される動的操作の各入力プロパティを定義するオブジェクトです。これらのオプションの両方を次のセクションで定義します。
—これは、入力パラメーターに使用するリテラル値です。次の例では、GetDynamicSchema 操作の version という名前の入力パラメーターは、静的な値 2.0 を使用して定義されています。
```
{
    "operationId": "GetDynamicSchema",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```
—パラメーター名で始まり、その後に参照されるプロパティのパス文字列が続く、パラメーターの完全な参照パスです。たとえば、操作 GetDynamicSchema の property1 という名前の入力プロパティは、パラメータ destinationInputParam1 の下にあり、property1 というプロパティ名でソース操作のパラメタ sourceInputParam1 への動的な参照を定義します。
```
{
    "operationId": "GetDynamicSchema",
      "parameters": {
          "destinationInputParam1/property1": {
            "parameterReference": "sourceInputParam1/property1"
    }
  }
}
```

注意

既定値で内部としてマークされているプロパティを参照するには、の代わりに、ここでの定義で既定値を静的な値として使用します。を使用して定義されている場合、スキーマの既定値は使用されません。

名前	必須	内容
`operationId`	はい	スキーマを返す操作。
`parameters`	はい	スキーマ操作を呼び出すのに必要な入力パラメーターを提供するオブジェクト。
`itemValuePath`	いいえ	スキーマを持つプロパティを参照するパス文字列。 これが指定されていない場合、応答はルートオブジェクトにスキーマが含まれると見なされます。指定した場合、成功した応答にはプロパティが含まれている必要があります。空のスキーマまたは未定義のスキーマの場合、この値は null である必要があります。

を使用すると、動的操作パラメーター参照のキーと値の両方に対して、参照するプロパティのパス文字列と共にパラメーター参照を使用できます。

    {
    "summary": "Tests dynamic schema with ambiguous references",
    "description": "Tests dynamic schema with ambiguous references.",
    "operationId": "TestDynamicSchemaWithAmbiguousReferences",
    "parameters": [{
        "name": "query",
        "in": "body",
        "description": "query text.",
        "required": true,
        "schema": {
            "description": "Input body to execute the request",
            "type": "object",
            "properties": {
                "query": {
                    "description": "Query Text",
                    "type": "string"
                }
            }
        },
        "x-ms-summary": "query text"
    }],
    "responses": {
        "200": {
            "description": "OK",
            "schema": {
                "x-ms-dynamic-schema": {
                    "operationId": "GetDynamicSchema",
                    "parameters": {
                        "version": "2.0",
                        "query": {
                            "parameter": "query"
                        }
                    },
                    "value-path": "schema/valuePath"
                },
                "x-ms-dynamic-properties": {
                    "operationId": "GetDynamicSchema",
                    "parameters": {
                        "version": {
                            "value": "2.0"
                        },
                        "query/query": {
                            "parameterReference": "query/query"
                        }
                    },
                    "itemValuePath": "schema/valuePath"
                }
            }
        },
        "default": {
            "description": "Operation Failed."
        }
      }
    }

次のステップ

OpenAPI 定義からカスタムコネクタを作成する

カスタムコネクタの概要

フィードバックを提供する

コネクタプラットフォームの問題点や新機能のアイデアなど、フィードバックをお待ちしています。フィードバックを提供するには、「問題を送信するか、コネクタに関するヘルプを入手する」にアクセスし、フィードバックの種類を選択します。

Last updated on 2026-03-07

次の方法で共有

OpenAPI 拡張機能からカスタム コネクタを作成する

概要

x-ms-summary

説明

x-ms-visibility

x-ms-api-annotation

x-ms-operation-context

x-ms-capabilities

x-ms-trigger

x-ms-trigger-hint

x-ms-notification-content

x-ms-notification-url

x-ms-url-encoding

x-ms-dynamic-values

動的な値を使用する方法

x-ms-dynamic-schema

動的なスキーマを使用する方法

オープンソース コネクタの例

次のステップ

関連情報

フィードバックを提供する

その他のリソース

OpenAPI 拡張機能からカスタムコネクタを作成する

オープンソースコネクタの例