Zelfstudie: toewijzingen van Copilot-tegoeden programmatisch beheren

Copilot Credits financieren het gebruik van agents en Copilot dat u met Copilot Studio bouwt in uw Power Platform-omgevingen. Als beheerder wijst u tegoeden toe aan de omgevingen die ze nodig hebben en bepaalt u wat er gebeurt wanneer een omgeving niet meer beschikt over het toegewezen tegoed. Naast de ervaring van het Power Platform-beheercentrum kunt u Copilot tegoedtoewijzingen beheren met code met behulp van de Power Platform-API en de beheer-SDK's (Admin). Het automatiseren van krediettoewijzing is handig wanneer u capaciteit over veel omgevingen distribueert, overschrijdingsgedrag standaardiseert of toewijzingen beheert als onderdeel van een implementatiepijplijn.

In deze zelfstudie leert u het volgende:

• Beheer Copilot Credits in het Power Platform-beheercentrum.
• Verifieer met behulp van de Power Platform-API.
• Bekijk de Copilot-credits die beschikbaar zijn om toe te wijzen.
• Wijs een omgeving Copilot-credits toe.
• Bepalen of een omgeving gebruikmaakt van tenantcapaciteit.

Copilot-tegoeden worden vertegenwoordigd door de machtigings-id MCSMessages en worden beheerd via de licensing/allocationsV2-bewerkingen van de Power Platform-API. De allocationsV2/availability bewerking rapporteert hoeveel capaciteit beschikbaar is om toe te wijzen en de allocationsV2 bewerking schrijft de toewijzing van een omgeving. Alle programmatische voorbeelden in dit artikel gebruiken API-versie 2024-10-01.

Elke omgevingstoewijzing bevat een set afdwingingsregels die bepalen wat er gebeurt wanneer de omgeving het toegewezen tegoed verbruikt. De optie Putten uit de beschikbare capaciteit in mijn tenant in het beheercentrum komt overeen met de TenantPool afdwingingsregel: wanneer deze is ingeschakeld, blijft de omgeving putten uit niet-toegewezen tenantcapaciteit nadat de eigen toewijzing is uitgeput; wanneer deze is uitgeschakeld, wordt de omgeving beperkt tot de toegewezen capaciteit.

Warning

Als een gepubliceerde omgevingsgroepsregel geldt voor Gebruikmaken van de beschikbare capaciteit in mijn tenant, kunt u de instelling voor een specifieke omgeving niet overschrijven. Updates via het Power Platform-beheercentrum, power platform-API of beheer-SDK's worden geweigerd met de TenantPoolLockedByPolicy fout. Wijzig en publiceer de regel voor de omgevingsgroep of verwijder de omgeving uit de groep om de instelling onafhankelijk te beheren. Na het verwijderen behoudt de omgeving de waarde die het laatst door de groep is toegepast, maar wordt de instelling bewerkbaar. Zie Regels voor omgevingsgroepen voor meer informatie over beschikbare groepsregels.

Prerequisites

• Een app-registratie die is geconfigureerd voor de Power Platform-API. Noteer de toepassings-id (client-id) en de directory-id (tenant-id) van de app-registratie.

• Machtiging voor het beheren van licenties en capaciteit. Meld u aan als gebruiker met de rol Power Platform-beheerder of globale beheerder , of een equivalente rol die licenties en capaciteit kan beheren.

• Installeer voor de voorbeelden voor de SDK de SDK die maandelijks wordt uitgebracht via de openbare galerie:

  • C#: de Microsoft. PowerPlatform.Management NuGet-pakket.
  • Python: het PyPI-pakket voor powerplatformbeheer.

  dotnet add package Microsoft.PowerPlatform.Management
  

  pip install powerplatform-management
  

Copilot krediettoewijzingen beheren

In deze sectie ziet u dezelfde end-to-end-stroom: controleer wat er beschikbaar is, wijs tegoeden toe aan een omgeving en bepaal of de omgeving gebruikmaakt van tenantcapaciteit, in het Power Platform-beheercentrum en in elke SDK. Gebruik de tabbladen om te schakelen tussen het beheercentrum en de taal van uw voorkeur.

Power Platform-beheercentrum

1. Meld u aan bij het Power Platform-beheercentrum.

2. Selecteer Licenties in het navigatiedeelvenster.

3. Selecteer onder ProductenCopilot Studio en selecteer vervolgens Copilot-credits beheren.

   

4. Selecteer de omgeving die u wilt beheren. Gebruik het zoekvak om een omgeving op naam te zoeken.

   

5. Voer onder Capaciteit toewijzen het aantal Copilot-credits in dat aan de omgeving moet worden toegewezen. In het deelvenster ziet u hoeveel tegoed is verbruikt, hoeveel er al is toegewezen en hoeveel er beschikbaar is om toe te wijzen uit uw tenant.

6. Onder Capaciteitsoverschrijdingen schakelt u Gebruikmaken van de beschikbare capaciteit in mijn tenant in of uit om te bepalen wat er gebeurt wanneer de omgeving de toegewezen capaciteit heeft verbruikt:

   • Geselecteerd: zodra de toegewezen credits van de omgeving zijn verbruikt, blijft deze gebruikmaken van de niet-toegewezen capaciteit van uw tenant.
   • Uitgeschakeld: de omgeving wordt beperkt tot de toewijzing en stopt met verbruik wanneer de toewijzing is uitgeput.

   

7. Kies Opslaan.

PowerShell

Het volgende voorbeeld meldt zich interactief aan als de huidige gebruiker, leest het Copilot-tegoed dat beschikbaar is om toe te wijzen, wijst tegoed toe aan een omgeving en schakelt Gebruikmaken van de beschikbare capaciteit in mijn tenant uit, zodat de omgeving is beperkt tot de toegewezen tegoeden.

# 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#

In het volgende voorbeeld meldt u zich interactief aan met behulp van de client-id van uw app-registratie, leest u de beschikbare Copilot-credits die kunnen worden toegewezen, wijst u credits toe aan een omgeving en schakelt u Putten uit de beschikbare capaciteit in mijn tenant uit, zodat de omgeving wordt beperkt tot de toegewezen credits.

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

In het volgende voorbeeld meldt u zich interactief aan met behulp van de client-id van uw app-registratie, leest u de beschikbare Copilot-credits die kunnen worden toegewezen, wijst u credits toe aan een omgeving en schakelt u Putten uit de beschikbare capaciteit in mijn tenant uit, zodat de omgeving wordt beperkt tot de toegewezen credits.

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())

Verwante informatie

• Capaciteitsbeheer voor add-ons
• Zelfstudie: Invoegtoepassingen toewijzen aan omgevingen
• Verificatie met de Power Platform-API