扩展自定义连接器的 OpenAPI 定义

项目
06/23/2023

若要创建 Azure 逻辑应用、Microsoft Power Automate 或 Microsoft Power Apps 的自定义连接器，一种方法是提供 OpenAPI 定义文件，该文件是一个描述 API 操作和参数的不区分语言的机器可读文档。配合 OpenAPI 的现成可用的功能，在为逻辑应用和 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 使用句子首字母大写。
示例：“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 使用句子首字母大写。
示例：“This operation is triggered when a new event is added to the calendar”、“Specify the subject of the mail”

每个操作或实体的“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 通知 URL 置于 Webhook 注册操作的此参数/字段中。

适用于：参数/输入字段

"x-ms-notification-url": true

x-ms-url-encoding

标识当前路径参数应该为双 URL 编码 double 还是单 URL 编码 single。缺少此字段指示 single 编码。

适用于：路径参数

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

使用动态值

动态值是供用户为操作选择输入参数的选项列表。 

适用于：参数 

显示列表的动态值。

如何使用动态值

备注

路径字符串是不包含前导正斜线的 JSON 指针。所以，这是一个 JSON 指针：/property/childProperty，这是一个路径字符串：property/childProperty。

可以通过两种方式定义动态值：

使用 x-ms-dynamic-values

客户	必选	描述
operationId	是	返回值的操作。
参数	是	提供调用动态值操作所必需的输入参数的对象。
value-collection	否	计算结果为响应有效负载中的对象数组的路径字符串。如果未指定值集合，响应将评估为数组。
value-title	否	引用值的说明的值集合内对象中的路径字符串。
值-路径	否	引用参数值的值集合内对象中的路径字符串。

"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—这是完整的参数引用路径，以参数名称开头，后面是要引用的属性的路径字符串。例如，参数 destinationInputParam1 下名为 property1 的操作 GetDynamicList 的输入属性，被定义为对源操作的参数 sourceInputParam1 下名为 property1 的属性的动态引用。

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

备注

若要引用任何已使用默认值标记为 internal 的属性，必须在此处的定义中将默认值用作静态值，而不能使用 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."
    }
  }
}

使用动态架构

动态架构指示当前参数或响应的架构为动态。此对象调用由此字段中的值定义的操作，动态发现架构，并显示用于收集用户输入的适当用户界面或显示可用字段。

适用于：参数、响应

此图像显示输入窗体如何基于用户从列表中选择的项目而变化：

窗体根据用户所做的选择更改。

此图像显示输出如何基于用户从下拉列表中选择的项目而变化。在此版本中，用户选择汽车：

用户选择汽车。

在此版本中，用户选择食物：

用户选择食物。

如何使用动态架构

备注

路径字符串是不包含前导正斜线的 JSON 指针。所以，这是一个 JSON 指针：/property/childProperty，这是一个路径字符串：property/childProperty。

可以通过两种方式定义动态架构：

x-ms-dynamic-schema：

客户	必选	描述
operationId	是	返回架构的操作。
参数	是	提供调用动态架构操作所必需的输入参数的对象。
值-路径	否	引用具有该架构的属性的路径字符串。如果未指定，响应应在根对象的属性中包含该架构。如果指定，成功的响应中必须包含此属性。对于空架构或未定义的架构，此值应该为 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—这是完整的参数引用路径，以参数名称开头，后面是要引用的属性的路径字符串。例如，参数 destinationInputParam1 下名为 property1 的操作 GetDynamicSchema 的输入属性，被定义为对源操作的参数 sourceInputParam1 下名为 property1 的属性的动态引用。

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

备注

若要引用任何已使用默认值标记为 internal 的属性，必须在此处的定义中将默认值用作静态值，而不能使用 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 定义

摘要

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

使用动态值

如何使用动态值

使用动态架构

如何使用动态架构

开放源代码连接器的示例

下一步

另请参见

提供反馈

其他资源