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

  • Статья

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

Эти расширения описаны в следующих разделах.

summary

Задает заголовок для действия (операции).

Применяется к: операциям.
Рекомендуется: использовать форму предложения для summary.
Пример: "При добавлении события в календарь" или "Отправить письмо"

"summary" для каждой операции.

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

x-ms-summary

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

Применяется к: параметрам, схеме ответа
Рекомендуется: использовать форму заголовка для 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.

"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

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

Применяется к: соединители

"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-Нетtification-content

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

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

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

x-ms-Нетtification-url

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

Применяется к: параметры/поля ввода

"x-ms-notification-url": true

x-ms-url-encoding

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

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

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

Использование динамических значений

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

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

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

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

Примечание

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

Есть два способа определения динамических значений:

  1. Использование x-ms-dynamic-values

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

  2. x-ms-dynamic-list

    Не существует способа однозначно ссылаться на параметры. Эта функция может быть добавлена в будущем. Если вы хотите, чтобы в вашей операции использовались последние обновления, добавьте новое расширение x-ms-dynamic-list c x-ms-dynamic-values. Кроме того, если динамическое расширение ссылается на свойства в параметрах, необходимо добавить новое расширение x-ms-dynamic-list c 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."
    }
  }
}

Использование динамической схемы

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

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

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

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

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

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

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

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

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

Примечание

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

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

  1. 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."
        }
    }
}
    Примеры из соединителей с открытым исходным кодом
    Соединитель Сценарий Ссылка
    Начисление оплаты Получить схему для подробностей выбранного события Начисление оплаты

  2. x-ms-dynamic-properties:

    Не существует способа однозначно ссылаться на параметры. Эта функция может быть добавлена в будущем. Если вы хотите, чтобы в вашей операции использовались последние обновления, добавьте новое расширение x-ms-dynamic-properties c x-ms-dynamic-schema. Кроме того, если динамическое расширение ссылается на свойства в параметрах, необходимо добавить новое расширение x-ms-dynamic-properties c 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

См. также

Обзор настраиваемых соединителей

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

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