custom-connectors

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Custom Connectors

Skill：自定义连接器

When to Use

适用场景

Trigger when building, configuring, or debugging custom connectors — reusable API wrappers that expose REST APIs as Power Platform connectors for use in Power Automate, Power Apps, and Copilot Studio.

当构建、配置或调试自定义连接器时触发——自定义连接器是可复用的API包装器，将REST API作为Power Platform连接器暴露，供Power Automate、Power Apps和Copilot Studio使用。

When to Use Custom Connectors vs Alternatives

自定义连接器与替代方案的适用场景对比

Scenario	Use	Why
Standard connector exists	Standard connector	Zero maintenance, Microsoft-supported
REST API used in one flow only	HTTP action in Power Automate	Simpler, no connector overhead
REST API used across multiple flows/apps	Custom connector	Reusable, typed, discoverable
REST API with complex auth (OAuth 2.0)	Custom connector	Auth handled once, shared across all uses
High-volume API calls needing throttling	Custom connector + Azure APIM	APIM handles rate limiting, caching, monitoring
On-premises API (no public endpoint)	Custom connector + On-premises Data Gateway	Gateway bridges private network

场景	使用方案	原因
已有标准连接器	标准连接器	无需维护，由微软提供支持
REST API仅在单个流中使用	Power Automate中的HTTP操作	更简单，无连接器开销
REST API在多个流/应用中使用	自定义连接器	可复用、类型化、易发现
REST API包含复杂身份验证（OAuth 2.0）	自定义连接器	身份验证只需配置一次，可在所有使用场景中共享
高调用量API需要限流	自定义连接器 + Azure APIM	APIM处理速率限制、缓存、监控
本地API（无公共端点）	自定义连接器 + 本地数据网关	网关桥接私有网络

Project Structure

项目结构

custom-connectors/
  contoso-erp/
    apiDefinition.swagger.json    # OpenAPI 2.0 definition
    apiProperties.json            # Connector metadata + policies
    icon.png                      # 160x160 connector icon
    settings.json                 # Test settings
  README.md

custom-connectors/
  contoso-erp/
    apiDefinition.swagger.json    # OpenAPI 2.0 定义
    apiProperties.json            # 连接器元数据 + 策略
    icon.png                      # 160x160 连接器图标
    settings.json                 # 测试设置
  README.md

⚠️ REQUIRED: Load Sub-Files Before Implementation

⚠️ 必需：在实施前加载子文件

SKILL.md is a summary only — it is NOT sufficient for implementation.

The detailed content (complete payloads, XML templates, working examples, edge-case handling) lives in sub-files in the same directory as this SKILL.md. Before writing any code, you MUST use

read_file

on the sub-files relevant to your task:

OpenAPI Definition — Swagger structure, action definitions, schema definitions, x-ms extensions, dynamic values/schema
Authentication — API Key, OAuth 2.0 (Authorization Code), Azure AD / Entra ID, apiProperties.json configuration
Triggers — Polling triggers (batch), webhook triggers, deregistration endpoint, trigger hints
Policies & APIM — Connector policies (set header, route request), Azure APIM integration, DLP classification, CLI workflow, solution-aware connectors

SKILL.md仅为摘要——不足以支撑实施工作。

详细内容（完整负载、XML模板、可用示例、边缘情况处理）存放在此SKILL.md所在目录的子文件中。在编写任何代码前，必须针对你的任务使用

read_file

加载相关子文件：

OpenAPI 定义 — Swagger结构、操作定义、模式定义、x-ms扩展、动态值/模式
身份验证 — API Key、OAuth 2.0（授权码）、Azure AD / Entra ID、apiProperties.json配置
触发器 — 轮询触发器（批量）、Webhook触发器、注销端点、触发器提示
策略与APIM — 连接器策略（设置标头、路由请求）、Azure APIM集成、DLP分类、CLI工作流、解决方案感知连接器

Best Practices

最佳实践

Always use
```
x-ms-summary
```
on every parameter and property (maker-friendly display names)
Always set
```
x-ms-visibility: "internal"
```
for technical parameters users shouldn't see
Always define response schemas (Power Automate needs them for dynamic content)
Use
```
x-ms-dynamic-values
```
for dropdown parameters (don't force users to type GUIDs)
Test with both Power Automate and Canvas App (behaviour can differ)
Version your connector:
```
host
```
+
```
basePath
```
should include version (e.g.,
```
/v2/
```
)
Icon must be exactly 160x160px PNG with brand colour background

始终为每个参数和属性添加
```
x-ms-summary
```
（便于制作者理解的显示名称）
始终为用户无需查看的技术参数设置
```
x-ms-visibility: "internal"
```
始终定义响应模式（Power Automate需要它们来生成动态内容）
为下拉参数使用
```
x-ms-dynamic-values
```
（不要强制用户输入GUID）
同时在Power Automate和Canvas App中测试（行为可能不同）
为连接器版本化：
```
host
```
+
```
basePath
```
应包含版本信息（例如：
```
/v2/
```
）
图标必须为160x160px的PNG格式，带有品牌颜色背景

Anti-Patterns

反模式

Missing
```
x-ms-summary
```
on parameters (users see raw field names)
Missing response schemas (dynamic content unavailable in flow designer)
Using
```
x-ms-visibility: "internal"
```
on required user inputs (hides needed fields)
Hardcoded hostnames in OpenAPI definition (use connection parameter for environment switching)
Not classifying connector in DLP policy (blocks use with Dataverse/SharePoint)
Polling triggers without proper 202 handling (triggers fire with empty data)
Not including connector in solution (breaks ALM)
Using Basic auth for production connectors (use OAuth 2.0 or API key)
Missing error response definitions (poor error handling in flows)

参数缺少
```
x-ms-summary
```
（用户看到原始字段名称）
缺少响应模式（流设计器中无法使用动态内容）
对必填用户输入设置
```
x-ms-visibility: "internal"
```
（隐藏所需字段）
OpenAPI定义中硬编码主机名（使用连接参数实现环境切换）
未在DLP策略中对连接器进行分类（阻止与Dataverse/SharePoint一起使用）
轮询触发器未正确处理202响应（触发器触发但返回空数据）
未将连接器纳入解决方案（破坏ALM）
生产连接器使用Basic身份验证（应使用OAuth 2.0或API Key）
缺少错误响应定义（流中的错误处理效果差）