チュートリアル: Copilot クレジットの割り当てをプログラムで管理する

Copilot Credits は、お使いの Power Platform 環境全体にわたって Copilot Studio で構築したエージェントと Copilot の使用に充てられます。 管理者は、必要な環境にクレジットを割り当て、割り当てられたクレジットが不足したときに何が起こるかを決定します。 Power Platform 管理センターのエクスペリエンスに加えて、Power Platform API と管理 (管理者) SDK を使用して、コードを使用してCopilotクレジットの割り当てを管理できます。 クレジット割り当ての自動化は、多くの環境に容量を分散したり、超過分の動作を標準化したり、デプロイ パイプラインの一部として割り当てを管理したりする場合に便利です。

このチュートリアルで学習する内容は次のとおりです。

• Power Platform 管理センターでCopilot クレジットを管理します。
• Power Platform API を使用して認証します。
• 割り当て可能なCopilot クレジットを表示します。
• 環境にCopilot クレジットを割り当てます。
• 環境がテナント容量を使用するかどうかを制御します。

Copilot クレジットはエンタイトルメント ID MCSMessagesで表され、Power Platform API のlicensing/allocationsV2操作を通じて管理されます。 allocationsV2/availability操作では、割り当て可能な容量が報告され、allocationsV2操作によって環境の割り当てが書き込まれます。 この記事のすべてのプログラムの例では、API バージョンの 2024-10-01を使用します。

各環境の割り当てには、環境が割り当てられたクレジットを使用したときに何が起こるかを決定する一連の 適用規則 が適用されます。 管理センターの テナント内の使用可能な容量から使用する オプションは、TenantPool 適用ルールに対応します。これを有効にすると、環境は自身に割り当てられた容量を使い切った後も、未割り当てのテナント容量から引き続き使用します。これを無効にすると、環境は割り当てられた容量が上限になります。

Warning

公開された 環境グループ ルール が テナントで使用可能な容量を使用する を規定している場合、個別の環境に対してこの設定を上書きすることはできません。 Power Platform 管理センター、Power Platform API、または管理 SDK を介した更新は、 TenantPoolLockedByPolicy エラーで拒否されます。 環境グループの規則を変更して再発行するか、グループ から環境を削除 して設定を個別に管理します。 削除後、環境はグループによって最後に適用された値を保持しますが、設定は編集可能になります。 使用可能なグループ ルールの詳細については、「 環境グループのルール」を参照してください。

前提条件

• Power Platform API 用に構成されたアプリの登録。 アプリ登録の アプリケーション (クライアント) ID と ディレクトリ (テナント) ID をメモします。

• ライセンスと容量を管理する権限。 Power Platform Administrator ロールまたはグローバル管理者ロール、またはライセンスと容量を管理できる同等のロールを持つユーザーとしてサインインします。

• SDK のサンプルについては、公開ギャラリーで毎月公開される SDK をインストールします。

  • C#: Microsoft。PowerPlatform.Management NuGet パッケージ。
  • Python: powerplatform-management PyPI パッケージ。

  dotnet add package Microsoft.PowerPlatform.Management
  

  pip install powerplatform-management
  

Copilotクレジットの割り当てを管理する

このセクションでは、Power Platform 管理センターと各 SDK で、同じエンド ツー エンド フロー (使用可能な内容の確認、環境へのクレジットの割り当て、テナント容量から環境が引き出されるかどうかを制御する) を示します。 タブを使用して、管理センターと優先言語を切り替えます。

Power Platform 管理センター

1. Power Platform 管理センターにサインインします。

2. サイド ナビゲーションのウィンドウで、ライセンスを選択します。

3. [製品] で [Copilot Studio] を選択し、[Copilot クレジットの管理] を選択します。

   

4. 管理する環境を選択します。 名前で環境を検索するには、[ 検索 ] ボックスを使用します。

   

5. [容量の割り当て] で、環境に割り当てるCopilot クレジットの数を入力します。 ウィンドウには、使用されているクレジットの数、既に割り当てられているクレジットの数、テナントから割り当てることができる数が表示されます。

6. キャパシティ超過で、テナントの利用可能キャパシティから引き出すを選択または選択解除し、環境の割り当てキャパシティが枯渇した際の動作を制御します:

   • 選択済み: 環境に割り当てられたクレジットが消費された後も、テナントの未割り当て容量を引き続き利用します。
   • クリア: 環境は割り当て時に制限され、割り当てが使い果たされると消費を停止します。

   

7. 保存を選びます。

PowerShell

次の例では、現在のユーザーとして対話的にサインインし、割り当て可能な Copilot クレジットを確認して、環境にクレジットを割り当て、自分のテナントで利用可能な容量から使用する をオフにして、環境の上限が割り当て量に制限されるようにします。

# Requires the MSAL.PS module: Install-Module MSAL.PS -Scope CurrentUser
Import-Module "MSAL.PS"

$clientId      = "<application (client) ID of your app registration>"
$tenantId      = "<directory (tenant) ID>"
$environmentId = "<environment ID>"
$apiBaseUrl    = "https://api.powerplatform.com"
$apiVersion    = "2024-10-01"

# Sign in interactively and request a token for the Power Platform API
$auth = Get-MsalToken -ClientId $clientId -TenantId $tenantId -Scope "https://api.powerplatform.com/.default" -Interactive
$headers = @{ Authorization = "Bearer $($auth.AccessToken)" }

# 1. View the Copilot Credits available to allocate for the environment
$filter = [uri]::EscapeDataString("environmentId eq '$environmentId' and EntitlementId in ('MCSMessages')")
$availability = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/licensing/allocationsV2/availability?api-version=$apiVersion&`$filter=$filter" `
    -Headers $headers
$availability.entitlementAllocationsAvailable |
    ForEach-Object { Write-Host "$($_.entitlementId): $($_.availableQuantity) available" }

# 2. Allocate Copilot Credits to the environment and turn off tenant capacity draw
$allocationBody = @{
    scope = @{ environmentId = $environmentId }
    allocatedEntitlements = @(
        @{
            entitlementId    = "MCSMessages"
            allocation       = @{ quantity = 5000 }
            enforcementRules = @(
                # Disable TenantPool so the environment is capped at its allocation.
                # Set enabled = $true to let the environment draw from tenant capacity.
                @{ ruleType = "TenantPool"; enabled = $false }
            )
        }
    )
} | ConvertTo-Json -Depth 10

Invoke-RestMethod -Method Put `
    -Uri "$apiBaseUrl/licensing/allocationsV2?api-version=$apiVersion" `
    -Headers $headers -ContentType "application/json" -Body $allocationBody
Write-Host "Updated Copilot credit allocation for environment $environmentId"

C#

次の例では、アプリ登録のクライアント ID を使用して対話型でサインインし、割り当て可能な Copilot クレジットを取得し、環境にクレジットを割り当て、テナントで使用可能な容量から引き出す をオフにして、環境の上限を割り当て量までに制限します。

using Microsoft.PowerPlatform.Management;
using Microsoft.PowerPlatform.Management.Models;

// Create an interactive client using your app registration's client ID.
// A browser window opens for sign-in.
var factory = new ServiceClientFactory();
var client = factory.Create("YOUR_CLIENT_ID");

var environmentId = "<environment ID>";
var apiVersion = "2024-10-01";

// 1. View the Copilot Credits available to allocate for the environment
var availability = await client.Licensing.AllocationsV2.Availability.GetAsync(config =>
{
    config.QueryParameters.ApiVersion = apiVersion;
    config.QueryParameters.Filter =
        $"environmentId eq '{environmentId}' and EntitlementId in (MCSMessages)";
});

foreach (var entitlement in availability.EntitlementAllocationsAvailable)
{
    Console.WriteLine($"{entitlement.EntitlementId}: {entitlement.AvailableQuantity} available");
}

// 2. Allocate Copilot Credits to the environment and turn off tenant capacity draw
var request = new AllocationPutRequestModel
{
    Scope = new ScopeModel { EnvironmentId = environmentId },
    AllocatedEntitlements = new List<EntitlementAllocationModel>
    {
        new EntitlementAllocationModel
        {
            EntitlementId = "MCSMessages",
            Allocation = new AllocationModel { Quantity = 5000 },
            EnforcementRules = new List<AllocationEnforcementRule>
            {
                // Disable TenantPool so the environment is capped at its allocation.
                // Set Enabled = true to let the environment draw from tenant capacity.
                new AllocationEnforcementRule
                {
                    RuleType = AllocationEnforcementRuleTypes.TenantPool,
                    Enabled = false
                }
            }
        }
    }
};

await client.Licensing.AllocationsV2.PutAsync(request, config =>
{
    config.QueryParameters.ApiVersion = apiVersion;
});
Console.WriteLine($"Updated Copilot credit allocation for environment {environmentId}");

Python

次の例では、アプリ登録のクライアント ID を使用して対話型でサインインし、割り当て可能な Copilot クレジットを取得し、環境にクレジットを割り当て、テナントで使用可能な容量から引き出す をオフにして、環境の上限を割り当て量までに制限します。

import asyncio
from azure.identity import InteractiveBrowserCredential
from kiota_abstractions.base_request_configuration import RequestConfiguration
from kiota_authentication_azure.azure_identity_authentication_provider import (
    AzureIdentityAuthenticationProvider,
)
from kiota_http.httpx_request_adapter import HttpxRequestAdapter
from mspp_management.service_client_base import ServiceClientBase
from mspp_management.licensing.allocations_v2.allocations_v2_request_builder import (
    AllocationsV2RequestBuilder,
)
from mspp_management.licensing.allocations_v2.availability.availability_request_builder import (
    AvailabilityRequestBuilder,
)
from mspp_management.models.allocation_put_request_model import AllocationPutRequestModel
from mspp_management.models.scope_model import ScopeModel
from mspp_management.models.entitlement_allocation_model import EntitlementAllocationModel
from mspp_management.models.allocation_model import AllocationModel
from mspp_management.models.allocation_enforcement_rule import AllocationEnforcementRule
from mspp_management.models.allocation_enforcement_rule_types import (
    AllocationEnforcementRuleTypes,
)

API_VERSION = "2024-10-01"


async def manage_copilot_credits(client: ServiceClientBase, environment_id: str):
    # 1. View the Copilot Credits available to allocate for the environment
    query_params = AvailabilityRequestBuilder.AvailabilityRequestBuilderGetQueryParameters(
        api_version=API_VERSION,
        filter=f"environmentId eq '{environment_id}' and EntitlementId in (MCSMessages)",
    )
    availability = await client.licensing.allocations_v2.availability.get(
        request_configuration=RequestConfiguration(query_parameters=query_params)
    )
    for entitlement in availability.entitlement_allocations_available:
        print(f"{entitlement.entitlement_id}: {entitlement.available_quantity} available")

    # 2. Allocate Copilot Credits to the environment and turn off tenant capacity draw
    # Disable TenantPool so the environment is capped at its allocation.
    # Set enabled = True to let the environment draw from tenant capacity.
    tenant_pool_rule = AllocationEnforcementRule()
    tenant_pool_rule.rule_type = AllocationEnforcementRuleTypes.TenantPool
    tenant_pool_rule.enabled = False

    entitlement = EntitlementAllocationModel()
    entitlement.entitlement_id = "MCSMessages"
    entitlement.allocation = AllocationModel()
    entitlement.allocation.quantity = 5000
    entitlement.enforcement_rules = [tenant_pool_rule]

    request = AllocationPutRequestModel()
    request.scope = ScopeModel()
    request.scope.environment_id = environment_id
    request.allocated_entitlements = [entitlement]

    put_params = AllocationsV2RequestBuilder.AllocationsV2RequestBuilderPutQueryParameters(
        api_version=API_VERSION,
    )
    await client.licensing.allocations_v2.put(
        request, request_configuration=RequestConfiguration(query_parameters=put_params)
    )
    print(f"Updated Copilot credit allocation for environment {environment_id}")


async def main():
    # Sign in interactively using your app registration's client ID.
    credential = InteractiveBrowserCredential(client_id="YOUR_CLIENT_ID")
    auth_provider = AzureIdentityAuthenticationProvider(
        credentials=credential,
        scopes=["https://api.powerplatform.com/.default"],
    )
    adapter = HttpxRequestAdapter(authentication_provider=auth_provider)
    client = ServiceClientBase(adapter)

    await manage_copilot_credits(client, environment_id="<environment ID>")


asyncio.run(main())

関連情報

• アドオンの容量管理
• チュートリアル: 環境にアドオンを割り当てる
• Power Platform API を使用した認証