Power Platform 自定义连接器 Schema 开发指南：基于 paconn 的 Swagger 2.0、API Properties 与 Settings 全解析-北京尧图网络

Power Platform 自定义连接器 Schema 开发指南基于 paconn 的 Swagger 2.0、API Properties 与 Settings 全解析【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilotPower Platform 自定义连接器Custom Connector是打通外部 API 与 Power Apps、Power Automate 等平台能力的关键桥梁而驱动它的核心是paconnPower Apps Connector工具所校验的三类 JSON Schema 定义。本篇指南以本仓库 instructions/power-platform-connector.instructions.md 为骨架系统讲解apiDefinition.swagger.json、apiProperties.json与settings.json三个文件的结构、Microsoft 扩展x-ms-*语义、校验规则、常见模式与排错方法并结合仓库内 MCP 集成专家 Agent、连接器生成 Skill 等资源补充实战背景。读完本文你将能够独立编写、校验并交付符合 Power Platform 生态规范的连接器 Schema。项目背景三份文件构成连接器的全部骨架在 Power Platform 中一个自定义连接器由三份 JSON Schema 文件共同描述分别对应连接器的不同关注面API DefinitionsapiDefinition.swagger.json采用 Swagger 2.0 格式定义 API 的路径、操作、参数、响应与安全模型并允许叠加 Power Platform 专属扩展API PropertiesapiProperties.json定义连接器元数据、认证配置Connection Parameters与策略模板Policy Template InstancesSettingssettings.json为paconn工具提供环境与部署配置包括环境 GUID、文件路径映射、API 端点PROD/TIP1与版本号。这三份文件在仓库中的 MCP 集成场景下被进一步强化。例如 skills/power-platform-mcp-connector-suite/SKILL.md 要求生成连接器时同时产出apiDefinition.swagger.json含x-ms-agentic-protocol: mcp-streamable-1.0的/mcp端点、apiProperties.json含元数据与认证、script.csxJSON-RPC 2.0 转换逻辑与readme.mdinstructions/power-platform-mcp-development.instructions.md 则进一步规定 Schema 设计需移除$ref、只使用单一类型等 Copilot Studio 约束。理解这三份基础 Schema是所有上层集成模式的前提。一、apiDefinition.swagger.jsonSwagger 2.0 Power Platform 扩展该文件是整个连接器的核心包含标准 Swagger 2.0 属性info、paths、definitions等并叠加三类 Power Platform 专属能力Microsoft 扩展以x-ms-*前缀命名的扩展属性用于描述触发器、动态参数、分页、可见性等平台行为自定义 format 类型如date-no-tz无时区偏移的日期时间与html客户端呈现 HTML 编辑器/查看器动态 Schema 支持允许在运行时根据用户选择动态调整参数结构提供更高的交互灵活性安全定义原生支持 OAuth2、API Key 与 Basic Auth 三种认证方式。1.1 操作级 Microsoft 扩展编写操作Operation时以下扩展用于控制用户界面呈现与平台行为扩展名作用关键取值x-ms-summary用户友好的显示名称必须使用 Title Case任意展示字符串x-ms-visibility控制参数可见性important、advanced、internalx-ms-trigger将操作标记为触发器batch、singlex-ms-trigger-hint触发器使用提示文本引导用户操作的说明文字x-ms-trigger-metadata定义触发器配置含kind与mode属性如kind: query、mode: pollingx-ms-notification配置 Webhook 操作以支持实时通知Webhook 配置对象x-ms-pageable启用分页需指定nextLinkName如{nextLinkName: odata.nextLink}x-ms-safe-operation将无副作用的 POST 操作标记为安全操作truex-ms-no-generic-test禁用特定操作的自动测试truex-ms-operation-context配置操作模拟simulation设置含simulate对象与operationId1.2 参数级 Microsoft 扩展参数Parameter上的扩展主要服务于动态交互与输入体验x-ms-dynamic-list基于 API 调用结果生成动态下拉列表x-ms-dynamic-values配置动态值来源以填充参数选项常用operationId、value-path、value-titlex-ms-dynamic-tree为嵌套数据结构创建层级选择器x-ms-dynamic-schema允许基于用户选择在运行时改变 Schemax-ms-dynamic-properties根据上下文动态适配属性配置x-ms-enum-values为枚举提供带显示名的增强定义改善用户体验x-ms-test-value提供测试样本值严禁包含机密或敏感数据x-ms-trigger-value为触发器参数指定值含value-collection与value-path属性x-ms-url-encoding指定 URL 编码风格取值为single或double默认singlex-ms-parameter-location提供参数位置提示AutoRest 扩展Power Platform 忽略x-ms-localizeDefaultValue启用默认参数值的本地化x-ms-skip-url-encoding跳过路径参数的 URL 编码AutoRest 扩展Power Platform 忽略。1.3 Schema 级扩展Schema 定义中可用的扩展包括x-ms-notification-url将 Schema 属性标记为 Webhook 通知 URLx-ms-media-kind指定媒体类型仅支持image或audiox-ms-enum增强的枚举元数据AutoRest 扩展Power Platform 忽略。需要特别注意所有参数级扩展同样适用于 Schema 属性可在definitions内的属性定义中直接使用。1.4 根级与路径级扩展根级Root-Level扩展x-ms-capabilities定义连接器能力如file-picker与testConnectionx-ms-connector-metadata提供标准属性之外的连接器元数据x-ms-docs配置文档设置与参考x-ms-deployment-version记录版本信息用于部署管理x-ms-api-annotation为 API 添加注解以增强功能。路径级Path-Level扩展x-ms-notification-content为 Webhook 路径项定义通知内容 Schema。操作级能力Operation-Level Capabilitiesx-ms-capabilities操作级启用操作专属能力如chunkTransfer用于大文件分块传输。值得注意的是x-ms-parameter-location、x-ms-skip-url-encoding、x-ms-enum属于 AutoRest 生态的扩展Power Platform 会忽略它们——保留这些扩展通常是为了兼容其他消费方工具链不能依赖它们改变 Power Platform 运行时行为。1.5 安全定义SecurityDefinitions安全设计遵循以下规则必须为 API 定义合适的securityDefinitions以保证认证正确允许多个安全定义共存但最多两个例如oauth2 apiKey、basic apiKey例外若使用None认证则同一连接器中不得出现任何其他安全定义选型建议现代 API 使用oauth2简单令牌认证使用apiKeybasic仅考虑内部/遗留系统每个安全定义必须恰好是一种类型由oneOf校验强制保证。1.6 Power Platform 自定义 Formatdate-no-tz表示不含时区偏移信息的日期时间html告知客户端在编辑时渲染 HTML 编辑器、查看时渲染 HTML 查看器标准 format 还包括int32、int64、float、double、byte、binary、date、date-time、password、email、uri、uuid。1.7 参数最佳实践使用描述性description字段帮助用户理解参数用途实现x-ms-summary改善用户体验必须 Title Case正确标记必填参数required: true确保校验生效使用合适的format含 Power Platform 扩展保证数据正确处理善用动态扩展x-ms-dynamic-*提升用户体验与数据校验质量。二、apiProperties.json连接器元数据、认证与策略apiProperties.json定义连接器的身份与运行时行为核心组件有三类2.1 Connection Parameters连接参数选择恰当的参数类型string、securestring、oauthSettingOAuth 设置需配置正确的身份提供方identity provider需要下拉选项时使用allowedValues需要条件参数时实现参数依赖parameter dependencies。典型 OAuth 配置示例来自 instructions/power-platform-connector.instructions.md{ type: oauthSetting, oAuthSettings: { identityProvider: oauth2, clientId: your-client-id, scopes: [scope1, scope2], redirectMode: Global } }在 MCP/Copilot Studio 集成场景下instructions/power-platform-mcp-development.instructions.md 进一步建议用枚举下拉选择 OAuth 版本与安全级别、为参数提供清晰的描述与约束、支持多套认证参数组以适配不同部署环境并通过连接参数值实现动态配置。2.2 Policy Templates策略模板策略模板用于数据转换与路由routerequesttoendpoint将请求路由到不同后端 API 端点setqueryparameter为查询参数设置默认值updatenextlink分页场景下正确处理翻页pollingtrigger为需要轮询行为的触发器应用轮询策略。路由策略模板示例{ templateId: routerequesttoendpoint, title: Route to backend, parameters: { x-ms-apimTemplate-operationName: [GetData], x-ms-apimTemplateParameter.newPath: /api/v2/data } }2.3 Branding 与 Metadata必须指定iconBrandColor——该属性对所有连接器均为必填定义合适的capabilities声明连接器支持 actions 还是 triggers设置有意义的publisher与stackOwner标识所有权。连接器认证与品牌规范在仓库 MCP 套件 Skill 中被进一步落地连接器发布certification要求 icon 为 PNG 格式、230×230 或 500×500 尺寸并配套完整的 readme 文档见 skills/power-platform-mcp-connector-suite/SKILL.md。三、settings.jsonpaconn 环境与部署配置settings.json为paconn工具提供运行环境信息3.1 环境配置使用符合校验模式的 GUID 格式设置environment为目标环境设置正确的powerAppsUrl与flowUrl使 API 版本与具体需求匹配。3.2 文件引用保持默认文件名一致性apiProperties.json与apiDefinition.swagger.json本地开发环境使用相对路径确保图标文件存在并被正确引用。同时该文件还支持为生产PROD与测试TIP1环境分别配置 API 端点 URL并在settings.json中声明产品与服务元数据以通过认证检查参见 agents/power-platform-mcp-integration-expert.agent.md 中关于 Product and service metadata compliance (settings.json structure) 的说明。四、Schema 校验规则总览4.1 必填属性Required Properties文件必填项API Definitionswagger: 2.0、info含title与version、pathsAPI Propertiesproperties中的iconBrandColorSettings无全部可选均有默认值4.2 模式校验Pattern ValidationVendor 扩展非 Microsoft 扩展必须匹配^x-(?!ms-)模式路径项API 路径必须以/开头环境 GUID必须匹配 UUID 格式^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$URL端点配置必须是合法 URIHost 模式必须匹配^[^{}/ :\\](?::\d)?$不含空格、协议与路径。4.3 类型约束Type Constraints安全定义securityDefinitions对象中最多允许两个安全定义每个安全定义必须恰好是一种类型oneOf校验basic、apiKey、oauth2例外None认证不能与其他安全定义共存。参数类型仅限string、number、integer、boolean、array、file策略模板按类型要求对应参数Format 值包含 Power Platform 扩展的扩展集合可见性值必须是important、advanced或internal之一触发器类型必须是batch或single。4.4 附加校验规则$ref引用只能指向#/definitions/、#/parameters/或#/responses/路径参数必须标记required: trueInfo 对象description应与title不同Contact 对象email必须是合法邮箱格式url必须是合法 URILicense 对象name必填url若提供则必须是合法 URIExternal Docsurl必填且必须是合法 URITags数组内名称必须唯一Schemes必须是合法 HTTP schemehttp、https、ws、wssMIME 类型consumes与produces必须符合合法 MIME 类型格式。五、常见模式与完整示例5.1 带 Microsoft 扩展的基础操作{ get: { operationId: GetItems, summary: Get items, x-ms-summary: Get Items, x-ms-visibility: important, description: Retrieves a list of items from the API, parameters: [ { name: category, in: query, type: string, x-ms-summary: Category, x-ms-visibility: important, x-ms-dynamic-values: { operationId: GetCategories, value-path: id, value-title: name } } ], responses: { 200: { description: Success, x-ms-summary: Success, schema: { type: object, properties: { items: { type: array, x-ms-summary: Items, items: { $ref: #/definitions/Item } } } } } } } }5.2 触发器操作配置{ get: { operationId: WhenItemCreated, x-ms-summary: When an Item is Created, x-ms-trigger: batch, x-ms-trigger-hint: To see it work now, create an item, x-ms-trigger-metadata: { kind: query, mode: polling }, x-ms-pageable: { nextLinkName: odata.nextLink } } }5.3 动态 Schema 示例{ name: dynamicSchema, in: body, schema: { x-ms-dynamic-schema: { operationId: GetSchema, parameters: { table: { parameter: table } }, value-path: schema } } }5.4 文件选择器能力File Picker{ x-ms-capabilities: { file-picker: { open: { operationId: OneDriveFilePickerOpen, parameters: { dataset: { value-property: dataset } } }, browse: { operationId: OneDriveFilePickerBrowse, parameters: { dataset: { value-property: dataset } } }, value-title: DisplayName, value-collection: value, value-folder-property: IsFolder, value-media-property: MediaType } } }5.5 连接测试能力注意自定义连接器不支持{ x-ms-capabilities: { testConnection: { operationId: TestConnection, parameters: { param1: literal-value } } } }5.6 操作模拟上下文Operation Context{ x-ms-operation-context: { simulate: { operationId: SimulateOperation, parameters: { param1: { parameter: inputParam } } } } }5.7 多安全定义示例{ securityDefinitions: { oauth2: { type: oauth2, flow: accessCode, authorizationUrl: https://api.example.com/oauth/authorize, tokenUrl: https://api.example.com/oauth/token, scopes: { read: Read access, write: Write access } }, apiKey: { type: apiKey, name: X-API-Key, in: header } } }注意最多允许两个安全定义共存但None认证不能与其他方式组合。5.8 动态参数设置{ x-ms-dynamic-values: { operationId: GetItems, value-path: id, value-title: name } }六、与 MCP / Copilot Studio 集成的进阶模式虽然基础 Schema 面向通用 Power Platform 连接器仓库中的 MCP 资源将这套 Schema 规则扩展到了 Copilot Studio 场景可作为编写时的补充依据协议头MCP 集成要求x-ms-agentic-protocol: mcp-streamable-1.0并采用 JSON-RPC 2.0 通信见 skills/power-platform-mcp-connector-suite/SKILL.md 与 instructions/power-platform-mcp-development.instructions.mdSchema 约束Copilot Studio 不支持$ref引用类型需将anyOf/oneOf结构扁平化为单一类型 Schema工具输入/输出 Schema 必须自包含资源模型MCP Resources 必须以工具输出tool outputs形式暴露而非独立实体安全加固在 OAuth 2.0 基础上实现令牌受众audience校验以防令牌透传与混淆代理confused deputy攻击并使用state参数防护 CSRF详见 agents/power-platform-mcp-integration-expert.agent.md。这些内容印证了基础x-ms-*扩展与apiProperties.json认证配置在真实平台集成中的落地方式也让本指南的校验规则具备面向未来的扩展价值。七、最佳实践善用 IntelliSense这些 Schema 提供丰富的自动补全与校验能力开发过程中应充分依赖遵循命名约定为操作与参数使用描述性名称提升代码可读性实现错误处理定义恰当的响应 Schema 与错误码妥善处理失败场景充分测试部署前校验 Schema尽早发现问题注释扩展为 Microsoft 专属扩展添加注释便于团队理解与后续维护版本管理在 APIinfo中使用语义化版本号跟踪变更与兼容性安全优先始终实现恰当的认证机制保护 API 端点。八、故障排查Troubleshooting8.1 常见 Schema 违规缺少必填属性swagger: 2.0、info.title、info.version、paths模式格式无效GUID 必须匹配^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$URL 必须是带合法 scheme 的 URI路径必须以/开头Host 不得包含协议、路径或空格Vendor 扩展命名错误Microsoft 扩展用x-ms-*其他扩展用^x-(?!ms-)安全定义类型不匹配每个安全定义必须恰好是一种类型枚举值无效检查x-ms-visibility、x-ms-trigger、参数类型的允许值$ref指向非法位置只能指向#/definitions/、#/parameters/、#/responses/路径参数未标记必填所有路径参数必须有required: truefile类型用错上下文仅允许出现在formData参数中不能出现在 Schema 里。8.2 API Definition 专属问题动态 Schema 冲突x-ms-dynamic-schema不能与固定 Schema 属性混用触发器配置错误x-ms-trigger-metadata必须同时包含kind与mode分页配置x-ms-pageable必须包含nextLinkName属性文件选择器配置错误必须同时包含open操作与必需属性能力冲突某些能力可能与特定参数类型冲突测试值安全x-ms-test-value中严禁包含机密或 PII操作上下文配置x-ms-operation-context必须包含带operationId的simulate对象通知内容 Schema路径级x-ms-notification-content必须定义正确的 Schema 结构媒体类型限制x-ms-media-kind仅支持image或audio触发器值配置x-ms-trigger-value至少需要一个属性value-collection或value-path。8.3 校验工具与流程使用 JSON Schema 校验器检查 Schema 定义是否合规借助 VS Code 内置的 Schema 校验在开发过程中捕获错误部署前使用 paconn CLI 测试paconn validate --api-def apiDefinition.swagger.json对照 Power Platform 连接器要求进行校验确保兼容性使用 Power Platform Connector 门户在目标环境中完成验证与测试检查操作响应是否与预期 Schema 匹配防止运行时错误。在 MCP 集成场景中仓库还补充了更完整的验证链skills/power-platform-mcp-connector-suite/SKILL.md 的 Validation Checklist 要求在paconn validate通过后继续使用pac connector create/update创建/更新连接器、在 pac CLI 上传时自动校验script.csx并运行ConnectorPackageValidator.ps1完成包级验证该 Skill 提供的插件入口见 plugins/power-platform-mcp-connector-development/README.md。结语这三类 Schema 确保 Power Platform 连接器格式正确、能在平台生态中稳定工作apiDefinition.swagger.json决定 API 如何被描述与呈现apiProperties.json决定连接器如何认证与转换数据settings.json决定paconn如何部署。掌握x-ms-*扩展语义与校验规则即可编写出既符合 Swagger 2.0 标准、又充分利用 Power Platform 动态能力的高质量连接器定义。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Power Platform 自定义连接器 Schema 开发指南：基于 paconn 的 Swagger 2.0、API Properties 与 Settings 全解析

相关推荐

昇腾CANN/GE数据依赖形状自定义算子示例

CANN/ge SetAttrValue API文档

Ruff Ty 类型检查器 while 循环类型收窄（Narrowing）机制深度解析

更多资讯

awesome-math 数学视频资源推荐：从入门到进阶的三步选片路径

ai-agent-book 怎么用 Pandoc 与 ElegantBook 自行编译全书 PDF，或用 build_epub.sh 构建 EPUB

oh-my-claudecode 的执行模式怎么选？autopilot、team、ralph 与 ultrawork 的决策依据

OpenZeppelin Contracts 工程指南全解：测试、代码风格与 Solidity 编码约定

Actual 23.4.2 版本解析：按命名计划自动预算、侧边栏浮动优化与服务端密码重置脚本

Nx CLI 基准测试实战：用 1110 项目合成工作区度量任务流水线性能

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？