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;

Adaptive Card付き GET

/**
 * Adaptive Card ビジュアライゼーション付きでアイテムをリストします。
 */
@route("/items")
@card(#{
  dataPath: "$",
  title: "$.title",
  file: "item-card.json"
})
@get op listItems(): Item[];

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}"
    }
  ]
}

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: "Create Item",
    body: """
    このアイテムを作成してもよろしいですか？
      * **Title**: {{ function.parameters.item.title }}
      * **User 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: "Update Item",
    body: """
    アイテム #{{ function.parameters.id }} を更新しています：
      * **Title**: {{ function.parameters.item.title }}
      * **Status**: {{ 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: "Delete Item",
    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: "Create Item",
      body: "作成中: **{{ function.parameters.item.title }}**"
    }
  })
  op createItem(@body item: CreateItemRequest): Item;

  @route("/items/{id}")
  @patch
  @capabilities(#{
    confirmation: #{
      type: "AdaptiveCard",
      title: "Update Item",
      body: "アイテム #{{ function.parameters.id }} を更新しています"
    }
  })
  op updateItem(@path id: integer, @body item: UpdateItemRequest): Item;

  @route("/items/{id}")
  @delete
  @capabilities(#{
    confirmation: #{
      type: "AdaptiveCard",
      title: "Delete Item",
      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 操作：

• 「タイトル『My Task』 で ユーザー 1 用の新しいアイテムを作成してください」
• 「アイテムを追加してください：タイトル『New Feature』 、説明『ログイン機能を追加』」

PATCH 操作：

• 「アイテム 10 をタイトル『Updated Title』 で更新してください」
• 「アイテム 5 のステータスを完了に変更してください」

DELETE 操作：

• 「アイテム 99 を削除してください」
• 「ID 15 のアイテムを削除してください」

ベストプラクティス

パラメータ命名

• 説明的なパラメータ名を使用してください：uid ではなく userId
• 操作全体で一貫性を保ってください
• フィルタ用にはオプションパラメータ（?）を使用してください

ドキュメント

• すべての操作に JSDoc コメントを追加してください
• 各パラメータの機能を説明してください
• 予期される応答を文書化してください

モデル

• id のような読み取り専用フィールドに @visibility(Lifecycle.Read) を使用してください
• 日付フィールドに @format("date-time") を使用してください
• 列挙型にはユニオン型を使用してください："active" | "completed"
• オプションフィールドを明示的に ? で指定してください

確認

• 破壊的な操作（DELETE、PATCH）には常に確認を追加してください
• 確認本文に主要な詳細を表示してください
• 元に戻せないアクションには警告絵文字（⚠️）を使用してください

Adaptive Card

• カードはシンプルで焦点を絞ってください
• ${if(..., ..., 'N/A')} で条件付きレンダリングを使用してください
• 一般的な次のステップ用にアクションボタンを含めてください
• 実際の API レスポンスでデータバインディングをテストしてください

ルーティング

• RESTful 規約を使用してください：
  • GET /items - リスト
  • GET /items/{id} - 1つ取得
  • POST /items - 作成
  • PATCH /items/{id} - 更新
  • DELETE /items/{id} - 削除
• 関連する操作を同じ名前空間にグループ化してください
• 階層的なリソース用にはネストされたルートを使用してください

よくある問題

問題: Copilot にパラメータが表示されない

解決策: パラメータが @query、@path、または @body で適切に装飾されているか確認してください

問題: Adaptive Card がレンダリングされない

解決策: @card デコレータのファイルパスを確認し、JSON 構文をチェックしてください

問題: 確認が表示されない

解決策: @capabilities デコレータが確認オブジェクトで適切に形成されていることを確認してください

問題: モデルプロパティが応答に表示されない

解決策: プロパティが @visibility(Lifecycle.Read) を必要とするか確認するか、書き込み可能である場合は削除してください