注:
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 である必要があります。
-
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}"
}
}
}
プレビュー カード
拡張アダプティブ カード
パラメーター
| プロパティ | 型 | 説明 | 必須 |
|---|---|---|---|
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、およびbooleanname: type: string example: doggieターゲット スキーマ:
Textblock{ "type": "TextBlock", "text": "name: ${if(name, name, 'N/A')}", "wrap": true }
array: 配列はアダプティブ カード内のコンテナーに変換されます。例
ソース スキーマ:
arraytype: 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: オブジェクトがアダプティブ カードの入れ子になったプロパティに変換されます。例
ソース スキーマ:
objectcomponents: 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 要素に変換されます。例
ソース スキーマ:
imageimage: 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) として選択します。
[追加] を選択します。
![アプリ名と、開発者ポータルで [最新のプレリリース (devPreview)] として選択されているマニフェスト バージョンを示すスクリーンショット。](../assets/images/copilot/api-based-me-tdp-manifest-version.png)
左側のウィンドウの [ 構成] で、次の 基本情報を更新します。
- フル ネーム
- 簡潔な説明
- 詳しい説明
- 開発者または会社名
- Web サイト (有効な HTTPS URL である必要があります)
- プライバシー ポリシー
- 使用条件
[保存] を選択します。
[ アプリ機能] を選択します。
[ メッセージ拡張機能] を選択します。
[ メッセージ拡張機能の種類] で、[API] を選択 します。
- Bot メッセージ拡張機能を読み取る免責事項 がユーザーによって既に使用されている場合。メッセージ拡張機能の種類を API に変更しますか?、 はい、変更を選択します。
[ OpenAPI spec]\(OpenAPI 仕様\) で、[ 今すぐアップロード] を選択します。
![開発者ポータルの [今すぐアップロード] オプションを示すスクリーンショット。](../assets/images/copilot/api-based-me-tdp-upload.png)
JSON または YAML 形式で OpenAPI Description ドキュメントを選択し、[ 開く] を選択します。
[保存] を選択します。 メッセージ API 仕様が正常に保存されたポップアップが表示されます。
[ 入手] を選択します。
![[正常に保存された API スペック] と [取得] ボタンの例を示すスクリーンショット。](../assets/images/copilot/api-based-me-tdp-api-saved.png)
![開発者ポータルの [今すぐアップロード] オプションを示すスクリーンショット。](../assets/images/copilot/api-based-me-tdp-upload.png#lightbox)
コマンドの追加
注:
API からビルドされたメッセージ拡張機能は、1 つのパラメーターのみをサポートします。
コマンドとパラメーターをメッセージ拡張機能に追加して、コマンドを追加できます。
[ メッセージ拡張機能の種類] で、[ 追加] を選択します。
[ コマンドの追加] ポップアップが表示され、OpenAPI Description ドキュメントから使用可能なすべての API の一覧が表示されます。
一覧から API を選択し、[ 次へ] を選択します。
![[コマンドの追加] ポップアップ ウィンドウの OpenAPI 説明ドキュメントの API の一覧を示すスクリーンショット。](../assets/images/copilot/api-based-me-tdp-commands-api-list.png)
[ 応答テンプレート] で、[ 今すぐアップロード] を選択します。
![コマンドのアダプティブ カード テンプレートを追加する [今すぐアップロード] オプションを示すスクリーンショット。](../assets/images/copilot/api-based-me-tdp-adaptive-card-template.png)
注:
複数の API がある場合は、各 API のアダプティブ カード応答テンプレートをアップロードしてください。
JSON 形式のアダプティブ カード応答テンプレート ファイルを選択し、[ 開く] を選択します。
アダプティブ カード テンプレートから次の属性が自動的に更新されます。
- コマンドの種類
- コマンド ID
- コマンドのタイトル
- パラメーター名
- パラメータの説明
[ 詳細] で、 コマンドの説明を更新します。
Microsoft 365 Copilotでトリガーを使用してコマンドを起動する場合は、[ユーザーが拡張機能を開いたときにこのコマンドを自動的に実行する] トグルをオンにします。
[追加] を選択します。 コマンドが正常に追加されました。
[保存] を選択します。
[ 認証と承認] で、次のいずれかのオプションを選択します。
- 認証なし (推奨されません)
- API キー
- OAuth
API ベースのメッセージ拡張機能が作成されます。
開発者ポータルで作成された API ベースのメッセージ拡張機能をテストするには、次の方法を使用します。
Teams でのプレビュー: メッセージ拡張機能を開き、右上隅 にある [Teams でプレビュー ] を選択します。 Teams にリダイレクトされ、アプリを Teams に追加してアプリをプレビューできます。
アプリ パッケージのダウンロード: メッセージ拡張機能ページで、左側のウィンドウで [ アプリ パッケージ ] を選択し、ウィンドウの左上隅にある [ アプリ パッケージのダウンロード] を選択します。 アプリ パッケージは、.zip ファイル内のローカル コンピューターにダウンロードされます。 アプリ パッケージをチームにアップロードし、メッセージ拡張機能をテストできます。
![[エージェント ツールキット for Visual Studio Code] に表示される Enter API キー コマンドを示すスクリーンショット。](../assets/images/copilot/api-based-me-ttk-api-key.png)
![Visual Studio の [Microsoft Teams アプリ] オプションを示すスクリーンショット。](../assets/images/copilot/api-based-me-vs-teams.png)
![Visual Studio の [エージェント ツールキット] の下の [クラウドでのプロビジョニング] オプションを示すスクリーンショット。](../assets/images/copilot/api-based-vs-provision-cloud.png)
![[プラス] アイコンから呼び出されたメッセージ拡張ポップアップ メニューと、ファイルされた検索に入力された MyTeamsApp の例を示すスクリーンショット。アプリが検索結果に表示されます。](../assets/images/copilot/api-based-me-vs-invoke-app.png)
複数パラメーター
複数パラメーターを使用すると、API ベースのメッセージ拡張機能でクエリ コマンドに対して複数の入力型を使用できます。 たとえば、ジャンル、レーティング、ステータス、日付でアニメを検索できます。
マニフェスト内のパラメーターの入力型、タイトル、説明、および必須フィールドを指定できます。
- パラメーター フィールドの
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"
}
],
ステップ バイ ステップのガイド
API ベースのメッセージ拡張機能を構築するには、次のステップ バイ ステップ ガイドに従います。
チュートリアル: API ベースのメッセージ拡張機能を構築する
注:
API ベースのメッセージ拡張機能では、検索コマンドのみがサポートされます。
API (API ベース) を使用して構築されたメッセージ拡張機能は、外部サービスと対話できるようにすることで、Teams アプリの機能を大幅に強化します。 API ベースのメッセージ拡張機能は、さまざまなアプリケーションを切り替える必要性を減らすことでワークフローを合理化するのに役立ちます。
API ベースのメッセージ拡張機能を使用して、ビジネス ワークフローでよく使用される外部サービスを統合できます。 たとえば、顧客管理に CRM システムを頻繁に使用するビジネスでは、メッセージ拡張機能を使用して Teams から顧客データを直接取得して表示できます。 このアプリは、時間を節約するのに役立ち、異なるアプリケーションを切り替える必要性を減らすことによって効率を向上させます。 この機能は、デスクトップ、Web、モバイルなど、Teams が利用できるすべてのプラットフォームでサポートされています。
前提条件
アプリをビルドして展開するために必要なツールの一覧を次に示します。
| インストール | 使用するには... |
|---|---|
| Microsoft Teams | Microsoft Teams、チャット、会議、通話のアプリを通じて作業するすべてのユーザーと共同作業を 1 か所で行うことができます。 |
| Microsoft Edge (推奨) または Google Chrome | 開発者ツールを備えたブラウザー。 |
| Visual Studio Code | JavaScript、TypeScript、または SharePoint Framework (SPFx) ビルド環境。 バージョン 1.55 以降を使用してください。 |
| Microsoft 365 開発者アカウント | アプリをインストールするための適切なアクセス許可を持つ Teams アカウントにアクセスします。 |
| Azure アカウント | Azure リソースへのアクセス。 |
| OpenAPI Description (OAD) ドキュメント | API の機能を説明するドキュメント。 詳細については、「 OpenAPI の説明」を参照してください。 |
Teams 開発テナントを設定する
テナント とは、チャット、ファイルの共有、会議の実行を行う Teams の組織のスペースまたはコンテナーのようなものです。 この領域は、カスタム アプリをアップロードしてテストする場所でもあります。 テナントを使って開発する準備ができているかどうかを確認しましょう。
カスタム アプリのアップロード オプションを確認する
アプリを作成したら、アプリを配布せずに Teams に読み込む必要があります。 このプロセスは、カスタム アプリのアップロードと呼ばれます。 このオプションを表示するには、Microsoft 365 アカウントにサインインします。
注:
Teams ローカル環境でアプリをプレビューおよびテストするために、カスタム アプリのアップロードが必要です。 有効になっていない場合は、Teams ローカル環境でアプリをプレビューしてテストすることはできません。
既にテナントがあり、管理者アクセス権がありますか? 実際にあるかどうかを確認しましょう。
Teams でカスタム アプリをアップロードできるかどうかを確認します。
Teams クライアントで、[ アプリ ] アイコンを選択します。
[アプリの管理] を選択します。
[ アプリのアップロード] を選択します。
[カスタム アプリのアップロード] オプションを探します。 オプションが表示された場合は、カスタム アプリのアップロードが有効になります。
注:
カスタム アプリをアップロードするオプションが見つからない場合は、Teams 管理者に問い合わせてください。
無料の Teams 開発者テナントを作成する (省略可能)
Teams 開発者アカウントをお持ちでない場合は、無料で取得できます。 Microsoft 365 開発者プログラムに参加します。
Microsoft 365 開発者プログラムに移動します。
[今すぐ参加] を選択し、画面の指示に従います。
ようこそ画面で、[E5 サブスクリプションの設定] を選択します。
管理者アカウントを設定します。 完了すると、次の画面が表示されます。
設定した管理者アカウントを使用して Teams にサインインします。 Teams に [カスタム アプリのアップロード] オプションがあることを確認します。
無料の Azure アカウントを取得します。
アプリをホストするか、Azureのリソースにアクセスする場合は、Azure サブスクリプションが必要です。 開始する前に無料でアカウントを作成してください。
アカウントを設定するためのツールがすべて揃っています。 次に、開発環境を設定し、ビルドを開始しましょう。 最初にビルドするアプリを選択します。
OpenAPI 説明ドキュメントを作成する
OpenAPI の説明
OpenAPI Description (OAD) は業界標準の仕様であり、OpenAPI ファイルの構造と概要について説明します。 これは、API を記述するための言語に依存しない、人間が判読できる形式です。 人間と機械の両方で読み書きが簡単です。 スキーマはマシンで読み取り可能であり、YAML または JSON のいずれかで表されます。
API を操作するには、OpenAPI 説明ドキュメントが必要です。 OpenAPI 説明ドキュメントは、次の条件を満たしている必要があります。
-
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, a search for "tool to create music" provides a list of 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.
注:
required: true プロパティが 1 つのパラメーターでのみ使用できることを確認します。 必要なパラメーターが複数ある場合は、必要なプロパティを更新して、他のパラメーターの required: false できます。
OpenAPI 説明ドキュメントが有効かどうかを検証できます。 確認するには、次の手順に従います。
Swagger/OpenAPI バリデーターに移動し、OpenAPI 説明ドキュメントを検証します。
OpenAPI 説明ドキュメントを保存します。
Swagger エディターに移動します。
左側のウィンドウで、エディターで OpenAPI の説明を貼り付けます。
右側のウィンドウで [GET] を選択 します。
[ 試してみる] を選択します。
検索パラメーターの値を Tool として入力して、音楽を作成します。
[ 実行] を選択します。 swagger エディターには、製品の一覧を含む応答が表示されます。
[サーバーの応答>Response Body] に移動します。
[
products] で、一覧から最初の製品をコピーし、後で参照するために保存します。
応答レンダリング テンプレートを作成する
OpenAPI Description ドキュメントでは、GET 要求または POST 要求に応答するために、アプリの応答レンダリング テンプレートが必要です。 応答レンダリング テンプレートは、アダプティブ カード テンプレート、プレビュー カード テンプレート、およびメタデータで構成されます。
アダプティブ カード テンプレート
アダプティブ カード テンプレートを作成するには、次の手順に従います。
ChatGPT に移動し、メッセージ作成領域で次のクエリを実行します。
Create an Adaptive Card Template that binds to the following response: "categories": [ "Music Generation", "AI Detection" ], "chatbot_short_url": "https://goto.opentools.ai/c/ai-music-generator", "main_summary": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.", "name": "AI Music Generator", "opentools_url": "https://goto.opentools.ai/ai-music-generator", "platforms": [ "Web", "App", "API" ][ メッセージの送信] を選択します。
ChatGPT は、サンプル データにバインドするアダプティブ カード テンプレートを使用して応答を生成します。 将来参照するためにアダプティブ カード テンプレートを保存します。
アダプティブ カード テンプレートの例を次に示します。
アダプティブ カード テンプレート
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "AI Music Generator",
"weight": "Bolder",
"size": "Large"
},
{
"type": "TextBlock",
"text": "Categories",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "Music Generation, AI Detection",
"wrap": true
},
{
"type": "TextBlock",
"text": "Description",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. AI Music Generator is powered by advanced AI technology, and it makes music production accessible to everyone.",
"wrap": true
},
{
"type": "TextBlock",
"text": "Platform",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "Web, App, API",
"wrap": true
}
],
"actions": [
{
"type": "Action.OpenUrl",
"title": "Learn More",
"url": "https://goto.opentools.ai/ai-music-generator"
},
{
"type": "Action.OpenUrl",
"title": "Try It",
"url": "https://goto.opentools.ai/c/ai-music-generator"
}
]
}
- アダプティブ カードによって生成されたがサンプル データにバインドされているかどうかを確認するには、次の手順に従います。
アダプティブ カード Designerに移動します。
[ホスト アプリの選択] に移動し、ドロップダウンから [Microsoft Teams] を選択します。
カード ペイロード エディターに移動し、アダプティブ カード テンプレート コードを貼り付けます。
サンプル データ エディターに移動し、先ほど保存した GET API 応答を貼り付けます。
[ プレビュー モード] を選択します。 アダプティブ カード デザイナーは、応答をテンプレートにバインドするデータを含むアダプティブ カードを表示します。
プレビュー カード テンプレートを作成する
プレビュー カード テンプレートには、title、subtitle、imageの各プロパティを含めることができます。 API 応答にイメージがない場合は、image プロパティを削除できます。
プレビュー カード テンプレートの例を次に示します。
プレビュー カード テンプレート
"previewCardTemplate": {
"title": "${if(name, name, 'N/A')}",
"subtitle": "$${if(price, price, 'N/A')}"
}
titleとsubtitleの if 条件を作成します。
- 名前が存在する場合、ボットは名前を使用します。
- 名前が存在しない場合、ボットは NA を使用します。
たとえば、「 "title": "Name: ${if(name, name, 'N/A')}" 」のように入力します。
プレビュー カード テンプレートを保存して、今後参照してください。
応答レンダリング テンプレート
応答レンダリング テンプレートは、 https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.jsonでホストされているスキーマに準拠している必要があります。
応答レンダリング テンプレートを作成するには、次の手順に従います。
JSON ファイルを作成し、次のコードをファイルに追加します。
{ "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json", "version": "1.0", "jsonPath": "", "responseLayout": "", "responseCardTemplate": { }, "previewCardTemplate": { } }応答レンダリング テンプレートのプロパティを次のように更新します。
"$schema":"https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json""version":"1.0"versionは、使用するレンダリング テンプレートのバージョンです"jsonPath":"tools"jsonPathは、応答 JSON 応答の 1 つ以上の結果へのパスです。 API 応答の製品リストから関連するデータ/配列にjsonPathを追加します。 この場合、jsonPathはツールです。 JSON パスを決定する方法の詳細については、「JSON パス を使用した JSON のクエリ」を参照してください。"responseLayout":"list"responseLayoutは、添付ファイルのレイアウトを指定します。 型の結果の応答に使用されます。 サポートされている型は、リストとグリッドです。 応答本文に、テキスト、タイトル、画像などの複数の要素を持つオブジェクトが含まれている場合は、応答レイアウトをlistに設定する必要があります。 API 応答に画像またはサムネイルのみが含まれている場合は、応答レイアウトをgridに設定する必要があります。"responseCardTemplate": 前に保存したアダプティブ カード テンプレート コードを貼り付けます。responseCardTemplateは、JSON 応答をアダプティブ カードにマップするアダプティブ カード テンプレートです。"previewCardTemplate": 前に保存したプレビュー カードテンプレート コードを貼り付けます。previewCardTemplateは、メッセージ拡張機能のポップアップで結果のプレビューを表示するためにテンプレートが使用されるプレビューカードです。
応答レンダリング テンプレートは、OpenAPI Description ドキュメントを保存したのと同じフォルダーに保存します。
次のコードは、応答レンダリング テンプレートの例です。
応答レンダリング テンプレート
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json",
"version": "1.0",
"jsonPath": "tools",
"responseLayout": "list",
"responseCardTemplate": {
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "AI Music Generator",
"weight": "Bolder",
"size": "Large"
},
{
"type": "TextBlock",
"text": "Categories",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "Music Generation, AI Detection",
"wrap": true
},
{
"type": "TextBlock",
"text": "Description",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
"wrap": true
},
{
"type": "TextBlock",
"text": "Platform",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "Web, App, API",
"wrap": true
}
],
"actions": [
{
"type": "Action.OpenUrl",
"title": "Learn More",
"url": "https://goto.opentools.ai/ai-music-generator"
},
{
"type": "Action.OpenUrl",
"title": "Try It",
"url": "https://goto.opentools.ai/c/ai-music-generator"
}
]
},
"previewCardTemplate": {
"title": "${if(name, name, 'N/A')}",
"subtitle": "$${if(price, price, 'N/A')}"
}
}
アプリ マニフェストを作成する
次に、アプリ マニフェスト (以前は Teams アプリ マニフェストと呼ばれる) を作成する必要があります。 アプリ マニフェストでは、アプリがMicrosoft Teams製品に統合される方法について説明します。
Teams アプリ マニフェストを作成する
マニフェストを作成するには、次の手順に従います。
新しい JSON ファイルを作成します。 アプリ マニフェストは、アプリ マニフェスト スキーマで定義されているスキーマの 1.20 バージョンに準拠している必要があります。
JSON ファイルに次のコードを追加します。
アプリ マニフェスト
{ "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.schema.json", "manifestVersion": "1.20", "version": "1.0.3", "id": "<<YOUR-MICROSOFT-APP-ID>>", "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": "Search ME API", "full": "Search ME API full" }, "description": { "short": "product app for testing API Message Extensions", "full": "product app for testing API Message Extensions" }, "accentColor": "#FFFFFF", "composeExtensions": [ { "composeExtensionType": "", "apiSpecificationFile": "", "commands": [ { "context": [ "compose" ], "type": "query", "title": "API for fetching Klarna.", "id": "", "parameters": [ { "name": "", "title": "", "description": "" } ], "description": "", "apiResponseRenderingTemplateFile": "" } ] } ], "permissions": [ "identity", "messageTeamMembers" ], "validDomains": [] }アプリ マニフェストのプロパティを次のように更新します。
-
<<YOUR-MICROSOFT-APP-ID>>をボットの Microsoft アプリ ID に置き換えます。 -
composeExtensionTypeの値をapiBasedに更新します。 -
apiSpecificationFileの値を OpenAPI Description ファイルのパスに更新します。 -
commands.idの値をsearchToolsに更新します。 -
commands.titleの値をSearch for AI Toolsに更新します。 -
commands.descriptionの値をSearch for AI Toolsに更新します。 -
parameters.nameの値をsearchに更新します。 パラメーターがない場合、値はクエリ パラメーターであるか、要求本文スキーマでプロパティを参照している場合はproperties.nameする必要があります。 - 応答レンダリング テンプレート ファイルのパスに
apiResponseRenderingTemplateFileを更新します。 -
validDomainsの値を、OpenAPI Description ファイルで定義されているservice URLエンドポイントに更新します。
-
OpenAPI 説明ドキュメントと応答レンダリング テンプレートを保存したのと同じフォルダーに Teams アプリ マニフェストを保存します。
- カラーイメージとアウトライン画像が必要です。 これらのイメージはフォルダーに含め、Teams アプリ マニフェストで参照する必要があります。
- フォルダーの内容を圧縮します。 zip ファイルには、次のファイルが含まれている必要があります。
- OpenAPI 説明ドキュメント
- 応答レンダリング テンプレート
- アプリ マニフェスト
- カラー アイコン
- アウトライン アイコン
カスタム アプリを Teams にアップロードする
Teams テスト環境にサインインして、Teams でアプリをテストします。 Teams でカスタム アプリをアップロードするには、次の手順に従います。
[Microsoft Teams] に移動し、テスト テナントの資格情報を使用してサインインします。
[アプリ>アプリの管理>アプリのアップロード] に移動します。
[ カスタマイズされたアプリのアップロード] を選択します。
作成した zip ファイルを選択し、[ 開く] を選択します。
[追加] を選択します。
![[追加] オプションが強調表示されているメッセージ拡張機能アプリのスクリーンショット。](../assets/images/copilot/api-me-sbs-add-app-teams.png)
[開く]を選択します。
![[開く] オプションが強調表示されているメッセージ拡張機能アプリのスクリーンショット。](../assets/images/copilot/api-me-open.png)
チャットに移動し、メッセージ作成領域から [ + ] を選択し、アプリを検索します。
アプリを選択し、検索クエリを作成します。
アプリは、チャット ウィンドウでアダプティブ カードで応答します。
[送信] を選びます。
おめでとうございます! 達成しました! OpenAPI Description ドキュメントを使用して API ベースのメッセージ拡張機能を作成する方法について学習しました。
関連項目
GitHub で Microsoft と共同作業する
このコンテンツのソースは GitHub にあります。そこで、issue や pull request を作成および確認することもできます。 詳細については、共同作成者ガイドを参照してください。
Platform Docs