typespec-api-operations

添加 TypeSpec API 操作

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

添加 GET 操作

简单 GET - 列出所有项目

/**
 * 列出所有项目。
 */
@route("/items")
@get op listItems(): Item[];

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

/**
 * 根据条件列出项目。
 * @param userId 可选的用户 ID，用于筛选项目
 */
@route("/items")
@get op listItems(@query userId?: integer): Item[];

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

/**
 * 根据 ID 获取特定项目。
 * @param id 要获取的项目 ID
 */
@route("/items/{id}")
@get op getItem(@path id: integer): Item;

带自适应卡片的 GET

/**
 * 列出项目并显示自适应卡片。
 */
@route("/items")
@card(#{
  dataPath: "$",
  title: "$.title",
  file: "item-card.json"
})
@get op listItems(): Item[];

创建自适应卡片 (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": "查看详情",
      "url": "https://example.com/items/${id}"
    }
  ]
}

添加 POST 操作

简单 POST - 创建项目

/**
 * 创建新项目。
 * @param item 要创建的项目
 */
@route("/items")
@post op createItem(@body item: CreateItemRequest): Item;

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

带确认的 POST

/**
 * 创建新项目并确认。
 */
@route("/items")
@post
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "创建项目",
    body: """
    确定要创建此项目吗？
      * **标题**：{{ function.parameters.item.title }}
      * **用户 ID**：{{ function.parameters.item.userId }}
    """
  }
})
op createItem(@body item: CreateItemRequest): Item;

添加 PATCH 操作

简单 PATCH - 更新项目

/**
 * 更新现有项目。
 * @param id 要更新的项目 ID
 * @param item 更新后的项目数据
 */
@route("/items/{id}")
@patch op updateItem(
  @path id: integer,
  @body item: UpdateItemRequest
): Item;

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

带确认的 PATCH

/**
 * 更新项目并确认。
 */
@route("/items/{id}")
@patch
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "更新项目",
    body: """
    正在更新项目 #{{ function.parameters.id }}：
      * **标题**：{{ function.parameters.item.title }}
      * **状态**：{{ function.parameters.item.status }}
    """
  }
})
op updateItem(
  @path id: integer,
  @body item: UpdateItemRequest
): Item;

添加 DELETE 操作

简单 DELETE

/**
 * 删除项目。
 * @param id 要删除的项目 ID
 */
@route("/items/{id}")
@delete op deleteItem(@path id: integer): void;

带确认的 DELETE

/**
 * 删除项目并确认。
 */
@route("/items/{id}")
@delete
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "删除项目",
    body: """
    ⚠️ 确定要删除项目 #{{ function.parameters.id }} 吗？
    此操作无法撤销。
    """
  }
})
op deleteItem(@path id: integer): void;

完整 CRUD 示例

定义服务和模型

@service
@server("https://api.example.com")
@actions(#{
  nameForHuman: "Items API",
  descriptionForHuman: "管理项目",
  descriptionForModel: "读取、创建、更新和删除项目"
})
namespace ItemsAPI {
  
  // 模型
  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";
  }

  // 操作
  @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: "创建项目",
      body: "正在创建：**{{ function.parameters.item.title }}**"
    }
  })
  op createItem(@body item: CreateItemRequest): Item;

  @route("/items/{id}")
  @patch
  @capabilities(#{
    confirmation: #{
      type: "AdaptiveCard",
      title: "更新项目",
      body: "正在更新项目 #{{ function.parameters.id }}"
    }
  })
  op updateItem(@path id: integer, @body item: UpdateItemRequest): Item;

  @route("/items/{id}")
  @delete
  @capabilities(#{
    confirmation: #{
      type: "AdaptiveCard",
      title: "删除项目",
      body: "⚠️ 删除项目 #{{ 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;

测试提示

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

GET 操作：

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

POST 操作：

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

PATCH 操作：

• "将项目 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)，如果应为可写则移除该装饰器