カスタムコネクタの OpenAPI 定義を拡張する

[アーティクル]
06/23/2023

Azure Logic Apps、Microsoft Power Automate、または Microsoft Power Apps のカスタムコネクタを作成する 1 つの方法は、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

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

summary

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

適用対象: 操作
推奨: summary の文頭を大文字にします。
例: "When an event is added to calendar" または "Send an email"

各操作の "summary"。

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

x-ms-summary

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

適用対象: パラメーター、応答スキーマ
推奨: x-ms-summary のタイトルの各単語の先頭を大文字にします。
例: "Calendar ID"、"Subject"、"Event Description"

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

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

description

操作の機能、またはエンティティの形式と機能についての詳細な説明を指定します。

適用対象: 操作、パラメーター、応答スキーマ
推奨: description の文頭を大文字にします。
例: "この操作は新規イベントがカレンダーに追加された場合にトリガーされます"、"メールの件名を指定してください"

各操作またはエンティティの "description"。

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

x-ms-visibility

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

使用可能な値: important、advanced、internal
適用対象: 操作、パラメーター、スキーマ

important 操作とパラメーターは常に、最初にユーザーに表示されます。
advanced 操作とパラメーターは追加メニューで非表示になります。
internal 操作とパラメーターはユーザーに対して非表示になります。

注意

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

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

操作とパラメーターを表示または非表示にする場合の "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

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

適用対象: 操作

family— 操作ファミリフォルダーを示す文字列。
revision— リビジョン番号を示す整数。
replacement— 代替 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"
  },
}

操作レベルで使用される場合、操作がチャンクアップロードや静的チャンクサイズをサポートし、ユーザーが指定できることを示すために使用します。

適用対象: 操作

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

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

x-ms-trigger

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

適用対象: 操作

single— オブジェクト応答
batch— 配列応答

"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 エンコード double にするか、シングル URL エンコード single にするかを示します。このフィールドがない場合は、single エンコードを示します。

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

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

動的な値を使用する

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

適用対象: パラメーター 

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

動的な値を使用する方法

注意

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

動的な値を定義するには、次の 2 つの方法があります。

x-ms-dynamic-values の使用

件名	必要な領域	内容
operationId	有効	値を返す操作。
パラメーター	有効	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、またはプロパティ requestBody/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."
        }
    }
}

x-ms-dynamic-list

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

parameters— このプロパティは、呼び出される動的操作の各入力プロパティが、静的な値フィールドまたはソース操作のプロパティへの動的参照のいずれかで定義されるオブジェクトです。これらのオプションの両方を以下に定義します。
value— 入力パラメーターに使用されるリテラル値です。以下の例では、GetDynamicList 操作の version という操作名の入力パラメーターは、静的な値 2.0 を使用して定義されています。
```
{
    "operationId": "GetDynamicList",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```

parameterReference— パラメーター名で始まり、その後に参照されるプロパティのパス文字列が続く、パラメーターの完全な参照パスです。たとえば、操作 GetDynamicList の property1 という名前の入力プロパティは、パラメータ destinationInputParam1 の下にあり、property1 というプロパティ名でソース操作のパラメタ sourceInputParam1 への動的な参照を定義します。

{
    "operationId": "GetDynamicList",
      "parameters": {
          "destinationInputParam1/property1": {
            "parameterReference": "sourceInputParam1/property1"
    }
  }
}

注意

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

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

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

{
  "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."
    }
  }
}

動的スキーマを使用する

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

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

このイメージでは、ユーザーがリストから選択する項目に基づいて、入力フォームがどのように変わるかを示します。

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

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

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

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

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

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

注意

動的なスキーマを定義するには、次の 2 つの方法があります。

x-ms-dynamic-schema:

件名	必要な領域	内容
operationId	有効	スキーマを返す操作。
パラメーター	有効	スキーマ操作を呼び出すのに必要な入力パラメーターを提供するオブジェクト。
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."
        }
    }
}

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

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

x-ms-dynamic-properties:

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

parameters— このプロパティは、呼び出される動的操作の各入力プロパティが、静的な値フィールドまたはソース操作のプロパティへの動的参照のいずれかで定義されるオブジェクトです。これらのオプションの両方を以下に定義します。
value— 入力パラメーターに使用されるリテラル値です。次の例では、GetDynamicSchema 操作の version という名前の入力パラメーターは、静的な値 2.0 を使用して定義されています。
```
{
    "operationId": "GetDynamicSchema",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```

parameterReference— パラメーター名で始まり、その後に参照されるプロパティのパス文字列が続く、パラメーターの完全な参照パスです。たとえば、操作 GetDynamicSchema の property1 という名前の入力プロパティは、パラメータ destinationInputParam1 の下にあり、property1 というプロパティ名でソース操作のパラメタ sourceInputParam1 への動的な参照を定義します。

{
    "operationId": "GetDynamicSchema",
      "parameters": {
          "destinationInputParam1/property1": {
            "parameterReference": "sourceInputParam1/property1"
    }
  }
}

注意

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

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

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

    {
    "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 定義からカスタムコネクタを作成する

参照

カスタムコネクタの概要

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

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

カスタム コネクタの 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

動的な値を使用する

動的な値を使用する方法

動的スキーマを使用する

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

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

次のステップ

参照

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

その他のリソース

カスタムコネクタの OpenAPI 定義を拡張する

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