Microsoft Flow でのカスタム コネクタ用の OpenAPI 拡張OpenAPI extensions for custom connectors in Microsoft Flow

概要Introduction

Microsoft Flow、Azure Logic Apps、または Microsoft PowerApps のカスタム コネクタを作成するには、API の操作とパラメーターが記述された、言語に依存しない、コンピューターが読み取れるドキュメントである OpenAPI の定義ファイルを指定する必要があります。To create custom connectors for Microsoft Flow, Azure Logic Apps, or Microsoft PowerApps, you must provide an OpenAPI definition file, which is a language-agnostic machine-readable document that describes your API's operations and parameters. OpenAPI のすぐに使用可能な機能と共に、Logic Apps と Flow のカスタム コネクタを作成する際にこれらの OpenAPI 拡張機能を含めることもできます。Along with OpenAPI's out-of-the-box functionality, you can also include these OpenAPI extensions when you create custom connectors for Logic Apps and Flow:

  • summary
  • x-ms-summary
  • description
  • x-ms-visibility
  • x-ms-dynamic-values
  • x-ms-dynamic-schema

これらの拡張機能の詳細を以下に示します。Here are more details about these extensions:

概要summary

アクション (操作) のタイトルを指定します。Specifies the title for the action (operation).
適用対象: 操作Applies to: Operations
推奨: summary文頭を大文字にします。Recommended: Use sentence case for summary.
例: "When an event is added to calendar" または "Send an email"Example: "When an event is added to calendar" or "Send an email"

各操作の "summary"

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

x-ms-summaryx-ms-summary

エンティティのタイトルを指定します。Specifies the title for an entity.
適用対象: パラメーター、応答スキーマApplies to: Parameters, Response Schema
推奨: x-ms-summaryタイトルの各単語の先頭を大文字にします。Recommended: Use title case for x-ms-summary.
例: "Calendar ID"、"Subject"、"Event Description" などExample: "Calendar ID", "Subject", "Event Description", and so on

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

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

説明description

操作の機能、またはエンティティの形式と機能についての詳細な説明を指定します。Specifies a verbose explanation about the operation's functionality or an entity's format and function.
適用対象: 操作、パラメーター、応答スキーマApplies to: Operations, Parameters, Response Schema
推奨: description文頭を大文字にします。Recommended: Use sentence case for description.
例: "This operation triggers when a new event is added to the calendar"、"Specify the subject of the mail." などExample: "This operation triggers when a new event is added to the calendar", "Specify the subject of the mail.", and so on

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

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

x-ms-visibilityx-ms-visibility

ユーザーに対するエンティティの可視性を指定します。Specifies the user-facing visibility for an entity.
使用可能な値: importantadvanced、および internalPossible values: important, advanced, and internal
適用対象: 操作、パラメーター、スキーマApplies to: Operations, Parameters, Schemas

  • important 操作とパラメーターは常に、最初にユーザーに表示されます。important operations and parameters are always shown to the user first.
  • advanced 操作とパラメーターは追加メニューで非表示になります。advanced operations and parameters are hidden under an additional menu.
  • internal 操作とパラメーターはユーザーに対して非表示になります。internal operations and parameters are hidden from the user.

注意

internal および required であるパラメーターの場合、その既定値を指定する必要があります。For parameters that are internal and required, you must provide default values for these parameters.

例: [詳細] メニューと [詳細オプションの表示] メニューでは、advanced 操作とパラメーターは非表示になります。Example: The See more menu and Show advanced options menu are hiding advanced operations and parameters.

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

ユーザーが操作の入力パラメーターを選択できるように、設定済みリストを表示します。Shows a populated list for the user so they can select input parameters for an operation.
適用対象: パラメーターApplies to: Parameters
使用方法: パラメーターの定義に x-ms-dynamic-values オブジェクトを追加します。How to use: Add the x-ms-dynamic-values object to the parameter's definition. 例については、この OpenAPI サンプルを参照してください。For example, see this OpenAPI sample.

リストを表示する場合の "x-ms-dynamic-values"

x-ms-dynamic-values のプロパティProperties for x-ms-dynamic-values

Name (名前)Name 必須または省略可能Required or optional 説明Description
operationIDoperationID 必須Required リストを設定するために呼び出す操作。The operation to call for populating the list.
value-pathvalue-path 必須Required パラメーター値を参照する、value-collection 内のオブジェクトのパス文字列。A path string in the object inside value-collection that refers to the parameter value. value-collection が指定されていない場合、応答は配列として評価されます。If value-collection isn't specified, the response is evaluated as an array.
value-titlevalue-title 省略可能Optional 値の説明を参照する、value-collection 内のオブジェクトのパス文字列。A path string in the object inside value-collection that refers to the value's description. value-collection が指定されていない場合、応答は配列として評価されます。If value-collection isn't specified, the response is evaluated as an array.
value-collectionvalue-collection 省略可能Optional 応答ペイロード内のオブジェクトの配列に対して評価するパス文字列。A path string that evaluates to an array of objects in the response payload
parametersparameters 省略可能Optional dynamic-values 操作を呼び出すのに必要な入力パラメーターをプロパティで指定するオブジェクト。An object whose properties specify the input parameters required to invoke a dynamic-values operation

x-ms-dynamic-values でプロパティを表示する例を以下に示します。Here's an example that shows the properties in x-ms-dynamic-values:

"x-ms-dynamic-values": {
  "operationId": "PopulateDropdown",
  "value-path": "name",
  "value-title": "properties/displayName",
  "value-collection": "value",
  "parameters": {
     "staticParameter": "{value}",
     "dynamicParameter": {
        "parameter": "{value-to-pass-to-dynamicParameter}"
     }
  }
}

例: 現時点までのすべての OpenAPI 拡張機能Example: All the OpenAPI extensions up to this point

"/api/lists/{listID-dynamic}": {
    "get": {
        "description": "Get items from a single list - uses dynamic values and outputs dynamic schema",
        "summary": "Gets items from the selected list",
        "operationID": "GetListItems",
        "parameters": [
           {
             "name": "listID-dynamic",
             "type": "string",
             "in": "path",
             "description": "Select the list from where you want outputs",
             "required": true,
             "x-ms-summary": "Select List",
             "x-ms-dynamic-values": {
                "operationID": "GetLists",
                "value-path": "id",
                "value-title": "name"
             }
           }
        ]
    }
}

x-ms-dynamic-schemax-ms-dynamic-schema

現在のパラメーターまたは応答のスキーマが動的であることを示します。Indicates that the schema for the current parameter or response is dynamic. このオブジェクトでは、このフィールドの値で定義されている操作を呼び出し、動的にスキーマを検出し、ユーザー入力を収集するための適切な UI を表示または使用可能なフィールドを表示できます。This object can invoke an operation that's defined by the value of this field, dynamically discover the schema, and display the appropriate UI for collecting user inputs or show available fields.

適用対象: パラメーター、応答Applies to: Parameters, Response

使用方法: 要求パラメーターまたは応答本文の定義に x-ms-dynamic-schema オブジェクトを追加します。How to use: Add the x-ms-dynamic-schema object to a request parameter or response body definition. 例については、この OpenAPI サンプルを参照してください。For an example, see this OpenAPI sample.

この例では、ユーザーがドロップダウン リストから選択する項目に基づいて、入力フォームがどのように変わるかを示します。This example shows how the input form changes, based on the item that the user selects from the drop-down list:

動的パラメーターの "x-ms-dynamic-schema"

また、この例では、ユーザーがドロップダウン リストから選択する項目に基づいて、出力がどのように変わるかを示します。And this example shows how the outputs change, based on the item that the user selects from the drop-down list. このバージョンでは、ユーザーは "Cars" を選択しています。In this version, the user selects "Cars":

選択された項目 "Cars" の "x-ms-dynamic-schema-response"

このバージョンでは、ユーザーは "Food" を選択しています。In this version, the user selects "Food":

選択された項目 "Food" の "x-ms-dynamic-schema-response"

x-ms-dynamic-schema のプロパティProperties for x-ms-dynamic-schema

Name (名前)Name 必須または省略可能Required or optional 説明Description
operationIDoperationID 必須Required スキーマをフェッチするために呼び出す操作。The operation to call for fetching the schema
parametersparameters 必須Required dynamic-schema 操作を呼び出すのに必要な入力パラメーターをプロパティで指定するオブジェクト。An object whose properties specify the input parameters required to invoke a dynamic-schema operation
value-pathvalue-path 省略可能Optional スキーマを持つプロパティを参照するパス文字列。A path string that refers to the property that has the schema.
これが指定されていない場合、応答は、ルート オブジェクトのプロパティにスキーマが含まれると見なされます。If not specified, the response is assumed to contain the schema in the root object's properties.

動的パラメーターの例を以下に示します。Here's an example for a dynamic parameter:

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

動的応答の例を以下に示します。Here's an example for a dynamic response:

"DynamicResponseGetListSchema": {
   "type": "object",
   "x-ms-dynamic-schema": {
      "operationID": "GetListSchema",
      "parameters": {
         "listID": {
            "parameter": "listID-dynamic"
         }
      },
      "value-path": "items"
    }
}

次のステップNext steps

カスタム コネクタを登録しますRegister a custom connector.

ASP.NET Web API を使用しますUse an ASP.NET Web API.

Azure Resource Manager API を登録しますRegister an Azure Resource Manager API.