初心者向けの API-Based メッセージ拡張機能
注:
- API ベースのメッセージ拡張機能では、検索コマンドのみがサポートされます。
- Teams Toolkit では、OpenAPI 仕様バージョン 2.0 と 3.0.x がサポートされています。
API (API ベース) を使用して構築されたメッセージ拡張機能は、外部サービスと対話できるようにすることで、Teams アプリの機能を大幅に強化します。 さまざまなアプリケーションを切り替える必要性を減らすことで、ワークフローを合理化するのに役立ちます。
API メッセージ拡張機能を使用して、ビジネス ワークフローでよく使用される外部サービスを統合できます。 たとえば、顧客管理に CRM システムを頻繁に使用するビジネスでは、メッセージング拡張機能を使用して Teams から顧客データを直接取得して表示できます。 さまざまなアプリケーションを切り替える必要性を減らすことで、ユーザーは時間を節約し、改善します。 API ベースのメッセージ拡張機能は、Teams デスクトップ、Web、モバイル クライアントでサポートされています。
前提条件
アプリをビルドして展開するために必要なツールの一覧を次に示します。
| インストール | 使用するには... |
|---|---|
| Teams ツールキット | アプリのプロジェクト スキャフォールディングを作成する Microsoft Visual Studio Code 拡張機能。 最新バージョンを使用します。 |
| Microsoft Teams | Microsoft Teams、チャット、会議、通話を 1 か所で行うためにアプリを通じて作業するすべてのユーザーと共同作業を行うことができます。 |
| Node.js | バックエンド JavaScript ランタイム環境。 詳細については、「 プロジェクトの種類Node.js バージョン互換性テーブル」を参照してください。 |
| Microsoft Edge (推奨) または Google Chrome | 開発者ツールを備えたブラウザー。 |
| Visual Studio Code | JavaScript、TypeScript、または SharePoint Framework (SPFx) ビルド環境。 バージョン 1.55 以降を使用してください。 |
| Microsoft 365 開発者アカウント | アプリをインストールするための適切なアクセス許可を持つ Teams アカウントにアクセスします。 |
| Teams の開発者ポータル | OrganizationまたはMicrosoft Teams ストアに Teams アプリを構成、管理、発行するための Web ベースのポータル。 |
| OpenAPI Description (OAD) ドキュメント | API の機能を説明するドキュメント。 詳細については、「 OpenAPI の説明」を参照してください。 |
開発環境を準備する
必要なツールをインストールしたら、開発環境を設定します。
Teams Toolkit をインストールする
Teams ツールキットは、アプリのクラウド リソースのプロビジョニングとデプロイ、Teams ストアへの発行などを行うツールを使用して、開発プロセスを簡素化するのに役立ちます。
使用このツールキットは、Visual Studio Code または Teamsapp という CLI (コマンド ライン インターフェイス) で使用できます。
Visual Studio Code を開き、[拡張機能] ビュー (Ctrl + Shift + X / ⌘⇧-X または [ビュー >拡張機能] ) を選択します。
検索ボックスに、「Teams Toolkit」と入力します。
Teams Toolkit の横にある [インストール] を選択します。
Teams Toolkit アイコンが Visual Studio Code アクティビティ バーに表示されます。
Teams Toolkit は、Visual Studio Code Marketplace にもあります。
注:
Teams Toolkit の最新バージョンは v5 です。
Teams 開発テナントを設定する
テナント とは、チャット、ファイルの共有、会議の実行を行う Teams の組織のスペースまたはコンテナーのようなものです。 この領域は、カスタム アプリをアップロードしてテストする場所でもあります。 テナントを使って開発する準備ができているかどうかを確認しましょう。
カスタム アプリのアップロード オプションを確認する
アプリを作成したら、アプリを配布せずに Teams に読み込む必要があります。 このプロセスは、カスタム アプリのアップロードと呼ばれます。 このオプションを表示するには、Microsoft 365 アカウントにサインインします。
注:
Teams ローカル環境でアプリをプレビューおよびテストするために、カスタム アプリのアップロードが必要です。 有効になっていない場合は、Teams ローカル環境でアプリをプレビューしてテストすることはできません。
既にテナントがあり、管理者アクセス権がありますか? 実際にあるかどうかを確認しましょう。
Teams でカスタム アプリをアップロードできるかどうかを確認します。
Teams クライアントで、[ アプリ ] アイコンを選択します。
[アプリの管理] を選択します。
[ アプリのアップロード] を選択します。
[カスタム アプリのアップロード] オプションを探します。 オプションが表示された場合は、カスタム アプリのアップロードが有効になります。
注:
カスタム アプリをアップロードするオプションが見つからない場合は、Teams 管理者に問い合わせてください。
無料の Teams 開発者テナントを作成する (省略可能)
Teams 開発者アカウントをお持ちでない場合は、無料で取得できます。 Microsoft 365 開発者プログラムに参加します。
Microsoft 365 開発者プログラムに移動します。
[今すぐ参加] を選択し、画面の指示に従います。
ようこそ画面で、[E5 サブスクリプションの設定] を選択します。
管理者アカウントを設定します。 完了すると、次の画面が表示されます。
設定した管理者アカウントを使用して Teams にサインインします。 Teams に [カスタム アプリのアップロード] オプションがあることを確認します。
無料の Azure アカウントを取得します。
アプリをホストする場合、または Azure でリソースにアクセスする場合は、Azure サブスクリプションが必要です。 開始する前に無料でアカウントを作成してください。
これで、アカウントを設定するためのツールがすべて揃いました。 次に、開発環境を設定し、ビルドを開始しましょう。 最初にビルドするアプリを選択します。
API ベースのメッセージ拡張機能を構築する
Teams Toolkit を使用してプロジェクト ワークスペースを設定したら、次にボット プロジェクトをビルドします。 Microsoft 365 アカウントにサインインしていることを確認します。
Microsoft 365 アカウントにサインインする
このアカウントを使用して、Teams にサインインします。 Microsoft 365 開発者プログラム テナントを使用している場合は、Microsoft 365 アカウントは、登録中に設定した管理者アカウントです。
Visual Studio Code を開きます。
サイド バーで Teams Toolkit
アイコンを選択します。[M365 にサインイン (Sign in to M365)] を選択します。
既定の Web ブラウザーが開き、アカウントにサインインできます。
資格情報を使用して Microsoft 365 アカウントにサインインします。
メッセージが表示されたらブラウザーを閉じて、Visual Studio Code に戻ります。
Visual Studio Code 内の Teams Toolkit に戻ります。
このアカウントを使用して、Teams にサインインします。 Microsoft 365 開発者プログラム テナントを使用している場合は、Microsoft 365 アカウントは、登録中に設定した管理者アカウントです。
これで、アプリをビルドし、ローカルで実行する準備が整いました。
OpenAPI 説明ドキュメントを作成する
OpenAPI Description (OAD) は業界標準の仕様であり、OpenAPI ファイルの構造と概要について説明します。 これは、API を記述するための言語に依存しない、人間が判読できる形式です。 人間と機械の両方で読み書きが簡単です。 スキーマはマシンで読み取り可能であり、YAML または JSON のいずれかで表されます。
API ベースのメッセージ拡張機能を作成する前に、OpenAPI Description (OAD) ドキュメントが必要です。 API 仕様は、次の条件を満たす必要があります。
-
authプロパティは指定しないでください。 - JSON と YAML は、サポートされている形式です。
- OpenAPI バージョン 2.0 および 3.0.x がサポートされています。
- Teams では、oneOf、anyOf、allOf、および (swagger.io) コンストラクトはサポートされていません。
- 要求の配列の構築はサポートされていませんが、JSON 要求本文内の入れ子になったオブジェクトはサポートされています。
- 要求本文が存在する場合は、さまざまな API との互換性を確保するために、application/Json にする必要があります。
-
servers.urlプロパティの HTTPS プロトコル サーバー URL を定義します。 - 1 つのパラメーター検索のみがサポートされています。
- 既定値のない必須パラメーターは 1 つだけ許可されます。
- POST メソッドと GET HTTP メソッドのみがサポートされています。
- OpenAPI Description ドキュメントには、
operationIdが必要です。 - 操作には、既定値のない必須のヘッダー パラメーターまたは Cookie パラメーターを含めてはいけません。
- コマンドには、パラメーターを 1 つだけ指定する必要があります。
- OpenAPI 説明ドキュメントにリモート参照がないことを確認します。
- 既定値の必須パラメーターは省略可能と見なされます。
このチュートリアルの例として、次の OpenAPI Description を使用しました。
OpenAPI 説明ドキュメント
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" gives 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.
注:
Teams Toolkit では、OpenAPI 仕様バージョン 2.0 と 3.0.x がサポートされています。
OpenAPI 説明ドキュメントが作成されたので、アプリが GET または POST 要求に応答するための応答レンダリング テンプレートも必要になります。 応答レンダリング テンプレートは、アダプティブ カード テンプレート、プレビュー カード テンプレート、およびメタデータで構成されます。 Teams Toolkit または Teams 用開発者ポータルを使用してアプリをビルドする場合、応答レンダリング テンプレートは OpenAPI Description ドキュメントから自動的に抽出されます。
次のコードは、応答レンダリング テンプレートの例です。
応答レンダリング テンプレート
{
"version": "1.0.0",
"jsonPath": "tools",
"responseLayout": "list",
"responseCardTemplate": {
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "${if(name, name, 'N/A')}",
"size": "Large",
"weight": "Bolder",
"wrap": true
},
{
"type": "TextBlock",
"text": "Categories: ${join(categories, ', ')}",
"size": "Small",
"isSubtle": true,
"wrap": true
},
{
"type": "TextBlock",
"text": "${if(main_summary, main_summary, 'N/A')}",
"size": "Medium",
"wrap": true
},
{
"type": "TextBlock",
"text": "Supported Platforms: ${join(platforms, ', ')}",
"size": "Small",
"isSubtle": true,
"wrap": true
},
{
"type": "TextBlock",
"text": "Pricing Summary:",
"size": "Medium",
"weight": "Bolder",
"wrap": true
},
{
"type": "TextBlock",
"text": "${if(pricing_summary, pricing_summary, 'N/A')}",
"size": "Small",
"wrap": true
}
],
"actions": [
{
"type": "Action.OpenUrl",
"title": "Learn More",
"url": "${opentools_url}",
"$when": "${opentools_url != null}"
},
{
"type": "Action.OpenUrl",
"title": "Chat with Chatbot",
"url": "${chatbot_short_url}",
"$when": "${chatbot_short_url != null}"
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
},
"previewCardTemplate": {
"title": "${if(name, name, 'N/A')}"
}
}
OpenAPI 説明ドキュメントを使用するメッセージ拡張機能を作成できるようになりました。 OpenAPI 説明ドキュメントを使用して am メッセージ拡張機能を作成するには、次の手順に従います。
Visual Studio Code を開きます。
Visual Studio Code アクティビティ バーの [Teams Toolkit
] アイコンを選択します。[ 新しいアプリの作成] を選択します。
![Teams Toolkit サイドバーの [Create New Project]\(新しいプロジェクトの作成\) リンクの場所を示すスクリーンショット。](assets/images/teams-toolkit-v2/first-bot/create-project.png)
[ メッセージ拡張機能] を選択します。
[カスタム検索結果] を選択する
[ OpenAPI Description Document で開始] を選択します。
[ 参照 ] を選択し、先ほど保存した OpenAPI 説明ドキュメントを選択します。 ドキュメントで使用できる API の一覧が表示されます。
一覧から API を選択し、[ OK] を選択します。
[既定のフォルダー] を選択して、プロジェクトのルート フォルダーを既定の場所に格納します。
次の手順で既定の場所を変更することもできます。
[ 参照] を選択します。
![[場所の参照] オプションの選択を示すスクリーンショット。](assets/images/teams-toolkit-v2/first-bot/select-browse.png)
プロジェクト ワークスペースの場所を選択します。
[ フォルダーの選択] を選択します。
アプリに適した名前を入力し、[Enter] を選択 します。
ダイアログが表示されます。 [ はい、作成者を信頼する] または [いいえ] を選択します。要件に基づいて作成者を信頼しません 。
API ベースのメッセージ拡張機能を備えた Teams アプリは、数秒で作成されます。
アプリが作成されると、Teams Toolkit に次のメッセージが表示されます。
![[デバッグ] を選択するオプションと共に、機能が正常に作成されたことを示す Teams Toolkit からのメッセージを示すスクリーンショット。](assets/images/copilot/api-based-me-ttk-api-me-debug.png)
[ ローカル デバッグ] を選択して、プロジェクトをプレビューします。
スキャフォールディングが完了したら、Visual Studio Code の [エクスプローラー] の下にあるプロジェクト ディレクトリとファイルを表示します。
| フォルダー名 | コンテンツ |
|---|---|
env/.env.dev.user |
プロビジョニングとデプロイの規則をカスタマイズするために teamsapp.yml によって使用されるローカル環境の構成ファイル。 |
appPackage |
アプリ マニフェスト テンプレート ファイルとアプリ アイコン (color.png と outline.png)。 |
appPackage/manifest.json |
ローカルおよびリモートの環境でアプリを実行するためのアプリ マニフェスト。 |
appPackage/apiSpecificationFiles/openapi.yml |
OpenAPI Description の API の構造と構文を含む記述ファイル。 |
appPackage/responseTemplates |
アダプティブ カード テンプレート、プレビュー カード テンプレート、メタデータで構成される応答レンダリング テンプレート。 |
teamsapp.yml |
これは、プロパティと構成ステージ定義を定義する teams Toolkit プロジェクトメインです。 |
ヒント
Teams 内に最初のボットを統合する前に、Teams 外のボットについて理解しておいてください。
アプリをプロビジョニングする
Azure でアプリをプロビジョニングするには:
Teams Toolkit に移動し、左側のウィンドウで [ 実行とデバッグ ] を選択します (Ctrl + Shift + D)。
[起動構成] ドロップダウンから [ Teams でリモートの起動 (Edge)] を選択します。
Teams ツールキットは、Azure でアプリをプロビジョニングし、それを Teams にデプロイします。
注:
初めてアプリをプロビジョニングするときは、完了するまで数分かかります。 以降のプロビジョニングの方が高速です。
チャット メッセージに移動し、[ アクションとアプリ ] アイコンを選択します。 ポップアップ メニューで、アプリを検索します。
一覧からアプリを選択し、 新規作成メッセージ領域から検索コマンドをトリガーします。
Teams は、チャット メッセージのアダプティブ カードとして検索結果を送信します。
課題の完了
このようなものを思いついたのですか?
おめでとうございます!
達成しました! API ベースのメッセージ拡張機能を作成しました。
このセクションに問題がある場合 このセクションを改善できるよう、フィードバックをお送りください。
Platform Docs