了解适用于字符串字段的最佳实践

以下文章包含 Power Automate、Power Apps 和 Azure 逻辑应用的连接器中字符串字段的一般指南。

连接器信息

每个连接器应该有一个标题（即连接器的名称）和一个说明（对连接器进行概括说明）。该信息应该在 OpenAPI 定义（在 apiDefinition.swagger.json 文件中）的 info 部分下的 title 和 description 字段中指定。

对于连接器标题和说明，至少应遵循以下准则：

可在此处找到针对认证连接器强制实施的、更高的标题和说明字段指南标准，并应将其用作最佳做法。

OpenAPI 定义中的每个路径和谓词对应于一项操作。请使用下面的每个字符串/标记来正确地描述操作，使最终用户能够正确地使用它。操作的一些字符串字段有：

summary：将显示为操作的名称。
- 案例：句子
- 注释：
  - 名称中不应该有斜杠（“/”）。
  - 不应超过 80 个字符。
  - 不应以非字母数字字符（包括标点符号或空格）结尾。
说明：当选择信息按钮时，此信息将显示为操作说明，如下图所示。
- 案例：句子。
- 注意：保持简短以适合文本框。如果只有一个字词，则不需要句号。
operationId：这是与操作相关联的唯一 ID。
- 案例：CaMel 形式（无空格或标点符号）。
- 注意：用于传达操作（例如 GetContacts 或 CreateContact）的含义。
下图显示_摘要_—发送电子邮件和_说明_—此操作发送电子邮件字段将在您创建工作流时出现。

触发器启动工作流或流程。例如，“每星期一凌晨 3 点启动工作流”、“创建对象时”，等等。

“触发器摘要”和“说明”字段应是人类可读的，具有语义含义。触发器_摘要_的格式通常为：“When a __________________”。

示例:

触发器_说明_通常采用的格式为：“此操作在_______________时触发”

示例:

操作是指工作流中需完成的任务，例如“发送电子邮件”、“更新行”、“发送通知”等。下面给出了一些操作_摘要_的示例：

每项操作 (operation)（不管是触发器还是操作 (action)）都有参数，用户可以将参数作为输入提供。参数的一些重要字符串字段有：

x-ms-summary：将显示为参数名称。
- 案例：标题
- 注意：长度不得超过 80 个字符
description：将在输入框中显示为参数说明。
- 案例：句子
- 注意：保持简短以适合文本框。如果只有一个字词，则不需要句号。
在下面显示的图片中，突出显示的参数将“主题”作为 x-ms-summary 字段的值，将“指定邮件主题”作为 description。

每项操作都有一个响应，该响应可以稍后用在工作流中，作为后续操作的输入。结果架构由多个属性组成。每个属性的一些重要字符串字段有：

x-ms-summary：将显示为结果属性名称。
- 案例：标题
- 注意：使用简短名称。
description：将显示为结果属性的说明。
- 案例：句子
- 注意：应该简明扼要，末尾有一个句点。
在下面所示的图像中，当您尝试在工作流中的某个后续操作中添加动态内容时，会显示“手动触发流”操作的结果架构。在这里，“用户电子邮件”是 x-ms-summary，其下的文本是“手动触发流”操作的响应中某个属性的 description。

就 summary/x-ms-summary 和 description 字段来说，通常需要考虑的一些重要事项包括：

确定实体的可见性优先级。如果未指定可见性，则会将该项的可见性视为“普通”。可能的值为“important”、“advanced”或“internal”。标记为“internal”的实体不显示在用户界面中。

适用范围：

示例:

在 UI 中，标记为“important”的实体首先显示，标记为“advanced”的实体隐藏在切换开关下（突出显示），标记为“internal”的实体不显示。下图是默认显示标记为“important”的参数的示例。另外还显示在选择显示高级选项按钮后显示的标记为“advanced”的参数。

显示高级选项的下拉列表的屏幕截图。

显示展开的隐藏高级选项的屏幕截图。

我们非常感谢大家提出有关连接器平台问题或新功能想法的反馈。要提供反馈，请转到提交问题或获取连接器帮助，然后选择反馈类型。