API ベースのメッセージ拡張機能を作成する

注:

API ベースのメッセージ拡張機能では、検索コマンドのみがサポートされます。

API ベースのメッセージ拡張機能は、外部 API を Teams に直接統合し、アプリの使いやすさを高め、シームレスなユーザーエクスペリエンスを提供する、Microsoft Teamsアプリ機能です。 API ベースのメッセージ拡張機能は検索コマンドをサポートしており、Teams 内の外部サービスからデータをフェッチして表示するために使用でき、アプリケーション間の切り替えの必要性を減らすことでワークフローを合理化できます。

注:

エージェントは、より柔軟でインテリジェントで将来に備えたエクスペリエンスを提供します。これにより、より豊かな推論、よりシンプルな開発、進化する Teams および Microsoft 365 プラットフォームとのより適切な連携が可能になります。エージェントを探索してビルドすることをお勧めします。

詳細については、「Teams での宣言型エージェントのビルドとビルドエージェント」を参照してください。

既存のボットベースのメッセージ拡張機能がある場合は、エージェントとしても拡張できます。

作業を開始する前に、次の要件を満たしていることを確認してください。

1. OpenAPI Description (OAD)

OpenAPI Description (OAD) ドキュメントの次のガイドラインに従っていることを確認します。

OpenAPI バージョン 2.0 および 3.0.x がサポートされています。
JSON と YAML は、サポートされている形式です。
要求本文が存在する場合は、application/Json である必要があります。
servers.url プロパティの HTTPS プロトコルサーバー URL を定義します。
POST メソッドと GET HTTP メソッドのみがサポートされています。
OpenAPI Description ドキュメントには、 operationIdが必要です。
既定値のない必須パラメーターは 1 つだけ許可されます。
既定値の必須パラメーターは省略可能と見なされます。
ユーザーは、ヘッダーまたは Cookie のパラメーターを入力しないでください。
操作には、既定値のない必須のヘッダーパラメーターまたは Cookie パラメーターを含めてはいけません。
OpenAPI 説明ドキュメントにリモート参照がないことを確認します。
要求の配列の構築はサポートされていません。ただし、JSON 要求本文内の入れ子になったオブジェクトはサポートされています。
Teams では、 oneOf、 anyOf、 allOf、 not (swagger.io) コンストラクトはサポートされていません。

次のコードは、OpenAPI Description ドキュメントの例です。

openapi: 3.0.1
info:
title: OpenTools Plugin
description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
version: 'v1'
servers:
- url: https://gptplugin.opentools.ai
paths:
/tools:
 get:
   operationId: searchTools
   summary: Search for AI Tools
   parameters:
     - in: query
       name: search
       required: true
       schema:
         type: string
       description: Used to search for AI tools by their category based on the keywords. For example, ?search="tool to create music" will give tools that can create music.
   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/searchToolsResponse'
     "400":
       description: Search Error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/searchToolsError'
components:
schemas:
 searchToolsResponse:
   required:
     - search
   type: object
   properties:
     tools:
       type: array
       items:
         type: object
         properties:
           name:
             type: string
             description: The name of the tool.
           opentools_url:
             type: string
             description: The URL to access the tool.
           main_summary:
             type: string
             description: A summary of what the tool is.
           pricing_summary:
             type: string
             description: A summary of the pricing of the tool.
           categories:
             type: array
             items:
               type: string
             description: The categories assigned to the tool.
           platforms:
             type: array
             items:
               type: string
             description: The platforms that this tool is available on.
       description: The list of AI tools.
 searchToolsError:
   type: object
   properties:
     message:
       type: string
       description: Message of the error.

詳細については、「OpenAPI 構造体」を参照してください。

2. アプリマニフェスト

アプリマニフェストの次のガイドラインに従っていることを確認します。

アプリマニフェストのバージョンを 1.17 に設定します。
[ composeExtensions.composeExtensionType ] を [ apiBased] に設定します。
フォルダー内の OpenAPI Description ファイルへの相対パスとして、 composeExtensions.apiSpecificationFile を定義します。これにより、アプリマニフェストが API 仕様にリンクされます。
応答レンダリングテンプレートへの相対パスとして apiResponseRenderingTemplateFile を定義します。これは、API 応答のレンダリングに使用されるテンプレートの場所を指定します。
各コマンドには、応答レンダリングテンプレートへのリンクが必要です。これにより、各コマンドが対応する応答形式に接続されます。
アプリマニフェストの Commands.id プロパティは、OpenAPI Description の operationId と一致している必要があります。
必須パラメーターに既定値がない場合、アプリマニフェストのコマンド parameters.name は、OpenAPI Description ドキュメントの parameters.name と一致する必要があります。
必要なパラメーターがない場合、アプリマニフェストで parameters.name コマンドは、OpenAPI Description の省略可能な parameters.name と一致する必要があります。
各コマンドのパラメーターが、OpenAPI 仕様の操作に対して定義されているパラメーターの名前と正確に一致していることを確認します。
応答レンダリングテンプレートは、API からの応答を変換するために使用されるコマンドごとに定義する必要があります。

完全な説明は 128 文字を超えてはなりません。

{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
+  "manifestVersion": "1.17",
"version": "1.0.0",
"id": "04805b4b-xxxx-xxxx-xxxx-4dbc1cac8f89",
"packageName": "com.microsoft.teams.extension",
"developer": {
    "name": "Teams App, Inc.",
    "websiteUrl": "https://www.example.com",
    "privacyUrl": "https://www.example.com/termofuse",
    "termsOfUseUrl": "https://www.example.com/privacy"
},
"icons": {
    "color": "color.png",
    "outline": "outline.png"
},
"name": {
    "short": "AI tools",
    "full": "AI tools"
},
"description": {
    "short": "AI tools",
    "full": "AI tools"
},
"accentColor": "#FFFFFF",
"composeExtensions": [
    {
+      "composeExtensionType": "apiBased",
+      "authorization": {
+        "authType": "apiSecretServiceAuth ",
+        "apiSecretServiceAuthConfiguration": {
+            "apiSecretRegistrationId": "9xxxxxxx-7xxx-4xxx-bxxx-1xxxxxxxxxxx"
+        }
+      },
+      "apiSpecificationFile": "aitools-openapi.yml",
       "commands": [
       {
          "id": "searchTools",
          "type": "query",
          "context": [
             "compose",
             "commandBox"
          ],
          "title": "search for AI tools",
          "description": "search for AI tools",
          "parameters": [
             {
             "name": "search",
             "title": "search query",
             "description": "e.g. search='tool to create music'"
             }
          ],
+          "apiResponseRenderingTemplateFile": "response-template.json"
       }
       ]
    }
],
"validDomains": []
}

パラメーター

名前	説明
`composeExtensions.composeExtensionType`	Compose拡張機能の種類。値を `apiBased` に更新します。
`composeExtensions.authorization`	API ベースのメッセージ拡張機能の承認に関する情報
`composeExtensions.authorization.authType`	可能な承認の種類の列挙型。サポートされている値は `none`、`apiSecretServiceAuth`、`microsoftEntra` です。
`composeExtensions.authorization.apiSecretServiceAuthConfiguration`	サービス認証を実行するために必要なオブジェクトキャプチャの詳細。認証の種類が `apiSecretServiceAuth`されている場合にのみ適用されます。
`composeExtensions.authorization.apiSecretServiceAuthConfiguration.apiSecretRegistrationId`	開発者が開発者ポータルを介して API キーを送信したときに返される登録 ID。
`composeExtensions.apiSpecificationFile`	アプリパッケージ内の OpenAPI Description ファイルを参照します。型が `apiBased`されている場合に含めます。
`composeExtensions.commands.id`	検索コマンドに割り当てる一意の ID。ユーザー要求には、この ID が含まれています。 ID は、OpenAPI Description で使用可能な `OperationId` と一致している必要があります。
`composeExtensions.commands.context`	メッセージ拡張のエントリポイントが定義されている配列。既定値は `compose` と `commandBox`です。
`composeExtensions.commands.parameters`	コマンドのパラメーターの静的リストを定義します。名前は、OpenAPI Description の `parameters.name` にマップする必要があります。要求本文スキーマでプロパティを参照している場合、名前は `properties.name` またはクエリパラメーターにマップする必要があります。
`composeExtensions.commands.apiResponseRenderingTemplateFile`	開発者の API からアダプティブカード応答への JSON 応答の書式設定に使用されるテンプレート。 [必須]

詳細については、「 composeExtensions」を参照してください。

3. 応答レンダリングテンプレート

$schema プロパティでスキーマ参照 URL を定義して、テンプレートの構造を確立します。
responseLayoutでサポートされている値はlistとgridであり、応答がどのように視覚的に表示されるかを決定します。
配列の場合、またはアダプティブカードのデータがルートオブジェクトではない場合は、jsonPathをお勧めします。たとえば、データが productDetailsの下に入れ子になっている場合、JSON パスは productDetailsされます。
jsonPathを、API 応答の関連データまたは配列へのパスとして定義します。パスが配列を指している場合、配列内の各エントリはアダプティブカードテンプレートとバインドされ、個別の結果として返されます。 [省略可能]
応答レンダリングテンプレートを検証するためのサンプル応答を取得します。これは、テンプレートが期待どおりに動作することを確認するためのテストとして機能します。
Fiddler や Postman などのツールを使用して API を呼び出し、要求と応答が有効であることを確認します。この手順は、API が正しく機能していることをトラブルシューティングして確認するために重要です。
アダプティブカード Designerを使用して、API 応答を応答レンダリングテンプレートにバインドし、アダプティブカードをプレビューできます。 カードペイロードエディターにテンプレートを挿入し、サンプルデータエディターにサンプル応答エントリを挿入します。

次のコードは、応答レンダリングテンプレートの例です。

応答レンダリングテンプレートの例

{
"version": "1.0",
"jsonPath": "repairs",
"responseLayout": "grid",
"responseCardTemplate": {
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "ColumnSet",
          "columns": [
            {
              "type": "Column",
              "width": "stretch",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Title: ${if(title, title, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "Description: ${if(description, description, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "Image",
                  "url": "${image}",
                  "size": "Medium",
                  "$when": "${image != null}"
                }
              ]
            },
            {
              "type": "Column",
              "width": "auto",
              "items": [
                {
                  "type": "Image",
                  "url": "${if(image, image, '')}",
                  "size": "Medium"
                }
              ]
            }
          ]
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Repair ID:",
              "value": "${if(id, id, 'N/A')}"
            },
            {
              "title": "Date:",
              "value": "${if(date, date, 'N/A')}"
            }
          ]
        }
      ]
    }
  ]
  },
  "previewCardTemplate": {
  "title": "Title: ${if(title, title, 'N/A')}",
  "subtitle": "Description: ${if(description, description, 'N/A')}",
  "text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
  "image": {
    "url": "${image}",
    "$when": "${image != null}"
    }
  }
 }

プレビューカード

特定の単語を検索するときにプレビューカードの配列を表示する新規作成拡張機能の例を示すスクリーンショット。この場合、'SME テストアプリ' で 'a' を検索すると、それぞれ 'Title'、'Description' (切り捨て) および 'AssignedTo' のプロパティと値を示す 5 枚のカードが返されます。

拡張アダプティブカード

ユーザーがプレビューカードを選択した後のアダプティブカードの展開の例。アダプティブカードには、タイトル、完全な説明、AssignedTo、RepairId、および Date の値が表示されます。

パラメーター

プロパティ	型	説明	必須
`version`	`string`	現在の応答レンダリングテンプレートのスキーマバージョン。	はい
`jsonPath`	`string`	responseCardTemplate と previewCardTemplate を適用する必要がある結果の関連セクションへのパス。設定されていない場合、ルートオブジェクトは関連セクションとして扱われます。関連するセクションが配列の場合、各エントリは responseCardTemplate と previewCardTemplate にマップされます。	不要
`responseLayout`	`responseLayoutType`	メッセージ拡張ポップアップの結果のレイアウトを指定します。サポートされている型は、 `list` と `grid`です。	はい
`responseCardTemplate`	`adaptiveCardTemplate`	結果エントリからアダプティブカードを作成するためのテンプレート。	はい
`previewCardTemplate`	`previewCardTemplate`	結果エントリからプレビューカードを作成するためのテンプレート。結果のプレビューカードは、メッセージ拡張機能のポップアップメニューに表示されます。	はい

JSON パス

JSON パスは省略可能ですが、配列に使用することも、アダプティブカードのデータとして使用するオブジェクトがルートオブジェクトではない場合にも使用できます。 JSON パスは、Newtonsoft によって定義された形式に従う必要があります。 JSON パスが配列を指している場合、その配列内の各エントリはアダプティブカードテンプレートにバインドされ、個別の結果として返されます。

例たとえば、製品の一覧に対して以下の JSON があり、エントリごとにカード結果を作成するとします。

{
   "version": "1.0",
   "title": "All Products",
   "warehouse": {
      "products": [
        ...
      ]
   }
}

ご覧のとおり、結果の配列は "products" の下にあり、これは "warehouse" の下に入れ子になっているため、JSON パスは "warehouse.products" になります。

アダプティブカード Designerを使用して、カードペイロードエディターにテンプレートを挿入してアダプティブカードをプレビューします。配列またはオブジェクトのサンプル応答エントリを取得し、サンプルデータエディターに挿入します。カードが適切にレンダリングされ、好みに合っていることを確認します。

スキーママッピング

OpenAPI Description ドキュメントのプロパティは、次のようにアダプティブカードテンプレートにマップされます。

string、 number、 integer、 boolean 型は TextBlock に変換されます。
例
- ソーススキーマ: string、 number、 integer、および boolean
```
 name:
   type: string
   example: doggie
```
- ターゲットスキーマ: Textblock
```
{
"type": "TextBlock",
"text": "name: ${if(name, name, 'N/A')}",
"wrap": true
}
```

array: 配列はアダプティブカード内のコンテナーに変換されます。

例

ソーススキーマ: array

    type: array
              items:
              required:
                - name
              type: object
                properties:
                id:
                  type: integer
                category:
                  type: object
                  properties:
                  name:
                    type: string

ターゲットスキーマ: Container

    {
              "type": "Container",
              "$data": "${$root}",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "id: ${if(id, id, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "category.name: ${if(category.name, category.name, 'N/A')}",
                  "wrap": true
                }
              ]
            }

object: オブジェクトがアダプティブカードの入れ子になったプロパティに変換されます。

例

ソーススキーマ: object

components:
  schemas:
    Pet:
        category:
          type: object
        properties:
          id:
            type: integer
          name:
            type: string

ターゲットスキーマ: アダプティブカードの入れ子になったプロパティ

{
  "type": "TextBlock",
  "text": "category.id: ${if(category.id, category.id, 'N/A')}",
  "wrap": true
},
{
  "type": "TextBlock",
  "text": "category.name: ${if(category.name, category.name, 'N/A')}",
  "wrap": true
}

image: プロパティがイメージ URL の場合は、アダプティブカードの Image 要素に変換されます。

例

ソーススキーマ: image

    image:
      type: string
      format: uri
      description: The URL of the image of the item to be repaired

ターゲットスキーマ: "Image"

{
      "type": "Image",
      "url": "${image}",
      "$when": "${image != null}"
    }

Api ベースのメッセージ拡張機能は、開発者ポータル for Teams、Microsoft 365 Agents Toolkit (以前は Teams Toolkit) for Visual Studio Code、コマンドラインインターフェイス (CLI)、または Visual Studio を使用して作成できます。

開発者ポータルを使用して API ベースのメッセージ拡張機能を作成するには、次の手順に従います。

開発者ポータルに移動します。
[アプリ] に移動します。
[ + 新しいアプリ] を選択します。
アプリの名前を入力し、 マニフェストバージョン を パブリック開発者プレビュー (devPreview) として選択します。
[追加] を選択します。
左側のウィンドウの [ 構成] で、次の 基本情報を更新します。
1. フルネーム
2. 簡潔な説明
3. 詳しい説明
4. 開発者または会社名
5. Web サイト (有効な HTTPS URL である必要があります)
6. プライバシーポリシー
7. 使用条件
[保存] を選択します。
[ アプリ機能] を選択します。
[ メッセージ拡張機能] を選択します。
[ メッセージ拡張機能の種類] で、[API] を選択 します。
1. Bot メッセージ拡張機能を読み取る免責事項 がユーザーによって既に使用されている場合。メッセージ拡張機能の種類を API に変更しますか?、 はい、変更を選択します。
[ OpenAPI spec]$OpenAPI 仕様$ で、[ 今すぐアップロード] を選択します。
JSON または YAML 形式で OpenAPI Description ドキュメントを選択し、[ 開く] を選択します。
[保存] を選択します。メッセージ API 仕様が正常に保存されたポップアップが表示されます。
[ 入手] を選択します。

コマンドの追加

注:

API からビルドされたメッセージ拡張機能は、1 つのパラメーターのみをサポートします。

コマンドとパラメーターをメッセージ拡張機能に追加して、コマンドを追加できます。

[ メッセージ拡張機能の種類] で、[ 追加] を選択します。

[ コマンドの追加] ポップアップが表示され、OpenAPI Description ドキュメントから使用可能なすべての API の一覧が表示されます。
一覧から API を選択し、[ 次へ] を選択します。
[ 応答テンプレート] で、[ 今すぐアップロード] を選択します。

注:

複数の API がある場合は、各 API のアダプティブカード応答テンプレートをアップロードしてください。
JSON 形式のアダプティブカード応答テンプレートファイルを選択し、[ 開く] を選択します。

アダプティブカードテンプレートから次の属性が自動的に更新されます。
- コマンドの種類
- コマンド ID
- コマンドのタイトル
- パラメーター名
- パラメータの説明
[ 詳細] で、 コマンドの説明を更新します。
Microsoft 365 Copilotでトリガーを使用してコマンドを起動する場合は、[ユーザーが拡張機能を開いたときにこのコマンドを自動的に実行する] トグルをオンにします。
[追加] を選択します。コマンドが正常に追加されました。
[保存] を選択します。
[ 認証と承認] で、次のいずれかのオプションを選択します。
- 認証なし (推奨されません)
- API キー
- OAuth

API ベースのメッセージ拡張機能が作成されます。

開発者ポータルで作成された API ベースのメッセージ拡張機能をテストするには、次の方法を使用します。

Teams でのプレビュー: メッセージ拡張機能を開き、右上隅 にある [Teams でプレビュー ] を選択します。 Teams にリダイレクトされ、アプリを Teams に追加してアプリをプレビューできます。
アプリパッケージのダウンロード: メッセージ拡張機能ページで、左側のウィンドウで [ アプリパッケージ ] を選択し、ウィンドウの左上隅にある [ アプリパッケージのダウンロード] を選択します。アプリパッケージは、.zip ファイル内のローカルコンピューターにダウンロードされます。アプリパッケージをチームにアップロードし、メッセージ拡張機能をテストできます。

注:

エージェントツールキットでは、OpenAPI 仕様バージョン 2.0 と 3.0.x がサポートされています。

Agents Toolkit for Visual Studio Code を使用して API ベースのメッセージ拡張機能を構築するには、次の手順に従います。

Visual Studio Code を開きます。
左側のウィンドウで、[ Microsoft 365 エージェントツールキット] を選択します。
[Create a New Agent/App>Teams App]$新しいエージェント/アプリTeams アプリの作成$ を選択します。
[ メッセージ拡張機能] を選択します。
[ カスタム検索結果] を選択します。
以下のいずれかのオプションを選択します。
1. 最初からビルドするには、[ 新しい API で開始] を選択します。
2. OpenAPI 説明ドキュメントが既にある場合は、[ OpenAPI 説明ドキュメントから開始] を選択します。

手順 6 で選択したオプションに基づいて、次を選択します。

新しい API
OpenAPI の説明

注:

Microsoft Entraの認証フローは、リモート環境でのみ機能します。 Azure関数コアツールでの認証サポートがないため、ローカル環境でテストすることはできません。修復 API は、ローカル環境で匿名で呼び出すことができます。

認証の種類を選択します。
- なし: ユーザーが API にアクセスするための認証を行わない場合は、選択します。
- API キー: API キーを使用して認証するかどうかを選択します。
- Microsoft Entra: アプリユーザーの Teams ID を使用して認証するかどうかを選択します。
プログラミング言語を選択します。
[ 既定のフォルダー] を選択します。
アプリの名前を入力し、[Enter] を選択 します。 Agents Toolkit は、Azure関数から API を使用して新しいプラグインを作成します。

開始するには、次のファイルのソースコードを更新する必要があります。

File	コンテンツ
`src/functions/repair.ts`	Azure Functionsの関数のメインファイル。 HTTP GET 要求からクエリパラメーターに基づいて修復レコードを取得およびフィルター処理し、結果を JSON 応答として返すAzure関数を定義します。
`src/repairsData.json`	修復 API のデータソース。
`src/keyGen.ts`	承認に使用される API キーを生成するように設計されています。
`appPackage/apiSpecificationFile/repair.yml`	修復 API の構造と動作を記述するファイル。
`appPackage/responseTemplates/repair.json`	API 応答をレンダリングするためのテンプレートファイル。
`m365agents.yml`	メインの Agents Toolkit プロジェクトファイル。プロジェクトファイルには、プロパティと構成ステージ定義という 2 つの主要な要素が定義されています。
`m365agents.local.yml`	ローカルの実行とデバッグを有効にするアクションでm365agents.ymlをオーバーライドします。
`aad.manifest.json`	アプリの構成Microsoft Entra定義します。このテンプレートでは、1 つのテナント Microsoft Entra アプリのみがプロビジョニングされます。

手順 a で選択したオプションに基づいて、次の手順に従います。
- [なし] または [Microsoft Entra] を選択した場合は、次の手順に進みます。
- API キーを選択した場合は、次の手順に従います。
  
  次のように API キーを生成して設定します。
  1. Visual Studio Code で、[ 表示>ターミナル] に移動します。
  2. 依存関係パッケージをインストールするには、次のコマンドを実行します。
```
npm install
```
  3. 次のコマンドを実行して API キーを生成します。
```
npm run keygen
```
    API キーは、 生成された新しい API キー xxx...として生成されます。生成された API キーは、開発者ポータルの API キー登録ツールに登録され、記録されます。 API キーの登録の詳細については、「 API キーの登録」を参照してください。
  4. 生成された API キーを env/.env.*.user ファイルに入力します。 <your-api-key>を実際のキーに置き換えます。
```
SECRET_API_KEY=<your-api-key>
```

OpenAPI Description ドキュメントの場所を入力または参照します。
API の一覧から、必要な API を選択し、[ OK] を選択します。

注:

API ベースのメッセージ拡張機能では、GET API と POST API がサポートされています。
[ 既定のフォルダー] を選択します。
アプリの名前を入力し、[Enter] を選択 します。 Agents Toolkit は、OpenAPI Description ドキュメントをスキャフォールディングし、API ベースのメッセージ拡張機能を作成します。
[ ライフサイクル] で、[プロビジョニング] を選択 します。
OpenAPI 仕様ドキュメントに、HTTP ベアラースキームを使用するセキュリティスキーム bearerAuthがある場合は、コマンドウィンドウで API キーを入力し、[Enter] を選択 します。

注:

API キーは、10 から 2048 文字の文字列である必要があります。

注:

Agents Toolkit ソースファイルには、受信要求が承認されていることを確認するためのセキュリティチェックが含まれています。関数 isApiKeyValid(req) を使用して、要求に有効な API キーが含まれているかどうかを確認します。 API キーが有効でない場合、コードは未承認の応答を示す 401 HTTP 状態コードを返します。

左側のウィンドウで、[ Microsoft 365 エージェントツールキット] を選択します。
[アカウント] で、Microsoft 365 アカウントでサインインし、アカウントをAzureします (まだサインインしていない場合)。
左側のウィンドウで、 実行とデバッグ (Ctrl + Shift + D) を選択します。
[起動構成] ドロップダウンから、[ Preview in Teams (Edge) ] または [ Preview in Teams (Chrome)] を選択します。 Agents Toolkit は、ブラウザーウィンドウで Teams Web クライアントを起動します。
チャットメッセージに移動し、[ アクションとアプリ ] アイコンを選択します。ポップアップメニューで、アプリを検索します。
一覧からメッセージ拡張機能を選択し、検索ボックスに検索コマンドを入力します。
一覧から項目を選択します。アイテムは、メッセージ作成領域のアダプティブカードに展開されます。
Enter キーを選択すると、Teams はチャットメッセージのアダプティブカードとして検索結果を送信します。

Microsoft 365 Agents Toolkit CLI (以前は Teams Toolkit CLI と呼ばれる) を使用して API ベースのメッセージ拡張機能を作成するには、次の手順に従います。

[コマンドプロンプト] に移動します。
次のコマンドを入力します:
```
npm install -g @microsoft/atk-cli
```
ターミナルに「 atk new 」と入力します
[ メッセージ拡張機能] を選択します。
[ カスタム検索結果] を選択します。
OpenAPI 説明ドキュメントから [開始] を選択します。
OpenAPI Description ドキュメントの有効な URL またはローカルパスを入力します。
一覧から API を選択し、[Enter] を選択 します。
プロジェクトの場所を入力し、[Enter] を選択 します。
アプリケーションの名前を入力し、[Enter] を選択 します。
プロジェクトが作成されるフォルダーパスに移動し、次のコマンドを入力して、Azureでアプリをプロビジョニングします。

atk provision --env dev

Agents Toolkit CLI によってブラウザーウィンドウが開き、Microsoft アカウントへのサインインを要求します。
Microsoft アカウントにサインインします。 Agents Toolkit CLI は、検証を実行し、Azureでアプリをプロビジョニングします。
コマンドプロンプトウィンドウで、次のコマンドを入力して、Teams でアプリをプレビューします。

atk preview --env dev

Teams Web クライアントが表示された新しいブラウザーウィンドウが開きます。アプリを Teams に追加できます。

作業を開始する前に、Visual Studio Enterprise 2022 Preview バージョン 17.9.0 Preview 1.0 をインストールし、ASP.NET と Web 開発ワークロードの下にMicrosoft Teams開発ツールをインストールしてください。

Agents Toolkit for Visual Studio を使用して API ベースのメッセージ拡張機能を作成するには、次の手順に従います。

Visual Studio を開きます。
[ファイル>New>Project... または [新しいプロジェクト] に移動します。
Microsoft を検索し、[Microsoft 365 エージェント] を選択します。
[プロジェクト名] と [場所] を入力します。
[作成] を選択します。
[ API からの検索結果] を選択します。
次のいずれかのオプションを選択します。
- API なしで開始する場合は、[ 新しい API で開始] を選択します。
- 既存の OpenAPI 説明ドキュメントがある場合は、[ OpenAPI Description で開始] を選択します。
[作成] を選択します。

手順 7 で選択したオプションに基づいて、次を選択します。

新しい API
OpenAPI の説明

開始するには、次のファイルのソースコードを更新する必要があります。

File	コンテンツ
`Repair.cs`	Azure Functionsの関数のメインファイル。 HTTP GET 要求からクエリパラメーターに基づいて修復レコードを取得およびフィルター処理し、結果を JSON 応答として返すAzure関数を定義します。
`RepairData.cs`	修復 API のデータソース。自動車修理タスクのハードコーディングされたリストを返すメソッドが含まれています。
`Models/RepairModel.cs`	ID、タイトル、説明、AssignedTo、Date、Image などのプロパティを持つ修復タスクを表すデータモデルを定義します。
`appPackage/apiSpecificationFile/repair.yml`	修復 API の構造と動作を記述するファイル。
`appPackage/responseTemplates/repair.json`	API 応答のレンダリングに使用される生成されたアダプティブカード。
`appPackage/responseTemplates/repair.data.json`	修復 API のデータソース。
`m365agents.yml`	メインの Agents Toolkit プロジェクトファイル。プロジェクトファイルには、プロパティと構成ステージ定義という 2 つの主要な要素が定義されています。
`m365agents.local.yml`	ローカルの実行とデバッグを有効にするアクションでm365agents.ymlをオーバーライドします。

ソースコードを更新したら、デバッグドロップダウンメニューの [Dev Tunnel (アクティブなトンネルなし)]> [トンネルの作成]を選択します。...
トンネルを作成するアカウントを選択します。サポートされているアカウントの種類は、Azure、Microsoft アカウント (MSA)、GitHub です。
1. [名前]: トンネルの名前を入力します。
2. トンネルの種類: [永続的] または [ 一時的] を選択します。
3. アクセス: [ パブリック] を選択します。
4. [OK] を選択します。 Visual Studio では、トンネルが作成されたことを示す確認メッセージが表示されます。
作成したトンネルが [ Dev Tunnel]$開発トンネル$ の下に一覧表示されます。
[ソリューションエクスプローラー] に移動し、プロジェクトを選択します。
メニューを右クリックし、[Microsoft 365 エージェントツールキット] >[Microsoft 365 アカウントの選択] を選択します。

メッセージが表示されたら、Microsoft 365 アカウントでサインインします。アプリが正常に準備されたことを示すメッセージが表示されます。
F5 キーを選択するか、[デバッグ>デバッグの開始] を選択します。 Visual Studio が Teams Web クライアントを起動します。

チャットに移動し、[ アクションとアプリ] を選択します。
メッセージ拡張機能のポップアップメニューから、検索ボックスにメッセージ拡張機能の名前を入力します。
メッセージ拡張機能を選択し、検索クエリを入力します。
一覧から項目を選択します。アイテムは、メッセージ作成領域のアダプティブカードに展開されます。
Enter キーを選択すると、Teams はチャットメッセージのアダプティブカードとして検索結果を送信します。

複数パラメーター

複数パラメーターを使用すると、API ベースのメッセージ拡張機能でクエリコマンドに対して複数の入力型を使用できます。たとえば、ジャンル、レーティング、ステータス、日付でアニメを検索できます。

アプリマニフェスト
Agents Toolkit

マニフェスト内のパラメーターの入力型、タイトル、説明、および必須フィールドを指定できます。

パラメーターフィールドの isRequired プロパティは、パラメーターがクエリコマンドに必須かどうかを示します。
アプリマニフェストのparameters フィールドの name プロパティは、対応するパラメーターの OpenAPI Description ドキュメントのid フィールドと一致する必要があります。

例

"composeExtensions": [
        {
            "composeExtensionType": "apiBased",
            "apiSpecificationFile": "apiSpecificationFiles/openapi.json",
            "commands": [
                {
                    "context": [
                        "compose"
                    ],
                    "type": "query",
                    "title": "Search Animes",
                    "id": "getAnimeSearch",
                    "parameters": [
                        {
                            "name": "q",
                            "title": "Search Query",
                            "description": "The search query",
                            "isRequired": true
                        },
                        {
                            "name": "type",
                            "inputType": "choiceset",
                            "title": "Type",
                            "description": "Available anime types",
                            "choices": [
                                {
                                    "title": "TV",
                                    "value": "tv"
                                },
                                {
                                    "title": "OVA",
                                    "value": "ova"
                                },
                                {
                                    "title": "Movie",
                                    "value": "movie"
                                },
                                {
                                    "title": "Special",
                                    "value": "special"
                                },
                                {
                                    "title": "ONA",
                                    "value": "ona"
                                },
                                {
                                    "title": "Music",
                                    "value": "music"
                                }
                            ]
                        },
                        {
                            "name": "status",
                            "inputType": "choiceset",
                            "title": "Status",
                            "description": "Available airing statuses",
                            "choices": [
                                {
                                    "title": "Airing",
                                    "value": "airing"
                                },
                                {
                                    "title": "Completed",
                                    "value": "complete"
                                },
                                {
                                    "title": "Upcoming",
                                    "value": "upcoming"
                                }
                            ]
                        },
                        {
                            "name": "rating",
                            "inputType": "choiceset",
                            "title": "Rating",
                            "description": "Available ratings",
                            "choices": [
                                {
                                    "title": "G",
                                    "value": "g"
                                },
                                {
                                    "title": "PG",
                                    "value": "pg"
                                },
                                {
                                    "title": "PG-13",
                                    "value": "pg13"
                                },
                                {
                                    "title": "R",
                                    "value": "r17"
                                },
                                {
                                    "title": "R+",
                                    "value": "r"
                                },
                                {
                                    "title": "Rx",
                                    "value": "rx"
                                }
                            ]
                        }
                    ],
                    "description": "Search animes",
                    "apiResponseRenderingTemplateFile": "response_json/getAnimeSearch.json"
                },
                {
                    "context": [
                        "compose"
                    ],
                    "type": "query",
                    "title": "Search mangas",
                    "id": "getMangaSearch",
                    "parameters": [
                        {
                            "name": "q",
                            "title": "Search Query",
                            "description": "The search query",
                            "isRequired": true
                        },
                        {
                            "name": "type",
                            "inputType": "choiceset",
                            "title": "Type",
                            "description": "Available manga types",
                            "choices": [
                                {
                                    "title": "Manga",
                                    "value": "manga"
                                },
                                {
                                    "title": "Novel",
                                    "value": "novel"
                                },
                                {
                                    "title": "Light Novel",
                                    "value": "lightnovel"
                                },
                                {
                                    "title": "One Shot",
                                    "value": "oneshot"
                                },
                                {
                                    "title": "Doujin",
                                    "value": "doujin"
                                },
                                {
                                    "title": "Manhwa",
                                    "value": "manhwa"
                                },
                                {
                                    "title": "Manhua",
                                    "value": "manhua"
                                }
                            ]
                        },
                        {
                            "name": "status",
                            "inputType": "choiceset",
                            "title": "Status",
                            "description": "Available manga statuses",
                            "choices": [
                                {
                                    "title": "Publishing",
                                    "value": "publishing"
                                },
                                {
                                    "title": "Complete",
                                    "value": "complete"
                                },
                                {
                                    "title": "Hiatus",
                                    "value": "hiatus"
                                },
                                {
                                    "title": "Discontinued",
                                    "value": "discontinued"
                                },
                                {
                                    "title": "Upcoming",
                                    "value": "upcoming"
                                }
                            ]
                        },
                        {
                            "name": "start_date",
                            "title": "Start Date",
                            "description": "Start date of the manga",
                            "inputType": "date"
                        },
                        {
                            "name": "end_date",
                            "title": "End Date",
                            "description": "End date of the manga",
                            "inputType": "date"
                        }
                    ],

Agents Toolkit for Visual Studio Code を使用して複数のパラメーターを使用して API ベースのメッセージ拡張機能を構築するには、次の手順に従います。

Visual Studio Code を開きます。
左側のウィンドウで、[ Microsoft 365 エージェントツールキット] を選択します。
[Create a New Agent/App>Teams App]$新しいエージェント/アプリTeams アプリの作成$ を選択します。
[ メッセージ拡張機能] を選択します。
[ カスタム検索結果] を選択します。
以下のいずれかのオプションを選択します。
1. 最初からビルドするには、[ 新しい API で開始] を選択します。
2. OpenAPI 説明ドキュメントが既にある場合は、[ OpenAPI 説明ドキュメントから開始] を選択します。
OpenAPI Description ドキュメントの場所を入力または参照します。
API の一覧から、必要な API を選択し、[ OK] を選択します。

注:

API ベースのメッセージ拡張機能では、GET API と POST API がサポートされています。
[ 既定のフォルダー] を選択します。
アプリの名前を入力し、[Enter] を選択 します。 Agents Toolkit は、OpenAPI Description ドキュメントをスキャフォールディングし、API ベースのメッセージ拡張機能を作成します。
[ ライフサイクル] で、[プロビジョニング] を選択 します。
左側のウィンドウで、[ Microsoft 365 エージェントツールキット] を選択します。
[アカウント] で、Microsoft 365 アカウントでサインインし、アカウントをAzureします (まだサインインしていない場合)。
左側のウィンドウで、 実行とデバッグ (Ctrl + Shift + D) を選択します。
[起動構成] ドロップダウンから、[ Preview in Teams (Edge) ] または [ Preview in Teams (Chrome)] を選択します。 Agents Toolkit は、ブラウザーウィンドウで Teams Web クライアントを起動します。
チャットメッセージに移動し、[ アクションとアプリ ] アイコンを選択します。ポップアップメニューで、アプリを検索します。
一覧からメッセージ拡張機能を選択し、検索ボックスに検索コマンドを入力します。
[ PetId ] ドロップダウンから必要なパラメーターを選択し、[ テキスト ] ボックスにセカンダリパラメーターとして必要な詳細を入力します。
[ 検索 ] を選択し、ポップアップメニューから出力を選択します。
必要な詳細を含むアダプティブカードがメッセージ作成領域に表示されます。 Enter キーを押します。