アプリマニフェストをカスタマイズする

2025-05-20

アプリマニフェスト (以前は Teams アプリマニフェスト) では、アプリをMicrosoft Teamsに統合する方法について説明します。スキャフォールディング後、既定のアプリマニフェストファイルは appPackage/manifest.jsonで使用できます。アプリマニフェストファイルには、 ${{XX_XX}}形式の環境変数がいくつか含まれており、実際の値は、Microsoft 365 Agents Toolkit (以前は Teams Toolkit と呼ばれます) と、 env/.env.dev や env/.env.localなどの env ファイルを使用して解決されます。

実際のコンテンツでアプリマニフェストをプレビューするために、Agent Toolkit は、次のフォルダー構造に示すように、 appPackage/build フォルダーの下にプレビューアプリマニフェストファイルを生成します。

└───appPackage
    └───build
        ├───appPackage.{env}.zip - Zipped app package of remote Teams app
        ├───appPackage.local.zip - Zipped app package of local Teams app
        ├───manifest.{env}.json  - Previewed manifest of remote Teams app
        └───manifest.local.json  - Previewed manifest of local Teams app

アプリマニフェストファイルは、ローカル環境とリモート環境でプレビューできます。

ローカル環境でアプリマニフェストファイルをプレビューする

ローカル環境でアプリマニフェストファイルをプレビューするには、F5 キーを選択してローカルデバッグを実行します。 env/.env.localで環境変数を生成すると、アプリパッケージとプレビューアプリマニフェストが appPackage/build フォルダーの下に構築されます。

また、ツリービューまたは Teams から Zip Teams アプリパッケージ をトリガーすることも、コマンドパレットから Zip Teams アプリパッケージ をトリガーして、プレビューアプリマニフェストとアプリパッケージを生成することもできます。

Zip Teams アプリパッケージの選択を示すスクリーンショット。

リモート環境でアプリマニフェストファイルをプレビューする

リモート環境でアプリマニフェストファイルをプレビューするには、ツリービューから プロビジョニング をトリガーするか、コマンドパレットから Teams: プロビジョニング をトリガーできます。これは、リモート Teams アプリの環境変数を生成し、アプリパッケージをビルドし、 appPackage/build フォルダーの下にプレビューアプリマニフェストを生成します。

Teams アプリパッケージを圧縮するオプションを示すスクリーンショット。

Visual Studio Code でアプリマニフェストをカスタマイズする

ローカルデバッグまたはプロビジョニング中、Agents Toolkit は appPackage/manifest.json からアプリマニフェストを読み込み、 env/.env.xxで定義された環境変数によってアプリマニフェストを解決してから、 Teams 用開発者ポータルで Teams アプリを作成または更新します。

m365agents.ymlとm365agents.local.ymlで独自のmanifest.json ファイルを定義できます。たとえば、manifest.json ファイルを test/test.json に配置し、yaml ファイル内の manifestPath パラメーターを更新できます。

- uses: teamsApp/zipAppPackage # Build Teams app package with latest env value
  with:
  manifestPath: ./test/test.json # Path to manifest template
  outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
  outputJsonPath: ./appPackage/build/manifest.${{TEAMSFX_ENV}}.json

独自の環境変数を定義できます。既定のmanifest.jsonには、${{xx_xx}} の形式のプレースホルダーがいくつか含まれています。独自の環境変数を定義し、manifest.json ファイルにプレースホルダーを追加できます。たとえば、env/.env.xx ファイルに新しい環境変数を定義してアプリの説明をカスタマイズし、対応するプレースホルダーでmanifest.jsonを更新できます。

.env.dev
```
TEAMS_APP_DESCRIPTION=This is an amazing app
```
manifest.json
```
 {
     "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
     "manifestVersion": "1.17",
     "description": {
         "short": "${{TEAMS_APP_DESCRIPTION}}",
         "full": "Full description of tab0418"
     },
 }
```
Agents Toolkit 5.10 以降では、 file 関数を使用して、長いアプリの説明や複数行のアプリの説明などのフィールドの値を別のテキストファイルに格納できます。たとえば、manifest.jsonの親フォルダーにdescription.txt ファイルを作成して、アプリの完全な説明を格納します。次に、manifest.jsonの description.full の値を $[file('description.txt')] として設定します。 Agents Toolkit は、テキストファイルからコンテンツを読み取り、アプリパッケージをビルドするときに完全な説明として使用します。

description.txt
```
 This is the full description.
```
manifest.json
```
 {
     "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
     "manifestVersion": "1.17",
     "description": {
         "short": "Short description of tab",
         "full": "$[file('./description.txt')]"
     },
 }
```
env/.env.xxにファイルパスを追加することもできます。次に、 file() のパラメーターを ${{xx_xx}} 形式のプレースホルダーに変更します。

.env.dev
```
 DESCRIPTION_PATH=./description.txt
```
manifest.json
```
{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
    "manifestVersion": "1.17",
    "description": {
        "short": "Short description of tab",
        "full": "$[file(${{DESCRIPTION_PATH}})]"
    },
}
```

アプリを検証する

カスタマイズ後に、アプリマニフェストまたはアプリパッケージを検証できます。ツリービューから [アプリケーションの検証] をトリガーするか、コマンドパレットから [Teams: アプリケーションの検証] を トリガーできます。 マニフェストスキーマを使用して検証するか、検証規則を使用してアプリパッケージを検証するかの 2 つのオプションがあります。

ユーティリティの下の検証アプリケーションの選択を示すスクリーンショット。

アプリマニフェストスキーマを使用して検証する

このオプションは、環境変数を使用して appPackage/manifest.json をレンダリングし、そのスキーマを使用してアプリマニフェストを検証します。

マニフェストスキーマを使用した検証の選択を示すスクリーンショット。

または、次の Microsoft 365 Agents Toolkit コマンドラインインターフェイス (以前は Teams Toolkit CLI と呼ばれる) コマンドを使用します。

atk validate --manifest-path <YOUR-PATH-TO-MANIFEST>

MissingEnvironmentVariablesErrorを満たしている場合は、エージェントツールキットで定義されている対応する環境変数がmanifest.jsonで見つからないことを意味します。 プロビジョニングを実行するか、F5 を選択して環境変数を生成するか、値を満たすためにファイル.env.xx手動で更新する必要があります。

不足している環境変数エラーを示すスクリーンショット。

検証規則を使用してアプリパッケージを検証する

このオプションは、検証規則を使用して zip 形式のアプリパッケージを検証します。

検証ルールを使用したアプリパッケージの検証の選択を示すスクリーンショット。

または、次の Agents Toolkit CLI コマンドを使用します。

atk validate --app-package-file-path <YOUR-PATH-TO-APP-PACKAGE>

アプリマニフェストスキーマ以外の検証規則があります。たとえば、静的タブセクションに entityId conversations と名前がある場合、次のエラーが表示されます。

Teams アプリを更新する

アプリマニフェストファイルをプレビューして検証したら、コマンドパレットから Teams : Update Teams App コマンドをトリガーすることで、ローカルの変更を Teams 開発者ポータルに同期できます。

Teams 更新チームアプリの選択を示すスクリーンショット。

または、次の Agents Toolkit CLI コマンドを使用します。

atk update teams-app

注:

変更は開発者ポータルに反映されます。開発者ポータルの手動更新は上書きされます。
発行されたアプリの名前を変更するには、 local.manifest ファイルと manifest.json ファイルの両方を変更する必要があります。

構成ファイルの変更またはテンプレートの変更が原因でアプリマニフェストファイルが古くなっている場合は、次のいずれかのアクションを選択します。

プレビューのみ: ローカルアプリマニフェストファイルは、現在の構成に従って上書きされます。
プレビューと更新: ローカルアプリマニフェストファイルは現在の構成に従って上書きされ、Teams プラットフォームにも更新されます。
キャンセル: アクションは実行されません。

ローカル環境と開発環境の値をプレビューするには

appPackage/manifest.jsonで、CodeLens に移動して、local環境とdev環境の値をプレビューできます。

CodeLens v5 を示すスクリーンショット。

注:

環境をプロビジョニングするか、ローカルデバッグを実行して環境変数を生成します。

[CodeLens] を選択すると、 .env ファイルに移動できます。これにより、すべての環境名を含むドロップダウンリストが表示されます。環境を選択すると、対応する .env ファイルが開きます。

開発環境の選択を示すスクリーンショット。

すべての環境の値をプレビューするには、プレースホルダーにカーソルを合わせます。環境名と対応する値の一覧が表示されます。環境をプロビジョニングしなかった場合やローカルデバッグを実行しなかった場合は、環境変数が存在しない可能性があります。プレースホルダー値を表示するには、アプリをローカルでプロビジョニングまたはデバッグします。

マウスポインターを合わせると、環境名と対応する値を含むリストが表示されるプレースホルダーを示すスクリーンショット。

次の方法で共有

アプリ マニフェストをカスタマイズする

ローカル環境でアプリ マニフェスト ファイルをプレビューする

リモート環境でアプリ マニフェスト ファイルをプレビューする

Visual Studio Code でアプリ マニフェストをカスタマイズする

アプリを検証する

アプリ マニフェスト スキーマを使用して検証する

検証規則を使用してアプリ パッケージを検証する