typespec-create-api-plugin

建立 TypeSpec API 外掛模組

為 Microsoft 365 Copilot 建立完整的 TypeSpec API 外掛模組，以與外部 REST API 進行整合。

需求說明

生成包含以下內容的 TypeSpec 檔案：

main.tsp - Agent 定義

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent({
  name: "[Agent Name]",
  description: "[Description]"
})
@instructions("""
  [Instructions for using the API operations]
""")
namespace [AgentName] {
  // Reference operations from actions.tsp
  op operation1 is [APINamespace].operationName;
}

actions.tsp - API 操作

import "@typespec/http";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Actions;

@service
@actions(#{
    nameForHuman: "[API Display Name]",
    descriptionForModel: "[Model description]",
    descriptionForHuman: "[User description]"
})
@server("[API_BASE_URL]", "[API Name]")
@useAuth([AuthType]) // Optional
namespace [APINamespace] {
  
  @route("[/path]")
  @get
  @action
  op operationName(
    @path param1: string,
    @query param2?: string
  ): ResponseModel;

  model ResponseModel {
    // Response structure
  }
}

身分驗證選項

根據 API 的需求進行選擇：

1. 無需驗證（公開 API）

   // 不需要 @useAuth 裝飾器
   

2. API Key

   @useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">)
   

3. OAuth2

   @useAuth(OAuth2Auth<[{
     type: OAuth2FlowType.authorizationCode;
     authorizationUrl: "https://oauth.example.com/authorize";
     tokenUrl: "https://oauth.example.com/token";
     refreshUrl: "https://oauth.example.com/token";
     scopes: ["read", "write"];
   }]>)
   

4. 已註冊的驗證參考

   @useAuth(Auth)
   
   @authReferenceId("registration-id-here")
   model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">
   

函式功能特性

操作確認對話方塊

@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Confirm Action",
    body: """
    Are you sure you want to perform this action?
      * **Parameter**: {{ function.parameters.paramName }}
    """
  }
})

Adaptive Card 回應

@card(#{
  dataPath: "$.items",
  title: "$.title",
  url: "$.link",
  file: "cards/card.json"
})

推理與回應指令

@reasoning("""
  Consider user's context when calling this operation.
  Prioritize recent items over older ones.
""")
@responding("""
  Present results in a clear table format with columns: ID, Title, Status.
  Include a summary count at the end.
""")

最佳做法

1. 操作名稱：使用明確、以動作為導向的名稱（如 listProjects、createTicket）
2. 模型：為請求與回應定義類似 TypeScript 的模型
3. HTTP 方法：使用適當的動詞（@get、@post、@patch、@delete）
4. 路徑：使用 @route 遵循 RESTful 路徑規範
5. 參數：適當地使用 @path、@query、@header、@body
6. 說明文字：提供清晰的描述以利模型理解
7. 確認機制：針對破壞性操作（刪除、更新關鍵資料）新增操作確認
8. 卡片：針對包含多個資料項目的豐富視覺化回應使用卡片

工作流程

詢問使用者：

1. API 的 Base URL 與主要用途為何？
2. 需要哪些操作（CRUD 操作）？
3. API 使用哪種身分驗證方式？
4. 是否有任何操作需要使用者確認？
5. 回應是否需要使用 Adaptive Cards？

接著生成：

• 包含 Agent 定義的完整 main.tsp
• 包含 API 操作與模型的完整 actions.tsp
• （選擇性）若需要 Adaptive Cards，生成 cards/card.json