Поделиться через

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

  • Статья

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

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

Каждый соединитель должен иметь заголовок, который является именем соединителя, и описание, которое описывает соединитель в целом. Эти сведения определяются в полях title и description в разделе info в определении OpenAPI (в файле apiDefinition.swagger.json).

Следующие рекомендации нужно соблюдать как минимум для названий и описаний соединителей:

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

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

Операции

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

  • Сводка: это будет отображаться как название операции.

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

  • description: это будет отображаться как описание операции при выборе кнопки информации Снимок экрана, на котором показана информационная кнопка., как показано на следующем изображении.

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

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

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

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

    Снимок экрана, на котором показано, как поля сводки и описания будут отображаться.

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

Триггер запускает рабочий процесс или процесс. Например, "Запускать рабочий процесс каждый понедельник в 03:00", "При создании объекта" и так далее.

Поля сводки и описания триггера должны быть удобочитаемыми и иметь семантическое значение. Сводка триггера обычно имеет формат: "При __________________".

Пример:

Триггер Сводка.
Создание При создании задачи
Изменить При обновлении задачи
Удален При удалении задачи

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

Пример:

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

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

Действие Сводка.
Создание Создание новой задачи
Читать Получить задачу по идентификатору
Изменить Обновление объекта
Удален Удаление объекта
Список Список всех объектов

Параметры

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

  • x-ms-summary: это будет отображаться как имя параметра.

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

  • description: это будет отображаться как описание параметра в поле ввода.

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

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

    Снимок экрана, на котором показаны значения параметра x-ms-summary и description в интерфейсе.

Отклик

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

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

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

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

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

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

Отклик

При использовании полей summary или x-ms-summary и description следует учитывать следующее:

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

x-ms-visibility

Определяет приоритет видимость сущности. Если видимость не определена, она считается обычной. Возможные значения: important (важный), advanced (дополнительный) или internal (внутренний). Объекты, отмеченные как internal (внутренний), не отображаются в пользовательском интерфейсе.

Относится к:

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

Пример:

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

Снимок экрана с раскрывающимся списком дополнительных параметров.

Снимок экрана, на котором показаны развернутые скрытые расширенные параметры.

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

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