API ベースのメッセージ拡張機能 - チュートリアル - Teams

注:

API ベースのメッセージ拡張機能では、検索コマンドのみがサポートされます。
API ベースのメッセージ拡張機能は、パブリック開発者プレビューでのみ使用できます。

API (API ベース) を使用して構築されたメッセージ拡張機能は、外部サービスと対話できるようにすることで、Teams アプリの機能を大幅に強化します。 API ベースのメッセージ拡張機能は、さまざまなアプリケーションを切り替える必要性を減らすことでワークフローを合理化するのに役立ちます。

API ベースのメッセージ拡張機能を使用して、ビジネスワークフローでよく使用される外部サービスを統合できます。たとえば、顧客管理に CRM システムを頻繁に使用するビジネスでは、メッセージ拡張機能を使用して Teams から顧客データを直接取得して表示できます。このアプリは、時間を節約するのに役立ち、異なるアプリケーションを切り替える必要性を減らすことによって効率を向上させます。この機能は、デスクトップ、Web、モバイルなど、Teams が利用できるすべてのプラットフォームでサポートされています。

前提条件

残り 16 分

アプリをビルドして展開するために必要なツールの一覧を次に示します。

インストール	使用するには...
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 説明ドキュメントを作成する

残り 15 分

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] で、一覧から最初の製品をコピーし、後で参照するために保存します。

応答レンダリングテンプレートを作成する

残り 10 分

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

アダプティブカードによって生成されたがサンプルデータにバインドされているかどうかを確認するには、次の手順に従います。
1. アダプティブカード Designerに移動します。
2. [ホストアプリの選択] に移動し、ドロップダウンから [Microsoft Teams] を選択します。
3. カードペイロードエディターに移動し、アダプティブカードテンプレートコードを貼り付けます。
4. サンプルデータエディターに移動し、先ほど保存した GET API 応答を貼り付けます。
5. [ プレビューモード] を選択します。アダプティブカードデザイナーは、応答をテンプレートにバインドするデータを含むアダプティブカードを表示します。

プレビューカードテンプレートを作成する

プレビューカードテンプレートには、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/vDevPreview/MicrosoftTeams.ResponseRenderingTemplate.schema.jsonでホストされているスキーマに準拠している必要があります。

応答レンダリングテンプレートを作成するには、次の手順に従います。

JSON ファイルを作成し、次のコードをファイルに追加します。

{ 
  "version": "1.0.0", 
  "$schema": "<URL_REFERENCE_TO_SCHEMA>", 
  "jsonPath": "", 
  "responseLayout": "", 
  "responseCardTemplate": { 
 },
 "previewCardTemplate": {
     }
 }

応答レンダリングテンプレートのプロパティを次のように更新します。
1. "version": "1.0.0"
2. "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
3. "jsonPath": "tools"
  
  jsonPath は、応答 JSON 応答の 1 つ以上の結果へのパスです。 API 応答の製品リストから関連するデータ/配列に jsonPath を追加します。この場合、 jsonPath はツールです。 JSON パスを決定する方法の詳細については、「JSON パスを使用した JSON のクエリ」を参照してください。
4. "responseLayout": "list"
  
  responseLayout は、添付ファイルのレイアウトを指定します。型の結果の応答に使用されます。サポートされている型は、リストとグリッドです。応答本文に、テキスト、タイトル、画像などの複数の要素を持つオブジェクトが含まれている場合は、応答レイアウトを list に設定する必要があります。 API 応答に画像またはサムネイルのみが含まれている場合は、応答レイアウトを grid に設定する必要があります。
5. "responseCardTemplate": 前に保存したアダプティブカードテンプレートコードを貼り付けます。
  
  responseCardTemplate は、JSON 応答をアダプティブカードにマップするアダプティブカードテンプレートです。
6. "previewCardTemplate": 前に保存したプレビューカードテンプレートコードを貼り付けます。
  
  previewCardTemplateは、メッセージ拡張機能のポップアップで結果のプレビューを表示するためにテンプレートが使用されるプレビューカードです。
応答レンダリングテンプレートは、OpenAPI Description ドキュメントを保存したのと同じフォルダーに保存します。

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

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

{
        "version": "devPreview",
        "jsonPath": "tools",
        "responseLayout": "list",
        "responseCardTemplate": {
    "$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. 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')}",
    } 
    }

アプリマニフェストを作成する

残り 5 分

次に、アプリマニフェスト (以前は Teams アプリマニフェストと呼ばれる) を作成する必要があります。アプリマニフェストでは、アプリがMicrosoft Teams製品に統合される方法について説明します。

Teams アプリマニフェストを作成する

マニフェストを作成するには、次の手順に従います。

新しい JSON ファイルを作成します。アプリマニフェストは、パブリック開発者プレビューアプリマニフェストスキーマで定義されているスキーマに準拠している必要があります。

JSON ファイルに次のコードを追加します。

アプリマニフェスト

{
 "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
 "manifestVersion": "devPreview",
 "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 にアップロードする

残り 2 分

Teams テスト環境にサインインして、Teams でアプリをテストします。 Teams でカスタムアプリをアップロードするには、次の手順に従います。

[Microsoft Teams] に移動し、テストテナントの資格情報を使用してサインインします。
[アプリ>アプリの管理>アプリのアップロード] に移動します。
[ カスタマイズされたアプリのアップロード] を選択します。
作成した zip ファイルを選択し、[ 開く] を選択します。
[追加] を選択します。アプリが Teams に追加されます。
チャットに移動し、メッセージ作成領域から [ + ] を選択し、アプリを検索します。
アプリを選択し、検索クエリを作成します。
アプリは、チャットウィンドウでアダプティブカードで応答します。
[送信] を選びます。

おめでとうございます!

100% 完了しました

達成しました! OpenAPI Description ドキュメントを使用して API ベースのメッセージ拡張機能を作成する方法について学習しました。

次の方法で共有

API ベースのメッセージ拡張機能を構築するための高度なチュートリアル

前提条件

Teams 開発テナントを設定する

カスタムアプリのアップロードオプションを確認する

無料の Teams 開発者テナントを作成する (省略可能)

無料の Azure アカウントを取得します。

OpenAPI 説明ドキュメントを作成する

OpenAPI の説明

応答レンダリングテンプレートを作成する

アダプティブカードテンプレート

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

アプリマニフェストを作成する

Teams アプリマニフェストを作成する

カスタムアプリを Teams にアップロードする

おめでとうございます!

次の方法で共有

API ベースのメッセージ拡張機能を構築するための高度なチュートリアル

前提条件

Teams 開発テナントを設定する

カスタム アプリのアップロード オプションを確認する

無料の Teams 開発者テナントを作成する (省略可能)

無料の Azure アカウントを取得します。

OpenAPI 説明ドキュメントを作成する

OpenAPI の説明

応答レンダリング テンプレートを作成する

アダプティブ カード テンプレート

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

アプリ マニフェストを作成する

Teams アプリ マニフェストを作成する

カスタム アプリを Teams にアップロードする

おめでとうございます!

カスタムアプリのアップロードオプションを確認する

応答レンダリングテンプレートを作成する

アダプティブカードテンプレート

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

アプリマニフェストを作成する

Teams アプリマニフェストを作成する

カスタムアプリを Teams にアップロードする