Создание пользовательского соединителя с расширением OpenAPI

Одним из способов создания пользовательских соединителей для Microsoft Copilot Studio, Azure Logic Apps, Microsoft Power Automate или Microsoft Power Apps является предоставление файла определения OpenAPI. Файл определения OpenAPI — это не зависящий от языка и машинный документ, описывающий операции и параметры API. Наряду с встроенными функциями OpenAPI можно также включить следующие расширения OpenAPI при создании пользовательских соединителей для Logic Apps и Power Automate:

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.
Пример: "При добавлении события в календарь" или "Отправить письмо"

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

x-ms-summary

Задает заголовок для сущности.

Область применения: параметры, схема ответа
Рекомендация: используйте регистр "как заголовках" для 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

Задает видимость сущности для пользователя.

Возможные значения: important, advanced и internal
Область применения: операции, параметры, схемы

Пользователь всегда видит important операции и параметры сначала.
Пользователь видит advanced операции и параметры только при использовании дополнительного меню.
Пользователь не видит internal операции и параметры.

Заметка

Для параметров internal и requiredнеобходимо предоставить значения по умолчанию.

Пример. Дополнительные сведения и отображение меню расширенных параметров скрывают advanced операции и параметры.

"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 для замещения и операции этого 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

Содержит определение схемы для запроса уведомлений веб-перехватчика. Это схема определяет полезные данные веб-перехватчика, публикуемые внешними службами по URL-адресу уведомления.

Применяется к ресурсам

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

x-ms-notification-url

Используйте логическое значение, чтобы указать, следует ли включать URL-адрес уведомления веб-перехватчика в этот параметр или поле для операции регистрации веб-перехватчика.

Область применения: параметры и поля ввода

"x-ms-notification-url": true

x-ms-url-encoding

Укажите, должен ли текущий параметр пути использовать двойную кодировку URL-адресов (double) или однокодирование URL-адресов (single). Если это поле отсутствует, по умолчанию используется кодировка single .

Область применения: параметры путей

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

x-ms-dynamic-values

Динамические значения представляют собой список параметров, из которых пользователь может выбрать входные параметры для операции. 

Применяется к: параметрам

Динамические значения для отображения списков.

Как использовать динамические значения

Заметка

Строка пути — это указатель JSON, который не содержит начальной прямой косой черты. Например, это указатель JSON: /property/childProperty, а это — строка пути: property/childProperty.

Динамические значения можно определить двумя способами:

Используйте x-ms-dynamic-values

Имя (название)	Требуется	Описание
`operationId`	Да	Операция, которая возвращает значения.
`parameters`	Да	Объект, который предоставляет входные параметры, необходимые для вызова операции с динамическими значениями.
`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 или на свойство 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`	Да	Операция, которая возвращает список.
`parameters`	Да	Объект, который предоставляет входные параметры, необходимые для вызова операции с динамическим списком.
`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."
    }
  }
}

x-ms-dynamic-schema

Динамическая схема указывает , что схема для текущего параметра или ответа является динамической. Этот объект вызывает операцию, которая определяется значением в данном поле, динамически обнаруживает схему и отображает соответствующий пользовательский интерфейс для сбора входных данных пользователя или отображения доступных полей.

Применяется к: параметрам, ответам

На следующем рисунке показано, как изменяется входная форма на основе элемента, выбранного пользователем из списка:

Форма меняется в зависимости от выбора, который делает пользователь.

На следующем рисунке показано, как изменяются выходные данные на основе элемента, выбранного пользователем из раскрывающегося списка. В этой версии пользователь выбирает элемент Автомобили:

Пользователь выбирает автомобили.

В этой версии пользователь выбирает элемент Еда:

Пользователь выбирает еду.

Как использовать динамическую схему

Заметка

Динамическую схему можно определить двумя способами:

x-ms-dynamic-schema:

Имя (название)	Требуется	Описание
`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."
        }
    }
}

Примеры из соединителей open source

Соединитель	Сценарий	Ссылка
Ticketing	Получить схему для подробностей выбранного события	Система обработки заявок

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`	Да	Операция, которая возвращает схему.
`parameters`	Да	Объект, который предоставляет входные параметры, необходимые для вызова операции с динамической схемой.
`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

Общие сведения о пользовательских соединителях

Предоставление отзыва

Мы очень ценим отзывы о проблемах с нашей платформой соединителей и новые идеи о функциях. Чтобы оставить отзыв, выберите пункт Сообщить о проблемах или получить помощь с соединителями и выберите тип отзыва.

Last updated on 2026-03-12

Создание пользовательского соединителя с расширением 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

Как использовать динамическую схему

Примеры из соединителей open source

Следующий шаг

Дополнительные сведения

Предоставление отзыва

Дополнительные ресурсы