typespec-create-api-plugin

TypeSpec API プラグインを作成する

外部 REST API と統合する、Microsoft 365 Copilot 用の完全な TypeSpec API プラグインを作成します。

要件

次の内容を含む TypeSpec ファイルを生成します。

main.tsp - エージェント定義

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)

   // No @useAuth decorator needed
   

2. API キー

   @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 のベース URL と目的は何ですか?
2. どのような操作が必要ですか (CRUD 操作)?
3. API はどの認証方法を使用しますか?
4. いずれかの操作に確認を必須にしますか?
5. レスポンスに Adaptive Card が必要ですか?

次に、以下を生成します。

• エージェント定義を含む完全な main.tsp
• API 操作とモデルを含む完全な actions.tsp
• Adaptive Card が必要な場合はオプションの cards/card.json