События
Мощная конференция разработчиков и хак вместе
12 февр., 23 - 28 февр., 23
Присоединяйтесь к онлайн-конференции и 2-недельным хакатоном, чтобы изучить создание мощных решений с помощью Power Platform.
ЗарегистрироватьсяЭтот браузер больше не поддерживается.
Выполните обновление до Microsoft Edge, чтобы воспользоваться новейшими функциями, обновлениями для системы безопасности и технической поддержкой.
Один из способов создать пользовательские соединители для Azure Logic Apps, Microsoft Power Automate или Microsoft Power Apps — предоставить файл определения 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
.
Пример: "При добавлении события в календарь" или "Отправить письмо"
"actions" {
"Send_an_email": {
/// Other action properties here...
"summary": "Send an email",
/// Other action properties here...
}
},
Задает заголовок для сущности.
Применяется к: параметрам, схеме ответа
Рекомендуется: использовать форму заголовка для 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...
}
},
Задает видимость сущности для пользователя.
Возможные значения: 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...
}
},
Используется для управления версиями и жизненным циклом операции.
Применяется к: операциям.
family
— строка, которая обозначает папку для семейства операций.revision
— целое число, которое обозначает номер редакции.replacement
— объект, который содержит сведения о сведениях и операции API для замещения."x-ms-api-annotation": {
"family": "ListFolder",
"revision": 1,
"replacement": {
"api": "SftpWithSsh",
"operationId": "ListFolder"
}
}
Используется для имитации срабатывания триггера, чтобы выполнить тестирование потока, зависящего от триггера.
Применяется к: операциям.
"x-ms-operation-context": {
"simulate": {
"operationId": "GetItems_V2",
"parameters": {
"$top": 1
}
}
При использовании на уровне соединителя предоставляет общие сведения о возможностях, предлагаемых соединителем, включая определенные операции.
Применяется к: соединители
"x-ms-capabilities": {
"testConnection": {
"operationId": "GetCurrentUser"
},
}
При использовании на уровне операции позволяет указать, что операция поддерживает отправку блоками или блоки статического размера; может предоставляться пользователем.
Применяется к: операциям.
chunkTransfer
— логическое значение, которое указывает, поддерживается ли перенос блоков."x-ms-capabilities": {
"chunkTransfer": true
}
Определяет, является ли текущая операция триггером, который активирует одно событие. Отсутствие этого поля означает, что это операция action
.
Применяется к: операциям.
single
— ответ в виде объекта.batch
— ответ в виде массива."x-ms-trigger": "batch"
Описание способа запуска события для операции триггера.
Применяется к: операциям.
"x-ms-trigger-hint": "To see it work, add a task in Outlook."
Содержит определение схемы для запрашивания уведомлений веб-перехватчика. Это схема для полезных данных веб-перехватчика, опубликованных внешними службами по URL-адресу уведомления.
Применяется к ресурсам
"x-ms-notification-content": {
"schema": {
"$ref": "#/definitions/WebhookPayload"
}
},
Определяет с помощью логического значения, нужно ли добавить URL-адрес уведомления в этот параметр или поле для операции регистрации веб-перехватчика.
Применяется к: параметры/поля ввода
"x-ms-notification-url": true
Определяет, какое кодирование URL-адреса нужно применить к текущему параметру пути: двойное (double
) или единичное (single
). Отсутствие этого поля означает, что используется кодирование single
.
Применяется к: параметры Path
"x-ms-url-encoding": "double"
Динамические значения представляют собой список параметров, из которых пользователь может выбрать входные параметры для операции.
Применяется к: параметрам
Примечание
Строка пути — это указатель JSON, который не содержит начальной прямой косой черты. Например, это указатель JSON: /property/childProperty, а это — строка пути: property/childProperty.
Есть два способа определения динамических значений:
Использование 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."
}
}
}
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.
Есть два способа определения динамических схем:
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
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
Обзор пользовательских соединителей
Для нас очень важны отзывы о проблемах с нашей платформой соединителей и новые идеи о функциях. Чтобы оставить отзыв, выберите пункт Сообщить о проблемах или получить помощь с соединителями и выберите тип отзыва.
События
Мощная конференция разработчиков и хак вместе
12 февр., 23 - 28 февр., 23
Присоединяйтесь к онлайн-конференции и 2-недельным хакатоном, чтобы изучить создание мощных решений с помощью Power Platform.
ЗарегистрироватьсяОбучение
Схема обучения
Use advance techniques in canvas apps to perform custom updates and optimization - Training
Use advance techniques in canvas apps to perform custom updates and optimization
Сертификация
Microsoft Certified: Dynamics 365: Finance and Operations Apps Developer Associate - Certifications
Реализуйте и расширяйте приложения финансов и операций в Microsoft Dynamics 365.