本文提供 Microsoft Power Automate、Microsoft Power Apps、Microsoft Copilot Studio 和 Azure 逻辑应用的连接器中字符串字段的一般指南。
连接器信息
请务必提供有关连接器的基本信息。 若要开始，请遵循本节中概述的基本准则。 连接器的名称位于标题 字段中。 连接器的说明位于说明字段中。 这两个字段都显示在 OpenAPI 定义（apiDefinition.swagger.json 文件）的信息 部分中。
下面是连接器标题和说明的一些最低要求：
- 连接器标题最多有 30 个字符。
- 连接器标题和说明不能包含
API一词。 - 连接器标题和说明不能引用 Microsoft Copilot Studio 或任何其他 Microsoft Power Platform 产品。
- 连接器标题和说明不能引用您不拥有其后端 API 的产品。
有关已认证连接器指南的详细信息，请转到认证提交文章。 有关最佳实践，请参阅它。
操作
OpenAPI 定义中的每个路径和谓词对应于一项操作。 请使用下面列出的每个字符串/标记来正确地描述操作，使最终用户能够正确地使用它。 下面是操作的一些字符串字段示例：
summary：显示为操作的名称。
案例：句子
注释：
- 名称中不应该有斜杠（“/”）。
- 不应超过 80 个字符。
- 不应以非字母数字字符（包括标点符号或空格）结尾。
当选择信息按钮时，说明显示为操作说明。
。- 案例：句子。
- 注意：保持简短以适合文本框。 如果只有一个字词，则不需要句号。
operationId 是与操作相关联的唯一 ID。
- 案例：CaMel 形式（无空格或标点符号）。
- 注意：传达操作（例如 GetContacts 或 CreateContact）的含义。
下图显示摘要—发送电子邮件和说明—此操作发送电子邮件字段将在您创建工作流时出现。
触发器与操作
触发器启动工作流或流程。 以下是几个示例：
- 每周一凌晨 3 点开始工作流
- 创建对象时
确保您的“触发器摘要”和“说明”字段可读，且具有语义含义。 触发器摘要 的格式通常为：_When a ___________________。
示例:
| 触发器 | 总结 |
|---|---|
| 创建 | 任务创建时 |
| Update | 任务更新时 |
| 已删除 | 任务删除时 |
触发器说明 的格式通常为：_This operation triggers when ________________。
示例:
- 此操作在添加新任务时触发。
操作是指工作流中需要完成的任务，例如发送电子邮件、更新行 和发送通知。 下面是操作摘要 的一些示例：
| 操作 | 总结 |
|---|---|
| 创建 | 创建新任务 |
| 阅读 | 按 ID 获取任务 |
| Update | 更新对象 |
| 已删除 | 删除对象 |
| 列表 | 列出所有对象 |
参数
每项操作 (operation)（不管是触发器还是操作 (action)）都有参数，用户可以将参数作为输入提供。 参数的一些重要字符串字段有：
x-ms-summary 显示为参数名称。
- 案例：标题
- 注意：此字符串字段限制为 80 个字符
description 在输入框中显示为参数说明。
- 案例：句子
- 注意：保持说明简短以适合文本框。 如果只有一个字词，则不需要句号。
在下图中，突出显示的参数将主题 作为 x-ms-summary 字段的值，将指定邮件主题 作为 description。
响应
每项操作都有一个响应，该响应可以稍后用在工作流中，作为后续操作的输入。 结果架构由多个属性组成。 每个属性的一些重要字符串字段有：
x-ms-summary 显示为结果属性名称。
- 案例：标题
- 注意：使用简短名称。
description 显示为结果属性的说明。
- 案例：句子
- 注意：保持说明简短扼要，末尾有一个句点。
在下图中，当您尝试在工作流中的某个后续操作中添加动态内容时，会显示手动触发流 操作的结果架构。 在这里，用户电子邮件 是 x-ms-summary，其下的文本是手动触发流 操作的响应中某个属性的 description。
下面是针对 summary/x-ms-summary 和 description 字段要考虑的一些重要事项：
- 摘要和说明文本不应相同。
- 说明为用户提供额外的信息，例如输出格式或与属性相关的对象。 例如：summary：ID，description：User's ID。
- 对于具有嵌套值的对象，将父名称的 x-ms-summary 追加到子项。
可见性优先级
实体的可见性优先级由 x-ms-visibility 指定。 如果未指定可见性，该值的可见性视为“普通”。 可能的值为 important、advanced 或 internal。 标记为 internal 的实体不显示在用户界面中。
可见性适用于：
- 操作
- 参数设置
- 响应属性
下面是一个示例：
在 UI 中，标记为 important 的实体首先显示，标记为 advanced 的实体隐藏在切换开关下（突出显示），标记为 internal 的实体不显示。 下图显示了默认显示标记为 important 的参数的示例。 您还可以在选择显示高级选项按钮后，查看标记为 advanced 的参数。
提供反馈
我们非常感谢大家提出有关连接器平台问题或新功能想法的反馈。 要提供反馈，请转到提交问题或获取连接器帮助，然后选择反馈类型。