Рекомендации по работе со строковыми полями

В этой статье приведены общие рекомендации по строковым полям в соединителе для Microsoft Power Automate, Microsoft Power Apps, Microsoft Copilot Studio и Azure Logic Apps.

Сведения о соединителе

Важно предоставить основные сведения о соединителе. Для начала следуйте основным рекомендациям, изложенным в этом разделе. В поле заголовка указывается имя соединителя. Описание соединителя помещается в поле описания. Оба поля отображаются в разделе информации в определении OpenAPI (файл apiDefinition.swagger.json).

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

• Название соединителя содержит не более 30 символов.
• В названии и описании не должно содержаться слово API.
• Заголовок и описание соединителя не могут ссылаться на Microsoft Copilot Studio или какой-либо другой продукт Microsoft Power Platform.
• В названии и описании соединителя не должны содержаться ссылки на продукт, API-интерфейсами серверной части для которого вы не владеете.

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

Операции

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

• сводка отображается как название операции.

  • Регистр: предложение

  • Примечания:

    • В имени не должно быть косой черты ("/").
    • Оно должно превышать 80 символов.
    • Оно не должно оканчиваться символом, который не является буквенно-цифровым (включая знаки пунктуации или пробел).

• описание отображается как описание операции при выборе кнопки информации. .

  • Регистр: предложение.
  • Примечания. Должно быть коротким, чтобы поместиться в текстовое поле. Точка не требуется, если есть одно слово.

• operationId — уникальный идентификатор, связанный с операцией.

  • Регистр: CaMel (без пробелов и знаков препинания).
  • Примечания. Передает значение операции, например GetContacts или CreateContact.

  На рисунке показано, как поля сводка—Отправить сообщение электронной почты и описание—Эта операция отправляет электронное письмо будут отображаться во время создания рабочего процесса.

  

Триггеры и действия

Триггер запускает рабочий процесс или процесс. Вот пара примеров:

• Запускать рабочий процесс каждый понедельник в 3 часа ночи
• При создании объекта

Убедитесь, что поля сводки и описания триггера удобочитаемые и имеют семантическое значение. Сводка триггера обычно имеет формат: _Когда ___________________.

Пример:

Описание триггера обычно имеет формат: _Эта операция срабатывает, когда ________________.

Пример:

• Эта операция запускается при добавлении новой задачи.

Действие — это задача, выполняемая в рамках рабочего процесса, например Отправить электронное письмо, Обновить строку и Отправить уведомление. Вот несколько примеров для сводки действия:

Параметры

Каждая операция (триггер или действие) имеет параметры, которые пользователь предоставляет в качестве входных данных. Некоторые из важных строковых полей для параметра следующие:

• x-ms-summary отображается как имя параметра.

  • Регистр: заголовок
  • Примечание: Это строковое поле имеет ограничение в 80 символов

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

  • Регистр: предложение
  • Примечания. Описание должно быть коротким, чтобы поместиться в текстовое поле. Точка не требуется, если есть одно слово.

  На этом рисунке показано, что выделенному параметру присвоено значение Тема для поля x-ms-summary и значение Укажите тему сообщения электронной почты для поля описание.

  

Отклик

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

• x-ms-summary отображается как имя свойства результата.

  • Регистр: заголовок
  • Примечания. Используйте краткое имя.

• описание отображается как описание для свойства результата.

  • Регистр: предложение
  • Примечания. Описание должно быть лаконичным с точкой в конце.

  На изображении схема результата из операции Запуск потока вручную отображается при попытке добавить динамическое содержимое в одну из последующих операций в рабочем процессе. Здесь Адрес электронной почты пользователя — это значение поля x-ms-summary, а текст ниже — значение поля описание для свойства в ответе операции Активировать поток вручную.

Вот несколько важных замечаний, которые нужно учитывать для полей summary/x-ms-summary и description:

• Текст сводки и описания не должен совпадать.
• Описание предоставляет дополнительные сведения пользователю (например, о формате выходных данных или объекте, с которым связано свойство). Например: сводка : ИД, описание: ИД пользователя.
• Для объекта с вложенными значениями к дочернему имени добавляется поле x-ms-summary родительского имени.

Приоритет видимости

Приоритет видимости сущности задается параметром x-ms-visibility. Если видимость не определена, значение считается обычной видимостью. Возможные значения: важный, дополнительный или внутренний. Объекты, отмеченные как внутренний, не отображаются в пользовательском интерфейсе.

Видимость распространяется на:

• Операции
• Параметры
• Свойства ответа

Приведем пример:

В пользовательском интерфейсе объекты, отмеченные как важный, отображаются первыми, объекты дополнительный отображаются с помощью переключателя (выделяются), а объекты внутренний не отображаются вообще. На изображении показан пример параметров, помеченных как важные, которые отображаются по умолчанию. Вы также можете просматривать параметры, помеченные как дополнительные, которые отображаются после выбора кнопки Показать дополнительные параметры.

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

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