准备连接器和支持 AI 的连接器文件以进行认证

完成开发 Microsoft Copilot Studio 和 Microsoft Power Platform 自定义连接器或支持 AI 的连接器文件后,您需要做好准备以进行认证。 作为经过验证的或独立的发布者,请按照以下步骤准备认证,并生成连接器或支持 AI 的连接器文件提交给 Microsoft。

备注

本文提供有关在 Azure 逻辑应用、Microsoft Power Automate、Microsoft Power Apps 中认证自定义连接器以及 Microsoft Copilot Studio 的支持 AI 的连接器文件的信息。 在按照本文中的步骤操作之前,请先阅读进行连接器和/或操作(插件)认证

步骤 1:满足连接器提交要求

为了在我们认证的连接器中保持高标准的质量和一致性,本节概述了您的自定义连接器在获得微软认证时必须遵守的一系列要求和指南。

为连接器提供标题

标题必须符合以下要求:

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

示例

  • 良好的连接器和/或操作标题:Azure Sentinel*, *Office 365 Outlook
  • 欠佳的连接器和/或操作标题:Azure Sentinel's Power Apps ConnectorOffice 365 Outlook API

为连接器编写说明

描述必须符合以下要求:

  • 确保您的描述符合市场指南
  • 必须有标题,并且必须使用英文书写。
  • 必须无语法和拼写错误。
  • 应简明扼要地描述您的连接器所提供的主要用途和价值。
  • 必须长于 30 个字符,短于 500 个字符。
  • 不能包含任何 Copilot Studio 或其他 Power Platform 产品名称(例如 Power Apps)。

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

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

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

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

摘要和说明必须符合以下要求:

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

定义确切操作响应

操作回复必须满足以下要求:

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

验证 swagger 属性

属性必须满足以下要求:

  • 确保 openapidefinition.json 是格式正确的 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 在语法上是正确的。 不要复制和粘贴摘要。 若要了解它们在产品内的显示方式,请转到连接器字符串指南

  • 如果可能,避免运行时复合字符串。 改用完整格式的语句。 串联的字符串或语句会让翻译变得困难,或可能导致错误翻译。

  • 确保缩写大写,使其清晰明了。 大写可减少被误认为排印错误的机会。

  • 如果要本地化字符串值,请修复 CAlMel 格式的字符串。 CaMel 形式的字符串(例如 minimizeHighwaysMinimizeHighways)通常不可翻译。

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

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

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

步骤 3:满足连接器操作的提交要求

如果还要提交相关的连接器操作进行认证,请务必遵守这些文章中的所有指导原则:

步骤 4:准备连接器、支持 AI 的连接器和/或项目

备注

  • 请遵守所有规范,以确保您的连接器和/或支持人工智能的连接器在认证前的质量。 否则会导致认证延迟,因为您会被要求进行更改。
  • 提供主机 URL 的生产版本。 不允许使用暂存、开发和测试主机 URL。

您向 Microsoft 提交一组文件,这是从 maker portal 或 Microsoft Copilot Studio 生成的解决方案。 若要打包文件,请按照本节中的步骤作。

连接器和支持 AI 的打包指南

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

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

  1. 在解决方案中创建自定义连接器

  2. 在步骤 1 中的连接器解决方案上运行解决方案检查器

  3. 导出连接器解决方案。

  4. 使用新创建的自定义连接器创建测试流,或将现有流添加到解决方案中

  5. 导出流解决方案。

  6. 使用步骤 3 和 5 中的解决方案创建包

  7. 创建 intro.md 文件

  8. 按以下格式将最终包创建为 zip 文件:

    要认证的经过认证的连接器的 zip 文件中文件夹和文件的屏幕截图。

备注

解决方案之外的文件夹和文件的名称仅供参考 - 您可以根据要求进行选择。 但是,请勿在解决方案内操作文件。

  1. 将包上载到存储 blob 并生成 SAS URL。 确保您的 SAS URI 在 15 天内有效。
  2. 将您的包提交到合作伙伴中心

打包自定义连接器和启用 AI 的连接器以进行认证

  1. 按照本文打包您的自定义连接器并提交进行认证中的步骤 1 到 5 操作。

  2. 在 Microsoft Copilot Studio 门户中创建插件并将其导出为解决方案

  3. 从以下步骤创建包

  4. 创建 intro.md 文件

  5. 作为 zip 文件创建最后一个包,使用以下格式。

    要认证的经过认证的连接器和插件的 zip 文件中文件夹和文件的屏幕截图。

备注

解决方案之外的文件夹和文件的名称仅供参考 - 您可以根据要求进行选择。 但是,请勿在解决方案内操作文件。

  1. 将包上载到存储 blob 并生成 SAS URL。 确保您的 SAS URI 在 15 天内有效。
  2. 将您的包提交到合作伙伴中心

打包现有的认证连接器和启用 AI 的连接器以进行认证

  1. Power Automate中创建解决方案并添加已认证的连接器。

  2. 按照本文打包您的自定义连接器并提交进行认证中的步骤 2 到 4 操作。

  3. 使用连接器操作扩展 扩展 Microsoft 365 Copilot 或 Copilot 代理

  4. 将插件导出为解决方案。

  5. 从以下步骤创建包

  6. 创建 intro.md 文件

  7. 作为 zip 文件创建最后一个包,使用以下格式。

    要认证的经过认证的现有连接器和插件的 zip 文件中文件夹和文件的屏幕截图。

备注

解决方案之外的文件夹和文件的名称仅供参考 - 您可以根据要求进行选择。 但是,请勿在解决方案内操作文件。

  1. 将包上载到存储 blob 并生成 SAS URL。 确保您的 SAS URI 在 15 天内有效。
  2. 将您的包提交到合作伙伴中心

经验证的发布者和独立发布者都在他们的构件中下载 openapidefinition.json。 您需要在此文件中设置 IconBrandColor。

  • 经过验证的发布者:在 openapidefinition 文件中将 iconBrandColor 设置为您的品牌颜色。
  • 独立发布者:在 openapidefinition 文件中将 iconBrandColor 设置为“#da3b01”。
    鲜艳的橙色 (da3b01) 图标的屏幕截图。

创建 intro.md 项目

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

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

小费

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

第 5 步:验证包的结构

包验证脚本验证包结构,并帮助您以可接受的格式生成包以供认证。 使用以下链接下载包验证程序脚本:ConnectorPackageValidator.ps1

若要运行脚本,请按照以下步骤操作:

  1. 在管理员模式下打开 Windows PowerShell。

    管理员模式下的 Windows PowerShell 屏幕截图。

  2. 通过输入 cd / 更改驱动器位置。

    以下示例使用 C:\

    用于更改驱动器的语法的屏幕截图。

  3. 转到包验证程序脚本的下载路径。

    例如,如果路径是 C:\Users\user01\Downloads,则输入 cd .\Users\user01\Downloads\

    用于更改路径的语法屏幕截图。

  4. 通过输入以下命令,将执行策略设置为不受限制:

    Set-ExecutionPolicy -ExecutionPolicy Unrestricted

    设置执行策略的语法的屏幕截图。

    此命令可以不受任何限制地执行 PowerShell。

  5. 通过输入 Y(这意味着)确认您的输入。

  6. 通过以下步骤执行 ConnectorPackageValidator.ps1

    1. 输入包含连接器包的 zip 文件路径。
    2. 指定是否启用 AI 操作。

    如以下示例所示,第一个参数是包含包的有效 zip 文件路径。 第二个参数是 yes/y,表示启用人工智能操作,或 no/n,表示禁用人工智能操作。

    显示执行 ConnectorPackageValidator.ps1 的语法。

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

    突出显示成功消息“验证成功:包结构正确”。

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

    突出显示问题详细信息消息“验证失败:包结构无效”。有关详细信息,请查看之前的消息。

第 6 步:提交连接器和/或支持 AI 的连接器进行认证

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

  1. (对于独立发布者)要将包提交给 Microsoft 进行认证,请按照独立发布者认证流程中的说明操作。

  2. (对于经过验证的发布者)要将包提交到 Microsoft,以在合作伙伴中心进行认证,请按照经过验证的发布者认证流程中的说明操作。

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

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

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

提交之前的清单

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

有关认证的查询

您需要使用 Microsoft Teams 加入办公时间会议。 如果您需要访问权限,请在 Microsoft Teams 中查看您的选项。

于 UTC(协调世界时)的每周二下午 3:30 到 4:30 加入办公时间会议

小费

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

下一步