从 OpenAPI 定义创建自定义连接器

简介

本文是一个完整教程系列中的重要组成部分，旨在帮助用户理解如何在多种平台上创建和使用自定义连接器。这些平台包括 Azure 逻辑应用、Microsoft Power Automate 和 Microsoft Power Apps，它们是现代企业自动化和应用集成的核心工具。

自定义连接器的主要功能是通过连接到外部API来扩展这些平台的能力，使用户能够实现更复杂、更个性化的业务流程。本文特别专注于通过使用 OpenAPI 定义 来创建自定义连接器，这是构建连接器的一种标准化且高效的方法。

在深入教程之前，建议用户先阅读相关的概述文章。这些概述文章能够帮助用户全面了解整个创建自定义连接器的流程，并为后续深入学习做准备。例如，通过了解自定义连接器的基本概念、工作原理以及在不同平台中的应用场景，用户可以更清楚地理解如何利用本文中的步骤实现特定需求。

先决条件

在开始创建自定义连接器之前，需要满足一些基本条件。这些条件确保您能够顺利完成操作，并使连接器能够正常运行。以下是详细说明：

• OpenAPI定义：要创建一个自定义连接器，首先需要准备一个描述目标API的OpenAPI定义文件。这是连接器识别API操作和数据结构的关键。需要注意的是，OpenAPI定义必须符合以下要求：

  • 文件大小需小于1MB，确保其能够被平台正常处理。
  • 格式必须是 OpenAPI 2.0（之前称为Swagger），因为目前不支持OpenAPI 3.0格式。

• API密钥：认知服务文本分析 API 的访问需要一个有效的API密钥。该密钥用于身份验证，确保连接器能够与API进行交互并获取所需数据。您可以通过 Azure 门户或相关服务获取此密钥。

  
  

• 支持的订阅：创建和使用自定义连接器需要您拥有以下平台之一的订阅：

  • Azure：适用于逻辑应用。
  • Power Automate：用于自动化流程。
  • Power Apps：用于构建应用程序。

• 逻辑应用：如果您选择使用Azure逻辑应用平台，请确保已提前创建一个逻辑应用。这是后续步骤中导入OpenAPI定义并配置连接器的基础。

  
  

满足这些先决条件后，您将能够流畅地开始创建自定义连接器，并确保其与目标API正确集成。

导入 OpenAPI 定义

导入 OpenAPI 定义是创建自定义连接器的核心步骤之一。通过正确导入定义文件，您可以快速配置连接器并使其能够与目标API交互。以下将详细说明如何在不同平台上完成导入操作。

在 Azure 门户中导入定义以创建逻辑应用连接器

如果您正在使用 Azure 逻辑应用，以下步骤可帮助您导入 OpenAPI 定义并创建自定义连接器：

• 登录到 Azure 门户，找到之前创建的逻辑应用连接器。

• 导航至连接器的菜单，选择逻辑应用连接器，然后点击编辑以进入编辑模式。

  
  

• 在编辑界面中，找到常规设置，选择上传 OpenAPI 文件，然后浏览您的本地文件以选择目标定义文件。

  
  

完成上传后，逻辑应用将自动解析定义文件，并提取其中的API操作和数据结构。这些数据将被用于配置连接器的功能。

在 Power Automate 和 Power Apps中导入定义以创建自定义连接器

对于 Power Automate 和 Power Apps，导入 OpenAPI 定义的步骤略有不同，但同样简单直接：

• 登录到 Power Apps 或 Power Automate 平台。

• 在左侧菜单中，点击数据，然后选择自定义连接器。

• 点击新建自定义连接器，随后选择导入 OpenAPI 文件。

• 为连接器输入一个名称，例如“SentimentDemo”，然后上传您的 OpenAPI 定义文件。点击继续以完成导入。

  
  

导入完成后，Power Automate 和 Power Apps会自动读取定义文件中的信息，并为连接器设置必要的配置。

配置参数和文件路径

在导入过程中，确保您上传的 OpenAPI 定义文件包含以下关键信息：

• API操作：定义文件需清晰描述API的操作类型（如POST或GET）以及对应的路径。
• 数据结构：定义文件需包含API的输入参数和响应数据的结构信息。
• 身份验证信息：如果API需要身份验证（如API密钥或OAuth），需在定义文件中正确配置相关字段。

导入完成后，您可以进一步检查导入的内容，并在平台的连接器编辑器中进行调整，以确保所有参数和路径与目标API匹配。

定义和更新连接器

在创建自定义连接器的过程中，定义和优化连接器的行为是一个至关重要的步骤。通过合理配置连接器的各项参数，您可以提高其用户体验和功能表现。以下是关于如何查看、编辑和更新连接器定义的详细说明。

查看连接器的常规信息、请求参数和响应配置

自定义连接器的定义页面提供了全面的视图，展示了连接器的各种配置和交互行为。以下是主要内容：

• 常规信息：您可以在定义页面顶部查看连接器的基本信息，比如名称、API主机地址和基础URL。这些信息是连接器调用API的基础。

  
  

• 请求参数：连接器的请求部分展示了API的具体调用方式，包括所需的HTTP谓词（如POST或GET）、路径和相关的参数。通过此部分，您可以了解API的输入需求。

  
  

• 响应配置：定义页面还包含连接器返回的数据配置，展示API调用成功时的响应结构和数据类型。这些信息对用户理解API返回的内容非常重要。

编辑定义以优化连接器的用户体验

为了使连接器更便于用户使用，可以对其定义进行调整和优化。以下是一些实用的编辑方法：

• 在常规区域中，您可以修改连接器操作的显示属性。例如，可以将某些参数设置为高级（隐藏在高级选项中）或重要（优先显示给用户）。

• 在请求部分，您可以编辑参数的描述，使其更清晰易懂。例如，为每个参数添加详细说明，帮助用户理解其作用和输入要求。

• 通过编辑响应部分，您可以明确返回数据的结构和格式，让用户对API的输出有更直观的理解。

通过向导更新连接器定义的流程

使用平台提供的向导工具，可以轻松更新连接器的定义。以下是具体的操作步骤：

1. 在定义页面中选择请求区域，点击正文并选择编辑。

2. 进入参数编辑界面，修改每个参数的名称、描述或数据类型，以确保与API的要求一致。

3. 返回到定义页面，检查所有配置是否正确。如果发现任何问题，可通过验证区域查看平台检测到的错误或警告。

4. 在右上角点击更新连接器，保存您的修改。此操作将使更新后的定义立即生效。

通过以上步骤，您可以确保连接器的定义准确无误，并优化其交互体验，使其更好地服务用户需求。

测试和使用自定义连接器

在完成自定义连接器的创建和定义后，下一步就是对它进行测试，以确保其正常运行并能够正确调用目标API。测试是验证连接器功能的重要环节，同时也是发现潜在问题并进行优化的机会。以下是详细的测试和使用连接器的步骤。

测试连接器的具体步骤

测试连接器的目的是验证其与API的交互是否正确。以下是测试的流程：

• 进入连接器的测试页面。在该页面中，您可以查看连接器的状态，并开始创建新的连接。

• 点击新建连接按钮，系统会提示您输入API密钥或其他必要的身份验证信息。

  
  

• 完成连接创建后，返回到测试页面。在测试字段中输入示例数据，比如测试API的输入参数，然后点击测试操作按钮。

• 系统会调用API并返回响应数据，您可以查看结果是否符合预期。例如，检查返回的情绪分数是否准确反映输入的文本。

通过以上步骤，您可以确保连接器正确调用API并返回预期结果。如果测试过程中出现问题，建议检查连接器定义中的配置，特别是请求参数和身份验证信息。

创建连接并输入 API 密钥

连接器的测试通常需要一个有效的连接，这意味着您需要输入API密钥或其他身份验证信息。以下是创建连接的操作说明：

• 在测试页面，点击新建连接。

• 根据连接器的定义，输入API密钥（例如认知服务文本分析 API 的密钥），确保您的连接能够与目标API进行交互。

• 点击创建连接按钮，系统会验证密钥并创建有效的连接。

完成连接创建后，您可以在测试页面中进行更深入的功能验证，并确保连接器能够正确处理API请求和响应。

在不同平台中使用已创建的连接器

测试完成后，您可以在多个平台上使用已创建的自定义连接器，例如 Power Automate、Power Apps 和 Azure 逻辑应用。以下是具体的使用方法：

• Power Automate：在自动化流程中添加您的连接器作为操作节点。例如，可以创建一个流程，当收到新文本时，使用连接器调用API以分析情绪。

• Power Apps：将连接器集成到应用程序中，供用户直接调用。例如，用户可以输入文本，应用通过连接器分析情绪并显示结果。

• Azure 逻辑应用：在逻辑应用中使用连接器作为步骤节点，实现复杂的工作流。例如，可以将情绪分析连接器与其他API或数据处理步骤结合使用。

  
  

通过这些平台，您可以充分利用自定义连接器的功能，实现业务流程的自动化和优化。

为 Microsoft 365 Copilot 创建连接器

Microsoft 365 Copilot 是一个强大的工具，可以通过集成各种连接器来扩展其功能。如果您希望将自定义连接器与 Copilot 集成，可以基于 OpenAPI 定义创建连接器，并按照以下步骤进行配置。同时，连接器还可以共享或认证，以便组织内外的用户使用。

根据 OpenAPI 定义创建连接器并集成到 Copilot

创建与 Microsoft 365 Copilot 集成的连接器需要一个详细的 OpenAPI 定义文件，它描述了目标 API 的操作和数据结构。以下是具体步骤：

• 首先，确保您已经准备好符合 OpenAPI 2.0 规范的定义文件。定义文件中需要清晰描述 API 的路径、请求参数、响应格式以及身份验证信息。

• 登录到 Power Apps 或 Power Automate 平台，创建一个新的自定义连接器。

  
  

• 上传定义文件后，根据平台的向导完成连接器的配置，例如设置连接器的名称（如“CopilotSentimentConnector”），并定义 API 的操作和参数。

• 在完成连接器的创建和测试后，您可以通过 Copilot 将其集成到具体的场景中，例如自动分析销售数据或生成情绪分析报告。

通过这些步骤，您可以将自定义连接器无缝集成到 Microsoft 365 Copilot 中，为用户提供更智能、更高效的体验。

共享或认证连接器以供组织内外使用

创建完成后，您可以选择共享或认证连接器，以便其他用户或团队能够使用它。这为连接器的应用和扩展提供了更多可能性。以下是具体操作方式：

• 共享连接器：您可以将连接器分享给组织内的其他用户或团队。在 Power Apps 或 Power Automate 平台中，选择连接器后点击共享选项。共享的连接器可以在同一组织的环境中使用。

• 认证连接器：如果您希望连接器能够被组织外的用户使用，可以通过认证流程使其成为公开连接器。认证连接器需要满足微软的审核标准，包括功能的稳定性、安全性以及文档的完整性。

  • 提交认证申请，附上详细的连接器定义和相关说明文档。
  • 完成审核后，连接器将被注册为公开连接器，供更广泛的用户访问。

共享和认证连接器不仅能够提高连接器的使用率，还能够推动其在更大范围内的应用，为组织和个人提供更多的价值。

提供反馈

用户反馈是改善连接器平台的重要途径。无论是发现问题还是提出新功能建议，您的意见都能帮助开发团队优化平台性能和功能，使其更好地满足用户需求。以下是关于如何提交反馈的详细说明。

鼓励用户提交问题或新功能建议

连接器平台的持续改进离不开用户的积极参与。如果您在使用过程中遇到任何问题，例如功能异常、配置错误或性能不佳，请不要犹豫提交反馈。此外，如果您有关于新功能的创意或建议，也欢迎与开发团队分享。以下是一些常见的反馈场景：

• 问题反馈：例如，连接器无法正确调用API、参数配置错误或其他技术故障。

• 功能建议：例如，如何优化用户界面、增加更多的集成功能或支持新的API格式。

• 性能改进：例如，提高连接器的响应速度或减少资源消耗。

您的反馈不仅能够帮助解决具体问题，还能推动平台的创新和发展，为所有用户创造更好的使用体验。

如何提交反馈或获取帮助

为了方便用户提交反馈或寻求帮助，连接器平台提供了多种渠道。以下是具体步骤：

• 访问 反馈页面，这是专门用于收集用户意见的入口。

• 选择适合您的反馈类型，例如“报告问题”或“功能建议”。根据页面提示填写详细信息，包括问题描述、复现步骤或建议内容。

• 如果您需要技术支持，可以通过页面上的帮助选项联系支持团队。确保提供足够的背景信息，例如连接器的配置详情和问题发生的时间。

此外，您还可以参与连接器社区讨论，与其他用户分享经验或解决问题。这不仅能帮助您快速找到解决方案，还能为平台的发展贡献自己的力量。

持续改进连接器平台

通过用户提交的问题和建议，开发团队可以持续优化连接器平台。例如，修复用户报告的漏洞、添加新功能或提升平台的稳定性。您的每一条反馈都可能成为改进的关键推动力。

我们鼓励所有用户积极参与反馈流程，共同打造一个更强大、更高效的连接器平台。