クラウドリソースをプロビジョニングする

[アーティクル]
06/24/2024

TeamsFx は Azure と Microsoft 365 クラウドと統合されており、1 つのコマンドでアプリを Azure に配置できます。 TeamsFx は Azure Resource Manager (ARM) と統合され、アプリケーションでコードアプローチに必要な Azure リソースをプロビジョニングできます。

Microsoft Visual Studio Code で Microsoft Teams Toolkit を使用してプロビジョニングする

Teams Toolkit または TeamsFx CLI でプロビジョニングコマンドをトリガーして、アプリケーションのリソースを作成または更新できます。 provision コマンドの手順は、provision プロパティの下の teamsapp.yml ファイルで定義されます。ファイルを表示して、作成されるリソースを把握できます。

注:

Azure サービスでは、サブスクリプションにコストが発生します。コスト見積もりの詳細については、「価格計算ツール」を参照してください。

プロビジョニングアクション

次の一覧は、プロビジョニング用に設計されたアクションを示しています。

teamsApp/create

それが何であるか

Teams アプリ ID を格納する環境変数が空であるか、アプリ ID が Teams 開発者ポータルから見つからない場合、このアクションによって新しい Teams アプリが作成されます。

動作するリソース

Teams 開発者ポータルの Teams アプリ。

使用方法

  - uses: teamsApp/create
    with:
      # #required. Name of Teams app
      name: <your-preferred-app-name>
    # Write the information of created resources into environment file for the specified environment variable(s).
    writeToEnvironmentFile:
      # The id for Teams app
      teamsAppId: <your-preferred-env-var-name>

teamsApp/update

それが何であるか

Teams 開発者ポータルの既存の Teams アプリにアプリマニフェスト (以前は Teams アプリマニフェストと呼ばれる) を適用します。 manifest.json ファイル内のアプリ ID を使用して、更新する Teams アプリを決定します。

動作するリソース

Teams 開発者ポータルの Teams アプリ。

使用方法

- uses: teamsApp/update
    with:
      # Required. Relative path to the yaml file. This is the path for built zip file.
      appPackagePath: <path-to-teams-app-package-file>

teamsApp/validateManifest

それが何であるか

このアクションは、環境変数を使用してアプリマニフェストテンプレートをレンダリングし、そのスキーマを使用してアプリマニフェストファイルを検証します。

動作するリソース

該当なし

使用方法

  - uses: teamsApp/validate
    with:
      # Required. Relative path to the yaml file. Path to app manifest file
      manifestPath: <path-to-manifest-file>

teamsApp/validateAppPackage

それが何であるか

このアクションは、検証ルールを使用して Teams アプリパッケージを検証します。

動作するリソース

該当なし

使用方法

  - uses: teamsApp/validateAppPackage
    with:
      # Required. Relative path to the yaml file. This is the path for built zip file.
      appPackagePath: <path-to-teams-app-package-file>

teamsApp/zipAppPackage

それが何であるか

このアクションは、環境変数を含むアプリマニフェストテンプレートをレンダリングし、2 つのアイコンを含むアプリマニフェストファイルを zip ファイルに圧縮します。

動作するリソース

該当なし

使用方法

- uses: teamsApp/zipAppPackage
    with:
      # Required. Relative path to the yaml file. This is the path for app manifest file. Environment variables in manifest will be replaced before apply to Microsoft Entra app.
      manifestPath: <path-to-manifest-file>
      # Required. Relative path to the yaml file. This is the path for built zip file.
      outputZipPath: <path-to-generated-zip-file>
      # Required. Relative path to the yaml file. This is the path for built manifest json file.
      outputJsonPath: <path-to-generated-json-file>

teamsApp/publishAppPackage

それが何であるか

このアクションにより、ビルドされた Teams アプリ zip ファイルがテナントアプリカタログに発行されます。

動作するリソース

Microsoft 365 テナントアプリカタログの Teams アプリ。

使用方法

- uses: teamsApp/publishAppPackage
    with:
      # Required. Relative path to this file. This is the path for built zip file.
      appPackagePath: <path-to-teams-app-package>
    # Write the information of created resources into environment file for the specified environment variable(s).
    writeToEnvironmentFile:
      # The Teams app id in tenant app catalog.
      publishedAppId: <your-preferred-env-var-name>

aadApp/create

それが何であるか

このアクションにより、clientId を格納する環境変数が空の場合にユーザーを認証するための新しい Microsoft Entra アプリケーションが作成されます。

動作するリソース

Microsoft 365 テナントの Microsoft Entra ID。

使用方法

- uses: aadApp/create
    with:
      # Required. The Microsoft Entra app's display name. When you run aadApp/update, the Microsoft Entra app name will be updated based on the definition in manifest. If you don't want to change the name, make sure the name in Microsoft Entra app manifest is the same with the name defined here.
      name: <your-application-name>
      # Required. If the value is false, the action will not generate client secret for you
      generateClientSecret: true
      # Required. Specifies what Microsoft accounts are supported for the current application. Supported values are: `AzureADMyOrg`, `AzureADMultipleOrgs`, `AzureADandPersonalMicrosoftAccount`, `PersonalMicrosoftAccount`.
      signInAudience: "AzureADMyOrg"
    # Write the information of created resources into environment file for the specified environment variable(s).
    writeToEnvironmentFile:
      # Required. The client (application) ID of Microsoft Entra application. The action will refer the environment variable defined here to determine whether to create a new Microsoft Entra app.
      clientId: <your-preferred-env-var-name>
      # Required when `generateClientSecret` is `true`. The action will refer the environment variable defined here to determine whether to create a new client secret. It's recommended to add `SECRET_` prefix to the environment variable name so it will be stored to the .env.{envName}.user environment file.
      clientSecret: <your-preferred-env-var-name>
      # Required. The object ID of Microsoft Entra application
      objectId: <your-preferred-env-var-name>
      # Optional. The tenant ID of Microsoft Entra tenant
      tenantId: <your-preferred-env-var-name>
      # Optional. The Microsoft Entra authority
      authority: <your-preferred-env-var-name>
      # Optional. The host name of Microsoft Entra authority
      authorityHost: <your-preferred-env-var-name>

aadApp/update

それが何であるか

このアクションは、Microsoft Entra アプリマニフェストに基づいて Microsoft Entra アプリケーションを更新します。これは、Microsoft Entra アプリマニフェストの ID プロパティを参照して、更新する Microsoft Entra アプリを決定します。

動作するリソース

Microsoft 365 テナントの Microsoft Entra ID。

使用方法

- uses: aadApp/update
    with:
      # Required. Relative path to the yaml file. Path to the Microsoft Entra app manifest. Environment variables in manifest will be replaced before apply to Microsoft Entra app.
      manifestPath: <path-to-manifest-file>
      # Required. Relative path to the yaml folder. This action will output the final Microsoft Entra app manifest used to update Microsoft Entra app to this path.
      outputFilePath : <path-to-output-file>

botAadApp/create

それが何であるか

このアクションでは、ボット用に新しい Microsoft Entra アプリケーションを作成するか、既存の Microsoft Entra アプリケーションを再利用します。

動作するリソース

Microsoft 365 テナントの Microsoft Entra ID。

使用方法

- uses: botAadApp/create
    with:
      # Required. The Microsoft Entra app's display name
      name: <your-app-name>
    writeToEnvironmentFile:
      # The Microsoft Entra app's client id created for bot.
      botId: <your-preferred-env-var-name>
      # The Microsoft Entra app's client secret created for bot. 
      botPassword: <your-preferred-env-var-name>

arm/deploy

それが何であるか

このアクションでは、指定された ARM テンプレートが並列にデプロイされます。

動作するリソース

Azure サブスクリプション。

使用方法

- uses: arm/deploy
    with:
      # Required. You can use built-in environment variable `AZURE_SUBSCRIPTION_ID` here. TeamsFx will ask you select one subscription if its value is empty. You're free to reference other environment variable here, but TeamsFx will not ask you to select subscription if it's empty in this case.
      subscriptionId: ${{AZURE_SUBSCRIPTION_ID}}
      # Required. You can use built-in environment variable `AZURE_RESOURCE_GROUP_NAME` here. TeamsFx will ask you to select or create one resource group if its value is empty. You're free to reference other environment variable here, but TeamsFx will not ask you to select or create resource group if it's empty in this case.
      resourceGroupName: ${{AZURE_RESOURCE_GROUP_NAME}}
      # Required. The ARM templates to be deployed.
      templates:
        # Required. Relative path to the yaml file.
      - path: <path-to-arm-template>
        # Optional. Relative path to the yaml file. TeamsFx will replace the environment variable reference with real value before deploy ARM template.
        parameters: <path-to-arm-template-parameter>
        # Required. Name of the ARM template deployment.
        deploymentName: <arm-deployment-name>
      # Optional. Teams Toolkit will download this bicep CLI version from github for you, will use bicep CLI in PATH if you remove this config.
      bicepCliVersion: v0.9.1

azureStorage/enableStaticWebsite

それが何であるか

このアクションにより、Azure Storage で静的な Web サイト設定が有効になります。

動作するリソース

Azure Storage。

使用方法

- uses: azureStorage/enableStaticWebsite
    with:
      # Required. The resource id of Azure Storage
      storageResourceId: ${{<env-name-of-azure-storage-resource-id>}}
      # Required. The path to index page.
      indexPage: <path-to-index-page>
      # Required. The path to error page.
      errorPage: <path-to-error-page>

azureStaticWebApps/getDeploymentToken

それが何であるか

このアクションは、Azure Static Web Apps からデプロイトークンを取得します。

バージョン情報

v1.4

動作するリソース

Azure Static Web Apps。

使用方法

- uses: azureStaticWebApps/getDeploymentToken
    with:
      resourceId: ${{AZURE_STATIC_WEB_APPS_RESOURCE_ID}}
    writeToEnvironmentFile:
      deploymentToken: SECRET_TAB_SWA_DEPLOYMENT_TOKEN

スクリプト

それが何であるか

このアクションは、ユーザー定義スクリプトを実行します。

動作するリソース

該当なし

使用方法

- uses: script
    with:
     # Required. Command to run or path to the script. Succeeds if exit code is 0. '::set-teamsfx-env key=value' is a special command to generate output variables into .env file, in this case, "mykey=abc" will be added the output in the corresponding .env file.
     run: $my_key="abc"; echo "::set-teamsfx-env mykey=${my_key}"
     # Optional. Available values are: bash, sh, powershell(Powershell Desktop), pwsh(powershell core), cmd. If omitted, it defaults to bash on Linux/MacOS, defaults to pwsh on windows.
     shell: <shell-name>
     # Optional. Current working directory. Defaults to the directory of this file.
     workingDirectory: <working-directory>
     # Optional. Timeout in ms.
     timeout: <timeout-in-ms>
     # Optional. Redirect stdout and stderr to a file.
     redirectTo: <path-to-output-file>

リソースのプロビジョニングをカスタマイズする

プロビジョニング手順は、 teamsapp.yml ファイルの [ provision プロパティ] で定義されます。 provision プロパティにアクションを追加、削除、または更新して、プロビジョニング中に実行する必要があるアクションを定義できます。

パラメーターファイル内の参照環境変数

Teams Toolkit では、 teamsapp.yml、アプリマニフェスト、Microsoft Entra アプリマニフェスト、Azure パラメーターファイルの環境変数からの値の参照がサポートされています。構文 ${{ENV_VARIABLE_NAME}} を使用して環境変数を参照できます。

次の例では、環境変数 MY_AZURE_SUBSCRIPTION_ID の値を subscriptionId に設定します。

subscriptionId: ${{MY_AZURE_SUBSCRIPTION_ID}}

ARM テンプレートファイルをカスタマイズする

定義済みのテンプレートがアプリの要件を満たしていない場合は、独自の ARM テンプレートを作成するか、既存の ARM テンプレートを更新し、次のテンプレートのように arm/deploy アクションへのパスを指定できます。

- uses: arm/deploy
    with:
      subscriptionId: ${{AZURE_SUBSCRIPTION_ID}}
      resourceGroupName: ${{AZURE_RESOURCE_GROUP_NAME}}
      templates:
      - path: <path-to-your-arm-template>
        parameters: <path-to-your-parameter-file>
        deploymentName: <arm-deployment-name>
      bicepCliVersion: <bicep-cli-version>

arm/deploy アクションでは、bicep 形式と json 形式で記述された ARM テンプレートがサポートされます。 json 形式を使用する場合は、 bicepCliVersion パラメーターを省略できます。 Azure Resource Manager に関する基本的な知識が必要です。 Azure Resource Manager の概要については、 Azure Resource Manager のドキュメントを参照してください。

Teams アプリをカスタマイズする

ボットまたは Teams アプリをカスタマイズするには、自分で作成した Microsoft Entra アプリを使用するように環境変数を追加します。 Teams アプリをカスタマイズするには、次の方法を実行します。

Teams アプリに既存の Microsoft Entra アプリを使用する
ボットに既存の Microsoft Entra アプリを使用する

Teams アプリに既存の Microsoft Entra アプリを使用する

次の手順に従って、環境変数を .env ファイルに追加して、Teams アプリ用に作成された Microsoft Entra アプリを使用できます。 Microsoft Entra アプリがまだない場合、または既にアプリを持っていても、正しい値を見つける場所がわからない場合は、 TeamsFx プロジェクトで既存の Microsoft Entra アプリを使用する方法を参照してください。

teamsapp.ymlを開き、aadApp/createアクションを見つけます。
microsoft Entra アプリの情報を格納する環境変数名を writeToEnvironmentFile プロパティで見つけます。 Teams Toolkit を使用してプロジェクトを作成する場合の既定の writeToenvironmentFile 定義は次のとおりです。
```
 writeToEnvironmentFile:
  clientId: AAD_APP_CLIENT_ID
  clientSecret: SECRET_AAD_APP_CLIENT_SECRET
  objectId: AAD_APP_OBJECT_ID
  tenantId: AAD_APP_TENANT_ID
  authority: AAD_APP_OAUTH_AUTHORITY
  authorityHost: AAD_APP_OAUTH_AUTHORITY_HOST
```

手順 2. から各環境変数の値を追加します。

ファイルに次の環境変数とその値 env\.env.{env} 追加します。

 AAD_APP_CLIENT_ID=<value of Microsoft Entra application's client id (application id)> # example: 00000000-0000-0000-0000-000000000000
 AAD_APP_OBJECT_ID=<value of Microsoft Entra application's object id> # example: 00000000-0000-0000-0000-000000000000
 AAD_APP_TENANT_ID=<value of Microsoft Entra's tenant id>> # example: 00000000-0000-0000-0000-000000000000
 AAD_APP_OAUTH_AUTHORITY=<value of Microsoft Entra's authority> # example: https://login.microsoftonline.com/<Directory (tenant) ID>
 AAD_APP_OAUTH_AUTHORITY_HOST=<host of Microsoft Entra's authority> # example: https://login.microsoftonline.com
 AAD_APP_ACCESS_AS_USER_PERMISSION_ID=<id of access_as_user permission> # example: 00000000-0000-0000-0000-000000000000

アプリケーションで Microsoft Entra アプリクライアントシークレットが必要な場合は、次の環境変数とその値をファイル env\.env.{env}.user 追加します。
```
SECRET_AAD_APP_CLIENT_SECRET=<value of Microsoft Entra application's client secret>
```

注:

writeToEnvironmentFileで異なる名前を使用する場合は、例の環境変数の名前を必ず更新してください。
aadApp/createアクションを使用して Microsoft Entra アプリケーションを作成しない場合は、上記の手順に従わずに、任意の名前で必要な環境変数を追加できます。
複数の環境で同じ Microsoft Entra アプリを共有しないようにしてください。

ボットに既存の Microsoft Entra アプリを使用する

次の手順に従って、環境変数を .env ファイルに追加して、Teams アプリ用に作成された Microsoft Entra アプリを使用できます。ボット用の Microsoft Entra アプリがまだない場合、または既にボットを持っているが、正しい値を見つける場所がわからない場合は、「 TeamsFx プロジェクトで既存の Microsoft Entra アプリを使用する」を参照してください。

teamsapp.ymlを開き、botAadApp/createアクションを見つけます。
microsoft Entra アプリの情報を格納する環境変数名を writeToEnvironmentFile プロパティで見つけます。 Teams Toolkit を使用してプロジェクトを作成する場合の既定の writeToEnvironmentFile 定義は次のとおりです。
```
 writeToEnvironmentFile:
   botId: BOT_ID
   botPassword: SECRET_BOT_PASSWORD
```
手順 2. から各環境変数の値を追加します。
1. 次の環境変数とその値をファイル env\.env.{env} 追加します。
```
BOT_ID=<value of Microsoft Entra application's client id (application id)> # example: 00000000-0000-0000-0000-000000000000    
```
2. 次の環境変数とその値をファイル env\.env.{env}.user 追加します。
```
SECRET_BOT_PASSWORD=<value of Microsoft Entra application's client secret>
```

注:

writeToEnvironmentFileで異なる名前を使用する場合は、例の環境変数の名前を必ず更新してください。
botAadApp/createアクションを使用して Microsoft Entra アプリケーションを作成しない場合は、上記の手順に従わずに、任意の名前で必要な環境変数を追加できます。
複数の環境で同じ Microsoft Entra アプリを共有しないようにしてください。

次の方法で共有

クラウド リソースをプロビジョニングする

Microsoft Visual Studio Code で Microsoft Teams Toolkit を使用してプロビジョニングする

プロビジョニング アクション

teamsApp/create

それが何であるか

動作するリソース

使用方法

teamsApp/update

それが何であるか

動作するリソース

使用方法

teamsApp/validateManifest

それが何であるか

動作するリソース

使用方法

teamsApp/validateAppPackage

それが何であるか

動作するリソース

使用方法

teamsApp/zipAppPackage

それが何であるか

動作するリソース

使用方法

teamsApp/publishAppPackage

それが何であるか

動作するリソース

使用方法

aadApp/create

それが何であるか

動作するリソース

使用方法

aadApp/update

それが何であるか

動作するリソース

使用方法

botAadApp/create

それが何であるか

動作するリソース

使用方法

arm/deploy

それが何であるか

動作するリソース

使用方法

azureStorage/enableStaticWebsite

それが何であるか

動作するリソース

使用方法

azureStaticWebApps/getDeploymentToken

それが何であるか

バージョン情報

動作するリソース

使用方法

スクリプト

それが何であるか

動作するリソース

使用方法

リソースのプロビジョニングをカスタマイズする

パラメーター ファイル内の参照環境変数

ARM テンプレート ファイルをカスタマイズする

Teams アプリをカスタマイズする

Teams アプリに既存の Microsoft Entra アプリを使用する

ボットに既存の Microsoft Entra アプリを使用する

関連項目

フィードバック

その他のリソース

クラウドリソースをプロビジョニングする

プロビジョニングアクション

パラメーターファイル内の参照環境変数

ARM テンプレートファイルをカスタマイズする