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

[アーティクル]
10/28/2024

注:

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

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

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

1. OpenAPI Description (OAD)

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

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

次のコードは、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 説明で使用可能な ID と一致 `OperationId` している必要があります。
`composeExtensions.commands.context`	メッセージ拡張のエントリポイントが定義されている配列。既定値はと `commandBox`です`compose`。
`composeExtensions.commands.parameters`	コマンドのパラメーターの静的リストを定義します。この名前は、OpenAPI Description 内のにマップ `parameters.name` する必要があります。要求本文スキーマでプロパティを参照している場合は、名前をパラメーターまたはクエリパラメーターにマップする `properties.name` 必要があります。
`composeExtensions.commands.apiResponseRenderingTemplateFile`	開発者の API からアダプティブカード応答への JSON 応答の書式設定に使用されるテンプレート。 [必須]

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

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

注:

Teams では、バージョン 1.5 までのアダプティブカードがサポートされ、アダプティブカード Designerはバージョン 1.6 までサポートされます。

テンプレートの構造を確立するには、 $schema プロパティでスキーマ参照 URL を定義します。
でサポートされている値 responseLayout は list と gridで、応答がどのように視覚的に表示されるかを決定します。
配列jsonPathの場合、またはアダプティブカードのデータがルートオブジェクトではない場合は、をお勧めします。たとえば、データがの下 productDetailsに入れ子になっている場合、JSON パスはになります productDetails。
API 応答の関連データまたは配列へのパスとして定義jsonPathします。パスが配列を指している場合、配列内の各エントリはアダプティブカードテンプレートとバインドされ、個別の結果として返されます。 [省略可能]
応答レンダリングテンプレートを検証するためのサンプル応答を取得します。これは、テンプレートが期待どおりに動作することを確認するためのテストとして機能します。
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`	メッセージ拡張ポップアップの結果のレイアウトを指定します。サポートされている型はと `grid`です`list`。	はい
`responseCardTemplate`	`adaptiveCardTemplate`	結果エントリからアダプティブカードを作成するためのテンプレート。	はい
`previewCardTemplate`	`previewCardTemplate`	結果エントリからプレビューカードを作成するためのテンプレート。結果のプレビューカードは、メッセージ拡張機能のポップアップメニューに表示されます。	はい

Json パス

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

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

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

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

https://adaptivecards.io/designer/テンプレートをカードペイロードエディターに挿入してアダプティブカードをプレビューし、配列またはオブジェクトのサンプル応答エントリを取得し、右側の同じデータエディターに挿入します。カードが適切にレンダリングされ、好みに合っていることを確認します。 Teams はバージョン 1.5 までのカードをサポートし、デザイナーは 1.6 をサポートします。

スキーママッピング

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

string、number、integerboolean型は 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 と Teams Toolkit for Visual Studio Code、コマンドラインインターフェイス (CLI)、または Visual Studio を使用して作成できます。

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

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

コマンドの追加

注:

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

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

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

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

コマンドの詳細が表示されます。
[コマンドの詳細] で、[アダプティブカードテンプレート] に移動し、[今すぐアップロード] を選択します。

注:

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

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

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

スクリーンショットは、Teams 開発者ポータルのアプリ機能ページで作成されたMicrosoft 365 Copilotのプラグインを示しています。

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

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

注:

Teams Toolkit では、OpenAPI 仕様バージョン 2.0 と 3.0.x がサポートされています。

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

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

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

新しい API
OpenAPI の説明

注:

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

認証の種類を選択します。
- なし: ユーザーが API にアクセスするための認証を行わない場合は、選択します。
- API キー: API キーを使用して認証するかどうかを選択します。
- Microsoft Entra: アプリユーザーの Teams ID を使用して認証するかどうかを選択します。
プログラミング言語を選択します。
[ 既定のフォルダー] を選択します。
アプリの名前を入力し、[Enter] を選択 します。 Teams 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 応答をレンダリングするためのテンプレートファイル。
`teamsapp.yml`	メイン Teams Toolkit プロジェクトファイル。プロジェクトファイルには、プロパティと構成ステージ定義という 2 つの主要な要素が定義されています。
`teamsapp.local.yml`	ローカル実行とデバッグを有効にするアクションでteamsapp.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 キーは、Teams 用開発者ポータルの 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] を選択 します。 Teams Toolkit は OpenAPI Description ドキュメントをスキャフォールディングし、API ベースのメッセージ拡張機能を作成しました。
[ ライフサイクル] で、[プロビジョニング] を選択 します。
OpenAPI 仕様ドキュメントに、HTTP ベアラースキームを使用するセキュリティスキーム bearerAuthがある場合は、コマンドウィンドウで API キーを入力し、[Enter] を選択 します。

注:

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

注:

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

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

Teams のチャットメッセージに検索結果が表示されたアダプティブカードを示すスクリーンショット。

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

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

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

Preview the app: teamsapp preview --env dev

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

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

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

Visual Studio を開きます。
[ファイル>] [新しいプロジェクト]、[新しい>プロジェクト] の順に移動します。
Teams を検索し、[アプリのMicrosoft Teams] を選択します。
[プロジェクト名] と [場所] を入力します。
[作成] を選択します。
[ 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 のデータソース。
`teamsapp.yml`	メイン Teams Toolkit プロジェクトファイル。プロジェクトファイルには、プロパティと構成ステージ定義という 2 つの主要な要素が定義されています。
`teamsapp.local.yml`	ローカル実行とデバッグを有効にするアクションでteamsapp.ymlをオーバーライドします。

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

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

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

ステップバイステップのガイド

API ベースのメッセージ拡張機能を構築するには、次のステップバイステップガイドに従います。

初心者向け: Teams Toolkit を使用して API ベースのメッセージ拡張機能を構築します。
上級ユーザーの場合: API ベースのメッセージ拡張機能を最初からビルドします。

次の方法で共有

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

パラメーター

パラメーター

Json パス

スキーママッピング

ステップバイステップのガイド

関連項目

その他のリソース

次の方法で共有

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

パラメーター

パラメーター

Json パス

スキーマ マッピング

ステップ バイ ステップのガイド

関連項目

その他のリソース

スキーママッピング

ステップバイステップのガイド