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

[アーティクル]
04/13/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/vDevPreview/MicrosoftTeams.schema.json",
+  "manifestVersion": "devPreview",
"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": "96270b0f-7298-40cc-b333-152f84321813"
+        }
+      },
+      "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 ベースのメッセージ拡張機能に認証を実装して、アプリケーションへの安全でシームレスなアクセスを提供できます。メッセージ拡張機能で認証が必要な場合は、アプリマニフェストでの下composeExtensionsにプロパティを追加authorizationし、でプロパティauthorizationを設定して、アプリケーションの認証の種類をauthType定義します。メッセージ拡張機能の認証を有効にするには、次のいずれかの認証方法でアプリマニフェストを更新します。

なし

メッセージ拡張機能でユーザーが API にアクセスするための認証を必要としない場合は、API ベースのメッセージ拡張機能での値authorizationとして更新noneできます。

    "authorization": {
      "authType": "none"
      }
    },

シークレットサービス認証

API シークレットサービス認証は、アプリが API で認証するためのセキュリティで保護された方法です。開発者ポータル for Teams を使用して API キーを登録し、API キー登録 ID を生成できます。プロパティを持つオブジェクトでapiSecretServiceAuthConfigurationアプリマニフェストをapiSecretRegistrationId更新します。このプロパティには、ポータルを介して API キーを送信したときに返される参照 ID が含まれている必要があります。

API 要求が開始されると、システムはセキュリティで保護されたストレージの場所から API キーを取得し、ベアラートークンスキームを使用して承認ヘッダーに含めます。 API エンドポイントは、要求を受け取ると、API キーの有効性を検証します。検証が成功した場合、エンドポイントは要求を処理し、必要な応答を返します。認証された要求のみが API のリソースへのアクセスを受け取ります。

API キーを登録する

API キーの登録を使用すると、認証の背後にある API をセキュリティで保護し、メッセージ拡張機能で使用できます。 API キーを登録し、API にアクセスできるドメイン、テナント、アプリを指定し、API 呼び出しを認証するために必要なシークレットを提供できます。その後、簡略化されたメッセージ拡張機能に API キー ID を貼り付け、API キー ID を使用すると、認証の背後にある API 呼び出しの認証が有効になります。

API キーを登録するには、次の手順に従います。

[ツールAPI キーの登録] > に移動します。
[ + 新しい API キー] を選択します。
[ API キーの登録 ] ページの [ API キーの登録] で、次の情報を更新します。
1. 説明: API キーの説明。
2. ドメインの追加: API エンドポイントのベースパスを更新します。パスはセキュリティで保護された HTTPS URL である必要があり、完全修飾ドメイン名を含め、必要に応じて特定のパスを含めることができます。たとえば、「 https://api.yelp.com 」のように入力します。

[ ターゲットテナントの設定] で、次のいずれかを選択します。

Home tenent
任意のテナント

オプション	いつ使用するか	説明
ホームテナント	テナントでアプリを開発し、組織用に構築されたカスタムアプリまたはカスタムアプリとしてアプリをテストする場合。	API キーは、API が登録されているテナント内でのみ使用できます。
任意のテナント	アプリのテストを完了し、異なるテナント間でアプリを有効にした後。パートナーセンターにアプリパッケージを送信する前に、ターゲットテナントを [任意のテナント ] に更新してください。	API キーは、アプリが Teams ストアで使用できるようになった後、他のテナントで使用できます。

[Teams 用開発者ポータルでターゲットテナントの設定] 見出しの下にある [ホームテナント] と [任意のテナント] オプションを示すスクリーンショット。

[ Teams アプリの設定] で、次のいずれかを選択します。

任意の Teams アプリ
既存の Teams アプリ ID

オプション	いつ使用するか	説明
任意の Teams アプリ	テナントでアプリを開発し、組織用に構築されたカスタムアプリまたはカスタムアプリとしてアプリをテストする場合。	API キーは、任意の Teams アプリで使用できます。これは、組織用に構築されたカスタムアプリまたはカスタムアプリに、アプリのアップロード後に ID が生成される場合に便利です。
既存の Teams アプリ ID	組織用に構築されたカスタムアプリまたはカスタムアプリとしてテナント内のアプリのテストを完了した後。API キーの登録を更新し、[ 既存の Teams アプリ ] を選択し、アプリのマニフェスト ID を入力します。	[既存の Teams アプリ] オプションは、API シークレットの登録を特定の Teams アプリにバインドします。

[Teams 用開発者ポータルで Teams アプリの設定] 見出しの下にある [Any Teams アプリ] と [既存の Teams アプリ] オプションを示すスクリーンショット。

[ + シークレットの追加] を選択します。 [ API キーの追加] ダイアログが表示されます。
シークレットの値を入力し、[保存] を選択 します。
注:
- API キーの登録ごとに最大 2 つのシークレットを保持できます。 1 つのキーが侵害された場合は、すぐに削除でき、Teams が 2 番目のキーに切り替えることができます。
- シークレット値には、少なくとも 10 文字、最大 128 文字が必要です。
- 最初のキーで 401 エラーが発生した場合、Teams は自動的に 2 番目のキーの使用を試みます。これは、ユーザーの中断のないサービスに役立ち、新しいシークレットの作成中に潜在的なダウンタイムを排除します。

API キー登録 ID が生成されます。

スクリーンショットは、開発者ポータル for Teams で生成された API キー登録 ID を示しています。

API キー登録 ID をコピーして保存し、アプリマニフェストのプロパティの apiSecretRegistrationId 値として更新します。

アプリマニフェストの更新

静的 API キーを構成することで、サービスへの受信要求を承認できます。 API キーは安全に格納され、API 呼び出しに追加されます。 Teams の apiSecretServiceAuthConfiguration 開発者ポータルを apiSecretRegistrationId 使用して API キーを送信するときに参照 ID を含むプロパティを持つオブジェクトを追加します。詳細については、「composeExtensions.commands」を参照してください。

"composeExtensions": [
    {
      "composeExtensionType": "apiBased",
      "authorization": {
        "authType": "apiSecretServiceAuth",
        "apiSecretServiceAuthConfiguration": {
            "apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
        }
      },

Microsoft Entra

microsoftEntra 認証方法では、アプリユーザーの Teams ID を使用して、アプリへのアクセスを提供します。 Teams にサインインしたユーザーは、Teams 環境内のアプリに再度サインインする必要はありません。アプリユーザーからの同意のみが必要な場合、Teams アプリはユーザーのアクセスの詳細をMicrosoft Entra IDから取得します。アプリユーザーは同意した後、もう一度検証しなくても、他のデバイスからでもアプリにアクセスできます。

前提条件

開始する前に、次のことを確認してください。

アクティブなサブスクリプションを持つ Azure アカウント。
Microsoft Entra IDと Teams アプリ開発に関する基本的な知識。

次の図は、Teams アプリユーザーが API bsed メッセージ拡張機能アプリへのアクセスを試みた場合の SSO のしくみを示しています。

ユーザーは、Teams のメッセージ拡張機能から API ベースのメッセージ拡張機能アプリを呼び出し、認証を必要とするコマンドを要求します。
アプリは、アプリ ID と必要なスコープ (access_as_user) を使用して、Teams バックエンドサービスに要求を送信します。
Teams バックエンドサービスは、ユーザーがアプリとスコープに同意したかどうかを確認します。そうでない場合は、ユーザーに同意画面が表示され、アクセス許可を求められます。
ユーザーが同意した場合、Teams バックエンドサービスはユーザーとアプリのアクセストークンを生成し、要求の承認ヘッダーでアプリに送信します。
アプリはトークンを検証します。ユーザーは、名前、電子メール、オブジェクト ID など、トークンからユーザー情報を抽出できます。
アプリはトークンを使用して独自の API を呼び出すことができます。
アプリは、Teams のユーザーに応答を返します。

API ベースのメッセージ拡張機能の認証方法を有効 microsoftEntra にするには、次の手順に従います。

Microsoft Entra IDで新しいアプリを登録する

Web ブラウザーで Azure portal を開きます。
[アプリの登録] アイコンを選択します。

[アプリの登録] ページが表示されます。
[+ 新しい登録] アイコンを選択します。

[アプリケーション登録] ページが表示されます。
アプリユーザーに表示するアプリの名前を入力します。必要に応じて、後の段階で名前を変更できます。

アプリにアクセスできるユーザーアカウントの種類を選択します。組織のディレクトリ内の単一または複数テナントのオプションから選択することも、個人の Microsoft アカウントにのみアクセスを制限することもできます。

サポートされているアカウントの種類のオプション

オプション	これを以下に選択します...
この組織のディレクトリ内のアカウントのみ (Microsoft のみ - シングルテナント)	テナント内のユーザー (またはゲスト) のみが使用するアプリケーションをビルドします。組織 (LOB アプリ) 用に構築されたカスタムアプリと呼ばれることがよくあります。このアプリは、Microsoft ID プラットフォームのシングルテナントアプリケーションです。
任意の組織ディレクトリ内のアカウント (任意のMicrosoft Entra ID テナント - マルチテナント)	任意のMicrosoft Entraテナントのユーザーがアプリケーションを使用できるようにします。このオプションは、たとえば、SaaS アプリケーションを構築していて、複数の組織で使用できるようにする場合に適しています。この種類のアプリは、Microsoft ID プラットフォームのマルチテナントアプリケーションと呼ばれます。
任意の組織ディレクトリ内のアカウント (任意のMicrosoft Entra ID テナント - マルチテナント) と個人用 Microsoft アカウント (Skype、Xbox など)	最も幅広い顧客のセットをターゲットにします。このオプションを選択すると、個人用 Microsoft アカウントを持つアプリユーザーをサポートできるマルチテナントアプリケーションを登録します。
個人用 Microsoft アカウントのみ	個人の Microsoft アカウントを持つユーザー専用のアプリケーションをビルドします。

注:

API ベースのメッセージ拡張アプリの SSO を有効にするために 、「リダイレクト URI」 と入力する必要はありません。

[登録] を選択します。アプリが作成されたことを示すメッセージがブラウザーに表示されます。

アプリ ID とその他の構成を含むページが表示されます。
アプリケーション (クライアント) ID からアプリ ID をメモして保存し、アプリマニフェストを後で更新します。

アプリはMicrosoft Entra IDに登録されています。これで、API ベースのメッセージ拡張アプリのアプリ ID が取得されました。

アクセストークンのスコープを構成する

新しいアプリの登録を作成したら、Teams クライアントにアクセストークンを送信するためのスコープ (アクセス許可) オプションを構成し、SSO を有効にするための信頼されたクライアントアプリケーションを承認します。

スコープを構成し、信頼されたクライアントアプリケーションを承認するには、次のものが必要です。

アプリケーション ID URI の追加: アプリのスコープ (アクセス許可) オプションを構成します。 Web API を公開し、アプリケーション ID URI を構成します。
API スコープの構成: API のスコープと、スコープに同意できるユーザーを定義します。管理者が高い特権のアクセス許可に対して同意を提供することのみを許可できます。
承認されたクライアントアプリケーションを構成する: 事前認証するアプリケーションの承認されたクライアント ID を作成します。これにより、アプリユーザーは、追加の同意を必要とせずに、構成したアプリスコープ (アクセス許可) にアクセスできます。アプリユーザーが同意を拒否する機会がないため、信頼できるクライアントアプリケーションのみを事前認証します。

アプリケーション ID

左側のウィンドウで [管理]>[API の公開] を選択します。

[API の公開] ページが表示されます。
[ 追加] を選択して、の形式 api://{AppID}でアプリケーション ID URI を生成します。

アプリケーション ID URI を設定するためのセクションが表示されます。

ここで説明する形式で アプリケーション ID URI を 入力します。

アプリケーション ID

アプリケーション ID URI には、形式api://{AppID}のアプリ ID (GUID) が事前に入力されています。
アプリケーション ID URI 形式はである必要があります。 api://fully-qualified-domain-name.com/{AppID}
fully-qualified-domain-name.com を api:// と {AppID} (つまり GUID) の間に挿入します。たとえば、api://example.com/{AppID} です。

重要

機密情報: アプリケーション ID URI は認証プロセスの一部としてログに記録され、機密情報を含めることはできません。
複数の機能を持つアプリのアプリケーション ID URI: API ベースのメッセージ拡張機能を構築する場合は、アプリケーション ID URI をとしてapi://fully-qualified-domain-name.com/{YourClientId}入力します。{YourClientId} は Microsoft Entra アプリ ID です。

ドメイン名の形式: ドメイン名には小文字を使用します。大文字を使用しないでください。

たとえば、リソース名を持つアプリサービスまたは Web アプリを作成するには、 demoapplication

使用される基本リソース名以下の場合	URL は次のようになります...	形式は以下でサポートされています...
demoapplication	`https://demoapplication.example.net`	すべてのプラットフォーム。
DemoApplication	`https://DemoApplication.example.net`	デスクトップ、Web、および iOS のみ。 Android ではサポートされていません。

小文字のオプション demoapplication を基本リソース名として使用します。

[保存] を選択します。

アプリケーション ID URI が更新されたことを示すメッセージがブラウザーに表示されます。

アプリケーション ID URI がページに表示されます。
アプリケーション ID URI をメモして保存して、アプリマニフェストを後で更新します。

API スコープを構成する

注:

API ベースのメッセージ拡張機能 では、access_as_user スコープのみがサポートされます。

[この API で定義されたスコープ] セクションで [+ スコープの追加] を選択します。

[スコープの追加] ページが表示されます。
スコープを構成するための詳細を入力します。
1. スコープ名を入力します。このフィールドは必須です。
2. このスコープに同意できるユーザーを選択します。既定のオプションは [管理者のみ] です。
3. 管理同意表示名を入力します。このフィールドは必須です。
4. 管理者の同意の説明を入力します。このフィールドは必須です。
5. [ユーザーの同意表示名] を入力します。
6. ユーザー同意の説明を入力します。
7. 状態の [有効] オプションを選択します。
8. [スコープの追加] を選択します。
スコープが追加されたことを示すメッセージがブラウザーに表示されます。

定義した新しいスコープがページに表示されます。

承認されたクライアントアプリケーションを構成する

[API の公開] ページを [承認済みクライアントアプリケーション] セクションに移動し、[+ クライアントアプリケーションの追加] を選択します。

[クライアントアプリケーションの追加] ページが表示されます。

アプリの Web アプリケーションに対して承認するアプリケーションに適した Microsoft 365 クライアント ID を入力します。

Azure portalのアプリにクライアントアプリケーションを追加するための [クライアント ID] オプションと [承認されたスコープ] オプションを示すスクリーンショット。クライアントアプリケーションを追加する

注:

Teams 用のモバイル、デスクトップ、および Web アプリケーション用の Microsoft 365 クライアント ID は、追加する必要がある実際の ID です。
Teams API ベースのメッセージ拡張機能アプリの場合は、Teams にモバイルまたはデスクトップクライアントアプリケーションを使用できないため、Web または SPA が必要です。

次のいずれかのクライアント ID を選択します。

クライアント ID を使用する	承認する場合...
1fec8e78-bce4-4aaf-ab1b-5451cc387264	Teams モバイルアプリケーションまたはデスクトップアプリケーション
5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Teams Web アプリケーション

公開した Web API にスコープを追加するには、[承認されたスコープ] でアプリ用に作成したアプリケーション ID URI を選択します。
[アプリケーションの追加] を選択します。

承認されたクライアントアプリが追加されたことを示すメッセージがブラウザーに表示されます。

承認されたアプリのクライアント ID がページに表示されます。

注:

複数のクライアントアプリケーションを承認できます。承認された別のクライアントアプリケーションを構成するには、この手順の手順を繰り返します。

アプリのスコープ、アクセス許可、およびクライアントアプリケーションが正常に構成されました。アプリケーション ID URI をメモして保存してください。次に、アクセストークンのバージョンを構成します。

アプリマニフェストの更新

注:

webApplicationInfo は、アプリマニフェストバージョン 1.5 以降でサポートされています。

アプリマニフェストファイルで次のプロパティを更新します。

webApplicationInfo: アプリの SSO を有効にして、アプリユーザーが API ベースのメッセージ拡張機能アプリにシームレスにアクセスできるようにします。セクション。アプリに関する重要な詳細が含まれています。 Microsoft Entra IDに登録したアプリケーション ID URI は、公開した API のスコープで構成されます。でアプリのサブドメイン URI を resource 構成して、を使用する getAuthToken() 認証要求がアプリマニフェストで指定されたドメインからのものであることを確認します。詳細については、「webApplicationInfo」を参照してください。
microsoftEntraConfiguration: アプリのシングルサインオン認証を有効にします。 SSO をsupportsSingleSignOntrueサポートし、複数の認証の必要性を軽減するようにプロパティを構成します。

アプリマニフェストを構成するには:

API ベースのメッセージ拡張アプリプロジェクトを開きます。
アプリマニフェストフォルダーを開きます。
注:
- アプリマニフェストフォルダーは、プロジェクトのルートにある必要があります。詳細については、「Microsoft Teams アプリパッケージを作成する」を参照してください。
- manifest.jsonを作成する方法の詳細については、アプリマニフェストスキーマに関するページを参照してください。
ファイルを manifest.json 開く
アプリマニフェストファイルに次のコードスニペットを追加します。

WebApplicationInfo
```
"webApplicationInfo":
{
"id": "{Microsoft Entra AppId}",
"resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
}
```
ここで、
- {Microsoft Entra AppId}は、Microsoft Entra IDでアプリを登録したときに作成したアプリ ID です。これは GUID です。
- subdomain.example.comは、Microsoft Entra IDでスコープを作成するときに登録したアプリケーション ID URI です。
MicrosoftEntraConfiguration
```
"authorization": {
  "authType": "microsoftEntra",
  “microsoftEntraConfiguration”: {
    “supportsSingleSignOn”: true
  }
},
```
次のプロパティでサブドメイン URL を更新します:
1. contentUrl
2. configurationUrl
アプリマニフェストファイルを保存します。

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

トークンの認証

メッセージ拡張機能は、認証中に API を呼び出すと、ユーザーの認証トークン (AED トークン) を使用して要求を受け取ります。メッセージ拡張機能は、送信 HTTP 要求の承認ヘッダーにトークンを追加します。ヘッダー形式はです Authorization: Bearer <token_value>。たとえば、メッセージ拡張機能が認証を必要とするサービスに対して API 呼び出しを行う場合などです。この拡張機能は、次のように HTTP 要求を構築します。

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

API ベースのメッセージ拡張機能がトークンを含む要求ヘッダーを取得したら、次の手順を実行します。

認証: 対象ユーザー、スコープ、発行者、署名要求のトークンを確認して、トークンがアプリ用の場合はチェックします。

ヘッダーと応答を持つ JSON Web トークン (JWT) の例を次に示します。

トークン V2
トークン V1

{
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "00000002-0000-0000-c000-000000000000",
  "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
  "iat": 1712509315,
  "nbf": 1712509315,
  "exp": 1712513961,
  "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=",
  "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
  "azpacr": "0",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "preferred_username": "john.doe@contoso.com",
  "rh": "I",
  "scp": "access_as_user",
  "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "h7DMQwSPAEeiEe62JJUGAA",
  "ver": "2.0"
  }

{
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "api://00000002-0000-0000-c000-000000000000",
  "iss": "https://sts.windows.net/{tenantid}/",
  "iat": 1537231048,
  "nbf": 1537231048,
  "exp": 1537234948,
  "acr": "1",
  "aio": "AXQAi/8IAAAA",
  "amr": ["pwd"],
  "appid": "c44b4083-3bb0-49c1-b47d-974e53cbdf3c",
  "appidacr": "0",
  "ipaddr": "192.168.1.1",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "scp": "access_as_user",
  "sub": "AAAAAAAAAAAAAAAAAAAAAIkzqFVrSaSaFHy782bbtaQ",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "fqiBqXLPj0eQa82S-IYFAA",
  }

トークンを使用する: 名前、電子メール、オブジェクト ID などのユーザー情報をトークンから抽出し、トークンを使用してメッセージ拡張アプリの独自の API を呼び出します。

注:

API は、Azure portalに登録されているスコープがにaccess_as_user設定されたMicrosoft Entra トークンを受け取ります。ただし、トークンは、Microsoft Graph などの他のダウンストリーム API を呼び出す権限がありません。

トラブルシューティング

アプリをチームにアップロードするときに マニフェストの解析に失敗した エラーメッセージが表示される場合は、 Teams アプリ検証ツールを使用して、アプリマニフェストや OpenAPI 仕様ファイルなど、アプリパッケージを検証します。アプリマニフェストと OpenAPI Description ドキュメントの要件を確認して、エラーや警告を解決し、アプリのアップロードを試してください。
Teams でアプリの実行中に問題が発生した場合は、次のトラブルシューティング手順を使用して問題を特定して解決します。
- ネットワーク: ネットワーク アクティビティを検査するには、開発者ツールの [ネットワーク] タブを選択します
  1. Teams Web クライアントを開きます。
  2. Microsoft 365 資格情報でサインインします。
  3. チャットに移動し、メッセージ拡張機能アプリを実行します。
  4. 右上の [設定など] (...) を選択します。[その他のツール>開発者ツール] に移動します。
  5. [ネットワーク] を選択します。 フィルター オプションを選択し、検索フィールドに「invoke」と入力します。
  6. 一覧からエラーを選択します。
  7. 右側のウィンドウで、[ 応答 ] タブを選択します。
  8. サービスまたは API からのエラー応答を表す JSON オブジェクトが表示されます。これには、standardizedErrorおよび errorDescriptionのオブジェクトが含まれています。このオブジェクトerrorCodeerrorSubCodeには、エラーに関する詳細が含まれています。
  一般的な HTTP エラー応答:
  - 要求パラメーターが見つからないか、正しく書式設定されていない場合は、400 の不適切な要求エラーが発生する可能性があります。
  - 401 未承認または 403 禁止エラーは、API キーの欠落や未承認など、API キーに関する問題を示しています。
  - 500 内部サーバーエラーは、サーバー側の問題が原因で、サービスが応答方法を知らないことを示します。
ツールのトラブルシューティング: ネットワークトレースからの情報が不足している場合は、OpenAPI の説明ドキュメントに従って要求を作成し、Swagger エディターや Postman などのツールを使用して、必要に応じて API キーの承認ヘッダーを含む要求をテストできます。

エラーを解決できない場合は、 Microsoft Teams 製品サポートにお問い合わせください。

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

パラメーター

パラメーター

Json パス

スキーママッピング

認証

API キーを登録する

アプリマニフェストの更新

前提条件

Microsoft Entra IDで新しいアプリを登録する

アクセストークンのスコープを構成する

アプリケーション ID

API スコープを構成する

承認されたクライアントアプリケーションを構成する

アプリマニフェストの更新

トークンの認証

トラブルシューティング

フィードバック

その他のリソース

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

パラメーター

パラメーター

Json パス

スキーマ マッピング

認証

API キーを登録する

アプリ マニフェストの更新

前提条件

Microsoft Entra IDで新しいアプリを登録する

アクセス トークンのスコープを構成する

アプリケーション ID

API スコープを構成する

承認されたクライアント アプリケーションを構成する

アプリ マニフェストの更新

トークンの認証

トラブルシューティング

フィードバック

その他のリソース

スキーママッピング

アプリマニフェストの更新

アクセストークンのスコープを構成する

承認されたクライアントアプリケーションを構成する

アプリマニフェストの更新