TypeSpec API 操作指南：为 Microsoft 365 Copilot 插件添加 RESTful 操作（GET/POST/PATCH）

typespec-api-operations by github/awesome-copilot

7,400 周安装量

27,200 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/github/awesome-copilot --skill typespec-api-operations

AI/机器学习开发

🇨🇳中文介绍

添加 TypeSpec API 操作

为现有的 Microsoft 365 Copilot TypeSpec API 插件添加 RESTful 操作。

添加 GET 操作

简单 GET - 列出所有项目

/**
 * List all items.
 */
@route("/items")
@get op listItems(): Item[];

带查询参数的 GET - 筛选结果

/**
 * List items filtered by criteria.
 * @param userId Optional user ID to filter items
 */
@route("/items")
@get op listItems(@query userId?: integer): Item[];

带路径参数的 GET - 获取单个项目

/**
 * Get a specific item by ID.
 * @param id The ID of the item to retrieve
 */
@route("/items/{id}")
@get op getItem(@path id: integer): Item;

带自适应卡片的 GET

/**
 * List items with adaptive card visualization.
 */
@route("/items")
@card(#{
  dataPath: "$",
  title: "$.title",
  file: "item-card.json"
})
@get op listItems(): Item[];

创建自适应卡片 (appPackage/item-card.json):

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

简单 POST - 创建项目

/**
 * Create a new item.
 * @param item The item to create
 */
@route("/items")
@post op createItem(@body item: CreateItemRequest): Item;

model CreateItemRequest {
  title: string;
  description?: string;
  userId: integer;
}

/**
 * Create a new item with confirmation.
 */
@route("/items")
@post
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Create Item",
    body: """
    Are you sure you want to create this item?
      * **Title**: {{ function.parameters.item.title }}
      * **User ID**: {{ function.parameters.item.userId }}
    """
  }
})
op createItem(@body item: CreateItemRequest): Item;

简单 PATCH - 更新项目

/**
 * Update an existing item.
 * @param id The ID of the item to update
 * @param item The updated item data
 */
@route("/items/{id}")
@patch op updateItem(
  @path id: integer,
  @body item: UpdateItemRequest
): Item;

model UpdateItemRequest {
  title?: string;
  description?: string;
  status?: "active" | "completed" | "archived";
}

/**
 * Update an item with confirmation.
 */
@route("/items/{id}")
@patch
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Update Item",
    body: """
    Updating item #{{ function.parameters.id }}:
      * **Title**: {{ function.parameters.item.title }}
      * **Status**: {{ function.parameters.item.status }}
    """
  }
})
op updateItem(
  @path id: integer,
  @body item: UpdateItemRequest
): Item;

添加 DELETE 操作

/**
 * Delete an item.
 * @param id The ID of the item to delete
 */
@route("/items/{id}")
@delete op deleteItem(@path id: integer): void;

/**
 * Delete an item with confirmation.
 */
@route("/items/{id}")
@delete
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Delete Item",
    body: """
    ⚠️ Are you sure you want to delete item #{{ function.parameters.id }}?
    This action cannot be undone.
    """
  }
})
op deleteItem(@path id: integer): void;

完整的 CRUD 示例

定义服务和模型

@service
@server("https://api.example.com")
@actions(#{
  nameForHuman: "Items API",
  descriptionForHuman: "Manage items",
  descriptionForModel: "Read, create, update, and delete items"
})
namespace ItemsAPI {
  
  // Models
  model Item {
    @visibility(Lifecycle.Read)
    id: integer;
    
    userId: integer;
    title: string;
    description?: string;
    status: "active" | "completed" | "archived";
    
    @format("date-time")
    createdAt: utcDateTime;
    
    @format("date-time")
    updatedAt?: utcDateTime;
  }

  model CreateItemRequest {
    userId: integer;
    title: string;
    description?: string;
  }

  model UpdateItemRequest {
    title?: string;
    description?: string;
    status?: "active" | "completed" | "archived";
  }

  // Operations
  @route("/items")
  @card(#{ dataPath: "$", title: "$.title", file: "item-card.json" })
  @get op listItems(@query userId?: integer): Item[];

  @route("/items/{id}")
  @card(#{ dataPath: "$", title: "$.title", file: "item-card.json" })
  @get op getItem(@path id: integer): Item;

  @route("/items")
  @post
  @capabilities(#{
    confirmation: #{
      type: "AdaptiveCard",
      title: "Create Item",
      body: "Creating: **{{ function.parameters.item.title }}**"
    }
  })
  op createItem(@body item: CreateItemRequest): Item;

  @route("/items/{id}")
  @patch
  @capabilities(#{
    confirmation: #{
      type: "AdaptiveCard",
      title: "Update Item",
      body: "Updating item #{{ function.parameters.id }}"
    }
  })
  op updateItem(@path id: integer, @body item: UpdateItemRequest): Item;

  @route("/items/{id}")
  @delete
  @capabilities(#{
    confirmation: #{
      type: "AdaptiveCard",
      title: "Delete Item",
      body: "⚠️ Delete item #{{ function.parameters.id }}?"
    }
  })
  op deleteItem(@path id: integer): void;
}

@route("/items")
@get op listItems(
  @query userId?: integer,
  @query status?: "active" | "completed" | "archived",
  @query limit?: integer,
  @query offset?: integer
): ItemList;

model ItemList {
  items: Item[];
  total: integer;
  hasMore: boolean;
}

@route("/items")
@get op listItems(
  @header("X-API-Version") apiVersion?: string,
  @query userId?: integer
): Item[];

自定义响应模型

@route("/items/{id}")
@delete op deleteItem(@path id: integer): DeleteResponse;

model DeleteResponse {
  success: boolean;
  message: string;
  deletedId: integer;
}

model ErrorResponse {
  error: {
    code: string;
    message: string;
    details?: string[];
  };
}

@route("/items/{id}")
@get op getItem(@path id: integer): Item | ErrorResponse;

添加操作后，使用以下提示进行测试：

"列出所有项目并以表格形式显示"
"显示用户 ID 为 1 的项目"
"获取项目 42 的详细信息"

"为用户 1 创建一个标题为 '我的任务' 的新项目"
"添加一个项目：标题 '新功能'，描述 '添加登录'"

"将项目 10 的标题更新为 '更新后的标题'"
"将项目 5 的状态更改为已完成"

DELETE 操作：

"删除项目 99"
"移除 ID 为 15 的项目"

使用描述性的参数名称：用 userId 而不是 uid
跨操作保持一致性
对筛选器使用可选参数 (?)

为所有操作添加 JSDoc 注释
描述每个参数的作用
记录预期的响应

对只读字段（如 id）使用 @visibility(Lifecycle.Read)
对日期字段使用 @format("date-time")
对枚举使用联合类型："active" | "completed"
使用 ? 明确表示可选字段

始终为破坏性操作（DELETE、PATCH）添加确认
在确认主体中显示关键详细信息
对不可逆操作使用警告表情符号 (⚠️)

保持卡片简单且重点突出
使用 ${if(..., ..., 'N/A')} 进行条件渲染
为常见的后续步骤包含操作按钮
使用实际的 API 响应测试数据绑定

使用 RESTful 约定：
- GET /items - 列表
- GET /items/{id} - 获取单个
- POST /items - 创建
- PATCH /items/{id} - 更新
- DELETE /items/{id} - 删除
将相关操作分组到同一个命名空间中
对分层资源使用嵌套路由

问题：参数未在 Copilot 中显示

解决方案：检查参数是否正确使用了 @query、@path 或 @body 装饰器

问题：自适应卡片未渲染

解决方案：验证 @card 装饰器中的文件路径并检查 JSON 语法

问题：确认未出现

解决方案：确保 @capabilities 装饰器格式正确，并包含确认对象

问题：模型属性未在响应中出现

解决方案：检查属性是否需要 @visibility(Lifecycle.Read)，或者如果它应该是可写的，则将其移除

🇺🇸English

Add TypeSpec API Operations

Add RESTful operations to an existing TypeSpec API plugin for Microsoft 365 Copilot.

Adding GET Operations

Simple GET - List All Items

/**
 * List all items.
 */
@route("/items")
@get op listItems(): Item[];

GET with Query Parameter - Filter Results

/**
 * List items filtered by criteria.
 * @param userId Optional user ID to filter items
 */
@route("/items")
@get op listItems(@query userId?: integer): Item[];

GET with Path Parameter - Get Single Item

/**
 * Get a specific item by ID.
 * @param id The ID of the item to retrieve
 */
@route("/items/{id}")
@get op getItem(@path id: integer): Item;

GET with Adaptive Card

/**
 * List items with adaptive card visualization.
 */
@route("/items")
@card(#{
  dataPath: "$",
  title: "$.title",
  file: "item-card.json"
})
@get op listItems(): Item[];

Create the Adaptive Card (appPackage/item-card.json):

{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.5",
  "body": [
    {
      "type": "Container",
      "$data": "${$root}",
      "items": [
        {
          "type": "TextBlock",
          "text": "**${if(title, title, 'N/A')}**",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "text": "${if(description, description, 'N/A')}",
          "wrap": true
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.OpenUrl",
      "title": "View Details",
      "url": "https://example.com/items/${id}"
    }
  ]
}

Adding POST Operations

Simple POST - Create Item

/**
 * Create a new item.
 * @param item The item to create
 */
@route("/items")
@post op createItem(@body item: CreateItemRequest): Item;

model CreateItemRequest {
  title: string;
  description?: string;
  userId: integer;
}

POST with Confirmation

/**
 * Create a new item with confirmation.
 */
@route("/items")
@post
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Create Item",
    body: """
    Are you sure you want to create this item?
      * **Title**: {{ function.parameters.item.title }}
      * **User ID**: {{ function.parameters.item.userId }}
    """
  }
})
op createItem(@body item: CreateItemRequest): Item;

Adding PATCH Operations

Simple PATCH - Update Item

/**
 * Update an existing item.
 * @param id The ID of the item to update
 * @param item The updated item data
 */
@route("/items/{id}")
@patch op updateItem(
  @path id: integer,
  @body item: UpdateItemRequest
): Item;

model UpdateItemRequest {
  title?: string;
  description?: string;
  status?: "active" | "completed" | "archived";
}

PATCH with Confirmation

/**
 * Update an item with confirmation.
 */
@route("/items/{id}")
@patch
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Update Item",
    body: """
    Updating item #{{ function.parameters.id }}:
      * **Title**: {{ function.parameters.item.title }}
      * **Status**: {{ function.parameters.item.status }}
    """
  }
})
op updateItem(
  @path id: integer,
  @body item: UpdateItemRequest
): Item;

Adding DELETE Operations

Simple DELETE

/**
 * Delete an item.
 * @param id The ID of the item to delete
 */
@route("/items/{id}")
@delete op deleteItem(@path id: integer): void;

DELETE with Confirmation

/**
 * Delete an item with confirmation.
 */
@route("/items/{id}")
@delete
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Delete Item",
    body: """
    ⚠️ Are you sure you want to delete item #{{ function.parameters.id }}?
    This action cannot be undone.
    """
  }
})
op deleteItem(@path id: integer): void;

Complete CRUD Example

Define the Service and Models

@service
@server("https://api.example.com")
@actions(#{
  nameForHuman: "Items API",
  descriptionForHuman: "Manage items",
  descriptionForModel: "Read, create, update, and delete items"
})
namespace ItemsAPI {
  
  // Models
  model Item {
    @visibility(Lifecycle.Read)
    id: integer;
    
    userId: integer;
    title: string;
    description?: string;
    status: "active" | "completed" | "archived";
    
    @format("date-time")
    createdAt: utcDateTime;
    
    @format("date-time")
    updatedAt?: utcDateTime;
  }

  model CreateItemRequest {
    userId: integer;
    title: string;
    description?: string;
  }

  model UpdateItemRequest {
    title?: string;
    description?: string;
    status?: "active" | "completed" | "archived";
  }

  // Operations
  @route("/items")
  @card(#{ dataPath: "$", title: "$.title", file: "item-card.json" })
  @get op listItems(@query userId?: integer): Item[];

  @route("/items/{id}")
  @card(#{ dataPath: "$", title: "$.title", file: "item-card.json" })
  @get op getItem(@path id: integer): Item;

  @route("/items")
  @post
  @capabilities(#{
    confirmation: #{
      type: "AdaptiveCard",
      title: "Create Item",
      body: "Creating: **{{ function.parameters.item.title }}**"
    }
  })
  op createItem(@body item: CreateItemRequest): Item;

  @route("/items/{id}")
  @patch
  @capabilities(#{
    confirmation: #{
      type: "AdaptiveCard",
      title: "Update Item",
      body: "Updating item #{{ function.parameters.id }}"
    }
  })
  op updateItem(@path id: integer, @body item: UpdateItemRequest): Item;

  @route("/items/{id}")
  @delete
  @capabilities(#{
    confirmation: #{
      type: "AdaptiveCard",
      title: "Delete Item",
      body: "⚠️ Delete item #{{ function.parameters.id }}?"
    }
  })
  op deleteItem(@path id: integer): void;
}

Advanced Features

Multiple Query Parameters

@route("/items")
@get op listItems(
  @query userId?: integer,
  @query status?: "active" | "completed" | "archived",
  @query limit?: integer,
  @query offset?: integer
): ItemList;

model ItemList {
  items: Item[];
  total: integer;
  hasMore: boolean;
}

Header Parameters

@route("/items")
@get op listItems(
  @header("X-API-Version") apiVersion?: string,
  @query userId?: integer
): Item[];

Custom Response Models

@route("/items/{id}")
@delete op deleteItem(@path id: integer): DeleteResponse;

model DeleteResponse {
  success: boolean;
  message: string;
  deletedId: integer;
}

Error Responses

model ErrorResponse {
  error: {
    code: string;
    message: string;
    details?: string[];
  };
}

@route("/items/{id}")
@get op getItem(@path id: integer): Item | ErrorResponse;

Testing Prompts

After adding operations, test with these prompts:

GET Operations:

"List all items and show them in a table"
"Show me items for user ID 1"
"Get the details of item 42"

POST Operations:

"Create a new item with title 'My Task' for user 1"
"Add an item: title 'New Feature', description 'Add login'"

PATCH Operations:

"Update item 10 with title 'Updated Title'"
"Change the status of item 5 to completed"

DELETE Operations:

"Delete item 99"
"Remove the item with ID 15"

Best Practices

Parameter Naming

Use descriptive parameter names: userId not uid
Be consistent across operations
Use optional parameters (?) for filters

Documentation

Add JSDoc comments to all operations
Describe what each parameter does
Document expected responses

Models

Use @visibility(Lifecycle.Read) for read-only fields like id
Use @format("date-time") for date fields
Use union types for enums: "active" | "completed"
Make optional fields explicit with ?

Confirmations

Always add confirmations to destructive operations (DELETE, PATCH)
Show key details in confirmation body
Use warning emoji (⚠️) for irreversible actions

Adaptive Cards

Keep cards simple and focused
Use conditional rendering with ${if(..., ..., 'N/A')}
Include action buttons for common next steps
Test data binding with actual API responses

Routing

Use RESTful conventions:
- GET /items - List
- GET /items/{id} - Get one
- POST /items - Create
- PATCH /items/{id} - Update
- DELETE /items/{id} - Delete
Group related operations in the same namespace
Use nested routes for hierarchical resources

Common Issues

Issue: Parameter not showing in Copilot

Solution : Check parameter is properly decorated with @query, @path, or @body

Issue: Adaptive card not rendering

Solution : Verify file path in @card decorator and check JSON syntax

Issue: Confirmation not appearing

Solution : Ensure @capabilities decorator is properly formatted with confirmation object

Issue: Model property not appearing in response

Solution : Check if property needs @visibility(Lifecycle.Read) or remove it if it should be writable

Weekly Installs

7.3K

Repository

github/awesome-copilot

GitHub Stars

26.9K

First Seen

Feb 25, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex7.2K

gemini-cli7.2K

opencode7.2K

cursor7.2K

github-copilot7.2K

kimi-cli7.2K

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装