准备 Power Platform 连接器和插件文件进行认证

项目
08/17/2024

此过程适用于经过验证的发布者和独立发布者。

完成自定义连接器和/或插件的开发后，请执行以下步骤为其做好认证准备，并生成要提交给 Microsoft 的连接器和/或插件文件。

备注

本文介绍如何认证 Azure 逻辑应用、Power Automate 和 Power Apps 中的自定义连接器以及 Copilot 中的插件。在按照本文中的步骤操作之前，请先阅读进行连接器和/或插件认证。

步骤 1：注册连接器和/或插件（仅适用于独立发布者）

本节不适用于经过验证的发布者。

无需完成自定义连接器和/或插件开发即可申请认证。要开始认证流程，请填写我们的注册表单来注册要认证的连接器和/或插件。

预计会在两个工作日内收到 Microsoft 联系人的电子邮件，他将：

了解您的自定义连接器、连接器和/或插件。
了解您的开发进度。
向您发送有关认证过程的电子邮件。

步骤 2：满足连接器提交要求

为了在我们的认证连接器之间保持高标准的质量和一致性，Microsoft 有一套要求和准则，您的自定义连接器必须遵守这些要求和准则才能获得认证。

为连接器提供标题

标题必须满足以下要求。

必须有标题，并且必须使用英文书写。
必须是唯一的，并且必须与任何现有的连接器和/或插件标题相区分。
应为您的产品或组织的名称。
应该遵守已认证连接器和/或插件的现有命名模式。对于独立发布者，连接器名称应采用模式 Connector and/or plugin Name (Independent Publisher)。
长度不能超过 30 个字符。
不能包含单词 API、Connector 或我们的任意 Power Platform 产品名称（例如 Power Apps）。
不能以非字母数字字符结尾，包括回车符、换行符或空格。

示例

合格的连接器和/或插件标题：Azure Sentinel*, *Office 365 Outlook
不合格的连接器和/或插件标题：Azure Sentinel's Power Apps Connector、Office 365 Outlook API

为连接器编写说明

说明必须满足下列要求。

必须有标题，并且必须使用英文书写。
必须无语法和拼写错误。
应简明扼要地描述您的连接器所提供的主要用途和价值。
不能短于 30 个字符或超过 500 个字符。
不能包含任何 Power Platform 产品名称（例如，“Power Apps”）。

为连接器设计图标（仅适用于经过验证的发布者）

本节不适用于独立发布者。

在 100 x 100 到 230 x 230 像素范围内创建 1:1 尺寸的徽标（无圆角）。
使用与您指定的图标背景颜色相匹配的非透明的非白色 (#ffffff) 背景和非默认颜色 (#007ee5)。
确保图标为任何其他已认证的连接器图标所特有。
提交 PNG 格式的徽标作为 <icon>.png。
将徽标尺寸设置为图像高度和宽度的 70% 以下，背景保持一致。
确保品牌颜色是有效的十六进制颜色，而不是白色 (#ffffff) 或默认颜色 (#007ee5)。

定义操作和参数摘要及说明

摘要和说明必须满足下列要求。

必须有标题，并且必须使用英文书写。
必须无语法和拼写错误。
操作和参数摘要应为包含 80 个字符或更少的短语，并且只能包含字母数字字符或括号。
操作和参数说明应该是完整的描述性句子并以标点符号结尾。
不能包含任何 Microsoft Power Platform 产品名称（例如 "Power Apps"）。

定义确切操作响应

操作响应必须满足下列要求。

应定义仅包含预期响应的具有精确架构的操作响应。
不要使用具有精确架构定义的默认响应。
为 Swagger 中的所有操作提供有效的响应架构定义。
除非在响应架构是动态这一特殊情况下，否则不允许使用空响应架构。这意味着输出中不会显示动态内容，制作者必须使用 JSON 来解析响应。
不允许使用空操作。
除非需要，否则删除空属性。

验证 swagger 属性

属性必须满足下列要求。

确保“openapidefinition”位于格式正确的 JSON 文件中。
确保 swagger 定义符合 OpenAPI 2.0 标准和连接器扩展标准。

验证连接参数

参数必须满足下列要求。

确保使用 "UIDefinition"（显示名称，描述）的适当值更新该属性。

如果您的连接参数使用基本身份验证，请确保 JSON 格式正确，如下例所示。

{
  "username": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourUsernameLabel",
      "description": "The description of YourUsernameLabel for this api",
      "tooltip": "Provide the YourUsernameLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": true,
        "required": "true"
        }
  }
},
  "password": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourPasswordLabel",
      "description": "The description of YourPasswordLabel for this api",
      "tooltip": "Provide the YourPasswordLabel tooltip text",
      "constraints": {
        "tabIndex": 3,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

如果您的连接参数使用 APIKey 作为身份验证，请确保 JSON 的格式正确，如下例所示。

{
  "api_key": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourApiKeyParameterLabel",
      "tooltip": "Provide your YourApiKeyParameterLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

如果您的连接参数使用通用 OAuth 作为身份验证，请确保 JSON 的格式正确，如下例所示。

{
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "oauth2",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "AuthorizationUrl": {
          "value": "https://contoso.com"
        },
        "TokenUrl": {
          "value": "https://contoso.com"
        },
        "RefreshUrl": {
          "value": "https://contoso.com"
        }
      },
      "clientId": "YourClientID"
    },
    "uiDefinition": null
  }
}

如果您的连接参数包含 OAuth2 身份提供者，请确保该身份提供者来自受支持的 OAuth2 提供者列表。以下是 GitHub OAuth2 身份提供者的示例：

{
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "github",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {},
      "clientId": "YourClientId"
    },
    "uiDefinition": null
  }
}

如果您的连接参数具有 Microsoft Entra ID 作为身份验证，请确保 JSON 的格式正确，如下例所示。

{
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "aad",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "LoginUri": {
          "value": "https://login.microsoftonline.com"
        },
        "TenantId": {
          "value": "common"
        },
        "ResourceUri": {
          "value": "resourceUri"
        },
        "EnableOnbehalfOfLogin": {
          "value": false
        }
      },
      "clientId": "AzureActiveDirectoryClientId"
    },
    "uiDefinition": null
  }
}

创建高质量的英语语言字符串

连接器将作为 Power Automate 本地化的一部分进行本地化；因此，当您开发连接器时，英语语言字符串的质量是翻译质量的关键。在创建所提供的字符串值时，需要重点关注以下几个主要方面。

确保运行拼写检查程序，以确保所有字符串值都没有排字错误。如果有任何不完整的英语字符串，翻译结果是不完整的或上下文不正确的。
确保语句格式完整。如果语句不完整，也会产生较低质量的翻译。
确保语句意思清晰。如果语句的意思不明确，也会产生较低质量或不正确的翻译。
确保 summaries、x-ms-summaries 和 descriptions 在语法上是正确的。不要进行复制和粘贴。若要了解它们在产品中的显示方式，请转到连接器字符串指南。
如果可能，避免运行时复合字符串。改用完整格式的语句。串联的字符串或语句会让翻译变得困难，或可能导致错误翻译。
如果您使用缩写，请确保将它们大写以清晰显示。这减少了被误认为是印刷错误的机会。
CaMel 形式的字符串（例如，minimizeHighways 或 MinimizeHighways）通常被视为不可翻译。如果您想要本地化此字符串值，您应该修复 CaMel 形式的字符串。

步骤 3：运行解决方案检查器来验证连接器

解决方案检查器是一种进行静态分析的机制，以确保您的连接器符合 Microsoft 认证所要求的标准。将连接器添加到 Power Automate 或 Power Apps 中的解决方案，并按照使用解决方案检查器验证自定义连接器中的说明运行解决方案检查器。

观看此视频，了解如何运行解决方案检查器。

步骤 4：添加元数据

您的连接器项目（文件）必须包含描述连接器及其终端服务的特定元数据。元数据中提供的信息发布在我们的连接器文档中，所有用户都可以公开访问。不要提供任何私人或机密信息，如果在向我们提供此信息时有任何问题，请通过您的 Microsoft 联系人告知我们。要了解元数据是如何记录的，请访问连接器参考下任何一个特定于连接器的文档页面。

步骤 4a：发布者和 stackOwner 属性

发布者是您的公司或组织的名称。提供完整的公司名称（例如，“Contoso Corporation”）。必须为字母数字格式。
“stackOwner” 是连接器连接到的后端服务堆栈的负责公司或组织。必须为字母数字格式。

发布服务器	Description	示例
已验证	发布者和 stackOwner 是相同的，除非 ISV 代表一个 stackOwner 构建一个连接器。	"publisher": "Tesla"， "stackOwner": "Tesla"
独立	您必须提供堆栈负责人和发布者负责人。	"publisher": "Nirmal Kumar"， "stackOwner": "ITGlue"

文件位置： openapidefinition.json

语法： publisher 和 stackOwner 属性作为顶级属性存在于openapidefinition.json文件中。添加如下所示的突出显示的行。确保完全按照如下所示输入属性名称和架构。

显示发布者和堆栈负责人属性的屏幕截图，这些属性在示例代码片段中提供。

步骤 4c：示例代码片段

您可以使用以下代码片段复制和输入信息。确保按前面部分所述在正确位置将片段添加到正确的文件。

    "publisher": "_____",
    "stackOwner": "_____"

    "contact": {
      "name": "_____",
      "url": "_____",
      "email": "_____"
    }

    "x-ms-connector-metadata": [
      {
        "propertyName": "Website",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Privacy policy",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Categories",
        "propertyValue": "_____;_____"
      }
    ]

备注

当前使用 stackOwner 属性和 Paconn CLI 工具时存在限制。有关详细信息，请参阅 README 文件中的限制。

步骤 4d：JSON 文件格式和限制

确保您的属性已正确对齐。
将 JSON 粘贴到 Visual Studio Code 中。随意使用拼写检查器等扩展和 JSON 插件等插件。
Swagger 文件不应大于 1 MB。
- 在开始构建连接器之前考虑连接器的设计。评估连接器是否应分解为两 (2) 个或更多连接器。
- 使用连接器时，较大的 swagger 文件可能会导致延迟。
例如，平台上有三 (3) 个不同的 HubSpot 连接器。

步骤 5：满足插件提交要求

如果您还提交相关的连接器插件进行认证，本节适用。

确保您按照为 Microsoft Copilot 创建 AI 插件（预览）中的指南创作插件。
提交的所有 AI 插件都应符合 100.10 不恰当内容中突出显示的标准。
所有 AI 插件都应符合负责任 AI 准则。
插件不能生成、包含或提供对不恰当、有害或攻击性人工智能 (AI) 生成的内容的访问，内容应符合 100.10 不恰当内容中列出的现有商业市场政策。

步骤 6：准备连接器和/或插件项目

备注

在认证之前，请确保您遵循了规格并确保连接器和/或插件的质量。否则，会导致认证延迟，因为系统会要求您进行更改。
提供主机 URL 的生产版本。不允许使用暂存、开发和测试主机 URL。

你要向 Microsoft 提交一组文件，这是从制作者门户 Microsoft Copilot Studio 或生成的解决方案。要打包文件，请跟随本节中的步骤操作。

连接器和插件打包指南

本节中的过程将指导您完成各个打包场景。如果只想打包自定义连接器，请使用第一种方案。如果要同时打包自定义连接器和插件，请使用第二种方案。如果要打包 现有的 连接器和插件，请使用最后一种方案。

打包您的自定义连接器并提交进行认证
打包您的自定义连接器和插件以进行认证
打包现有的经过认证的连接器和插件以进行认证

打包您的自定义连接器并提交进行认证

创建解决方案的自定义连接器。
在步骤 1 中的连接器解决方案上运行解决方案检查器。
导出连接器解决方案。
使用新创建的自定义连接器创建流（测试）并将流添加到解决方案。
导出流解决方案。
使用步骤 3 和 5 中的解决方案创建包。
创建 intro.md 文件。
作为 zip 文件创建最后一个包，使用以下格式：

备注

The names of the folder and files outside the solution are only for reference—you can choose as per your requirements. However, don't manipulate the files inside the solution.

将包上载到存储 blob 并生成 SAS URL。请确保 SAS URI 的有效期至少为 15 天。
将您的包提交到合作伙伴中心。

打包您的自定义连接器和插件以进行认证

按照本文打包您的自定义连接器并提交进行认证中的步骤 1 到 5 操作。
在 Microsoft Copilot Studio 门户中创建插件并将其导出为解决方案。
从以下步骤创建包：
- 运行解决方案检查器（打包您的自定义连接器并提交进行认证中的步骤 2）。
- 导出流解决方案（打包您的自定义连接器并提交进行认证中的步骤 5）。
- 在 Microsoft Copilot Studio 中创建插件并将其导出为解决方案（此过程中的步骤 2）。
创建 intro.md 文件。
作为 zip 文件创建最后一个包，使用以下格式。

备注

The names of the folder and files outside the solution are only for reference—you can choose as per your requirements. However, don't manipulate the files inside the solution.

将包上载到存储 blob 并生成 SAS URL。请确保 SAS URI 的有效期至少为 15 天。
将您的包提交到合作伙伴中心。

打包现有的经过认证的连接器和插件以进行认证

在 Power Automate 中创建解决方案，然后在其中添加经过认证的连接器。
按照本文打包您的自定义连接器并提交进行认证中的步骤 2 到 4 操作。
在 Copilot Studio 中创建插件并将其导出为解决方案。
将插件导出为解决方案。
从以下步骤创建包：
- 在连接器解决方案上运行解决方案检查器（本文打包您的自定义连接器并提交进行认证中的步骤 2）。
- 在 Copilot Studio 中创建插件并将其导出为解决方案（此过程中的步骤 3）。
- 在 Copilot Studio 中创建插件并将其导出为解决方案（此过程中的步骤 4）。
创建 intro.md 文件。
作为 zip 文件创建最后一个包，使用以下格式。

备注

The names of the folder and files outside the solution are only for reference—you can choose as per your requirements. However, don't manipulate the files inside the solution.

将包上载到存储 blob 并生成 SAS URL。请确保 SAS URI 的有效期至少为 15 天。
将您的包提交到合作伙伴中心。

经过验证的发布者和独立发布者都会在其项目中下载 openapidefinition.json 。您需要在此文件中设置 IconBrandColor。

已验证的发布者：在 openapidefinition 文件中将 iconBrandColor 设置为您的品牌颜色。
独立发布者：在 openapidefinition 文件中将 iconBrandColor 设置为 “#da3b01”。

创建 intro.md 项目

独立发布者和经过验证的发布者都需要 intro.md 文件。您需要创建一个 intro.md 文件来记录连接器的特性和功能。有关要包括的文档的示例，请转到 Readme.md 示例。要了解如何编写 intro.md 文件，请查看我们的 GitHub 存储库中的其他 intro.md 文件（也称为 Readme.md 文件）。

如果您是独立发布者并且您的连接器使用 OAuth，请确保包括有关如何获取凭据的说明。

提示

已知问题和限制是一个需要维护的重要部分，可以让您的用户及时了解最新信息。

步骤 7：验证包的结构

包验证脚本验证包结构，并帮助您以可接受的格式生成包以进行认证。使用此链接下载包验证器脚本： ConnectorPackageValidator.ps1。

要运行脚本，请跟随以下步骤操作：

在管理员模式下打开 Windows PowerShell。
通过输入更改 cd / 驱动器位置。

以下示例使用 C:\。
转到下载包验证器脚本的路径。

例如，如果路径是， C:\Users\user01\Downloads 则输入 cd .\Users\user01\Downloads\。
通过输入以下命令，将执行策略设置为不受限制：

Set-ExecutionPolicy -ExecutionPolicy Unrestricted

此命令使 PowerShell 可以不受任何限制地执行。
输入 Y 以确认您的输入，这意味着是。
执行 ConnectorPackageValidator.ps1 with the following steps：
1. 输入包含连接器包的 zip 文件路径。
2. 指定是否启用 AI 插件。
如以下示例所示，第一个参数是包含包的有效 zip 文件路径。第二个参数是 yes/y 指示 AI 插件已启用，或 no/n 指示它已禁用。

如果包结构正确，则会显示以下成功消息：

如果包结构存在问题，脚本会通过检测和突出显示包结构中的缺陷来提供问题详细信息。

步骤 8：提交连接器和/或插件以进行认证

在提交过程中，您将向我们的 Microsoft Power Platform 连接器存储库开放您的连接器和/或插件源代码。

（对于独立发布者）要将包提交给 Microsoft 进行认证，请按照独立发布者认证流程中的说明操作。
（对于经过验证的发布者）要将包提交到 Microsoft，以在合作伙伴中心进行认证，请按照经过验证的发布者认证流程中的说明操作。

如果您是经验证的发布者，并且使用自定义代码，则需要提交 script.csx 文件。

如果您的连接器具有 OAuth，在合作伙伴中心提供客户端 ID 和机密。此外，从连接器提交请求中获取 APIname 以更新应用程序。

作为提交的一部分，Microsoft 会对您的连接器和/或插件进行认证。如果您需要解决 Swagger 错误，请转到修复 Swagger 验证者错误。

提交之前的清单

在继续提交您的连接器以获得 Microsoft 认证之前，请确保：

您的连接器和/或插件满足步骤 2：满足连接器提交要求、步骤 5：满足插件提交要求和步骤 4：添加元数据中设置的所有标准。
没有任何操作缺少摘要、说明或可见性信息。
您已经测试了自定义连接器和/或插件以确保操作按预期运行（每个操作至少有 10 次成功的调用）。
自定义连接器向导的测试部分没有显示运行时或架构验证错误。

提示

创建 YouTube 视频、博客或其他内容来分享示例或屏幕截图，让用户了解如何开始使用连接器和/或插件。
在 intro.md 文件中包含链接，以便我们可以将其添加到文档中。
将工具提示添加到您的 swagger 文件中，以帮助您的用户取得更大的成功。

通过

准备 Power Platform 连接器和插件文件进行认证

步骤 1：注册连接器和/或插件（仅适用于独立发布者）

步骤 2：满足连接器提交要求

为连接器提供标题

为连接器编写说明

为连接器设计图标（仅适用于经过验证的发布者）

定义操作和参数摘要及说明

定义确切操作响应

验证 swagger 属性

验证连接参数

创建高质量的英语语言字符串

步骤 3：运行解决方案检查器来验证连接器

步骤 4：添加元数据

步骤 4a：发布者和 stackOwner 属性

步骤 4c：示例代码片段

步骤 4d：JSON 文件格式和限制

步骤 5：满足插件提交要求

步骤 6：准备连接器和/或插件项目

连接器和插件打包指南

打包您的自定义连接器并提交进行认证

打包您的自定义连接器和插件以进行认证

打包现有的经过认证的连接器和插件以进行认证

创建 intro.md 项目

步骤 7：验证包的结构

步骤 8：提交连接器和/或插件以进行认证

提交之前的清单

下一步

其他资源