Como Usar a API do Microsoft Graph para Provisionar Licenças do Copilot Programaticamente

Atribuir manualmente licenças do Copilot para Microsoft 365 a cada usuário pelo centro de administração é lento e sujeito a erros em grandes organizações. Você precisa de um método repetível e com script para adicionar ou remover licenças do Copilot em centenas ou milhares de usuários. A API do Microsoft Graph fornece um endpoint REST para gerenciar atribuições de licença diretamente de suas ferramentas de automação. Este artigo explica como usar a API do Graph para provisionar licenças do Copilot programaticamente usando PowerShell e autenticação do Azure AD.

Entendendo o SKU da Licença do Copilot e a Estrutura da API Graph

Antes de escrever qualquer código, você precisa do identificador SKU exato do produto para o Copilot para Microsoft 365. Cada plano de licença do Microsoft 365 tem um GUID único chamado SKU ID. Para o Copilot, o SKU ID no Microsoft Graph é CFQ7TTC0LG0Z. Esse identificador é usado no array addLicenses ao chamar a ação assignLicense.

A API do Microsoft Graph usa o endpoint /users/{user-principal-name}/assignLicense. O corpo da requisição contém dois arrays: addLicenses e removeLicenses. Para provisionar uma licença do Copilot, você adiciona o SKU ID ao array addLicenses. Para removê-la, adicione o SKU ID ao array removeLicenses. A API processa ambos os arrays em uma única chamada, permitindo substituir licenças existentes, se necessário.

A API Graph retorna um objeto User com a propriedade assignedLicenses atualizada em caso de sucesso. Se a chamada falhar, a API retorna um erro com campos code e message descrevendo o problema. Erros comuns incluem permissões insuficientes, SKU ID inválido ou o usuário já possuir a licença atribuída.

Pré-requisitos para Usar a API Graph

Para chamar a API Graph, você precisa do seguinte:

• Um locatário do Azure AD com uma assinatura do Copilot para Microsoft 365 que tenha licenças disponíveis.
• Um aplicativo registrado no Azure AD com a permissão delegada ou de aplicativo User.ReadWrite.All. Para scripts não supervisionados, use permissões de aplicativo.
• Consentimento do administrador concedido ao aplicativo para a permissão User.ReadWrite.All.
• Um segredo do cliente ou certificado para o aplicativo autenticar sem interação do usuário.
• O módulo Microsoft Graph PowerShell instalado: Install-Module Microsoft.Graph

Passos para Provisionar uma Licença do Copilot para um Único Usuário

Os passos a seguir usam o módulo Microsoft Graph PowerShell para atribuir uma licença do Copilot a um usuário. Substitua user@contoso.com pelo nome principal de usuário real e YOUR_TENANT_ID pelo ID do locatário do Azure AD.

1. Conectar ao Microsoft Graph
   Execute Connect-MgGraph -Scopes "User.ReadWrite.All" -TenantId "YOUR_TENANT_ID". Faça login com uma conta de administrador que tenha a função de Administrador Global ou Administrador de Licenças. A sessão permanece ativa durante a janela do PowerShell.
2. Recuperar o SKU ID do Copilot
   Execute Get-MgSubscribedSku | Where-Object {$_.SkuPartNumber -eq "COPILOT_MICROSOFT_365"} | Select-Object SkuId, SkuPartNumber. Isso retorna o GUID. O SkuPartNumber do Copilot é COPILOT_MICROSOFT_365. Copie o valor de SkuId.
3. Atribuir a licença ao usuário
   Execute o seguinte bloco de script:

   $userId = "user@contoso.com"
   $skuId = "YOUR_COPIED_SKU_ID"
   $addLicenses = @(
       @{
           SkuId = $skuId
           DisabledPlans = @()
       }
   )
   $removeLicenses = @()
   Set-MgUserLicense -UserId $userId -AddLicenses $addLicenses -RemoveLicenses $removeLicenses

   O array DisabledPlans pode incluir IDs de planos de serviço para desabilitar recursos específicos. Para o Copilot, normalmente você o deixa vazio.

4. Verificar a atribuição da licença
   Execute Get-MgUser -UserId $userId -Property AssignedLicenses | Select-Object -ExpandProperty AssignedLicenses. A saída mostra o SkuId da licença do Copilot atribuída.

Provisionamento em Lote de Licenças do Copilot a partir de um Arquivo CSV

Para grandes organizações, atribua licenças a vários usuários lendo um arquivo CSV. O CSV deve ter uma coluna chamada UserPrincipalName contendo os endereços de e-mail dos usuários.

1. Preparar o arquivo CSV
   Crie um arquivo chamado users.csv com o seguinte conteúdo:

   UserPrincipalName
   user1@contoso.com
   user2@contoso.com
   user3@contoso.com

   Salve o arquivo no diretório de trabalho.

2. Importar o CSV e percorrer os usuários
   Execute este script:

   $users = Import-Csv -Path ".\users.csv"
   $skuId = "YOUR_COPIED_SKU_ID"
   foreach ($user in $users) {
       $userId = $user.UserPrincipalName
       try {
           Set-MgUserLicense -UserId $userId -AddLicenses @(@{SkuId=$skuId;DisabledPlans=@()}) -RemoveLicenses @()
           Write-Host "Licença atribuída a $userId" -ForegroundColor Green
       } catch {
           Write-Host "Falha ao atribuir licença a $userId : $_" -ForegroundColor Red
       }
   }

   O script processa cada usuário e relata sucesso ou falha.

Removendo uma Licença do Copilot Programaticamente

Para remover uma licença do Copilot de um usuário, chame o mesmo endpoint, mas mova o SKU ID para o array removeLicenses.

1. Remover a licença de um único usuário
   Execute:

   $userId = "user@contoso.com"
   $skuId = "YOUR_COPIED_SKU_ID"
   Set-MgUserLicense -UserId $userId -AddLicenses @() -RemoveLicenses @($skuId)

   A API remove a licença imediatamente. O usuário perde o acesso aos recursos do Copilot nos aplicativos do Microsoft 365.

2. Remover licenças em lote a partir de um CSV
   Use o mesmo formato CSV e loop:

   $users = Import-Csv -Path ".\users.csv"
   $skuId = "YOUR_COPIED_SKU_ID"
   foreach ($user in $users) {
       $userId = $user.UserPrincipalName
       Set-MgUserLicense -UserId $userId -AddLicenses @() -RemoveLicenses @($skuId)
   }

   Nenhum tratamento de erro é mostrado aqui por brevidade. Adicione blocos try-catch como no exemplo de atribuição em lote.

Problemas Comuns ao Usar a API Graph para Provisionamento de Licenças

A API retorna 403 Forbidden ou 401 Unauthorized

O aplicativo do Azure AD não possui a permissão User.ReadWrite.All necessária ou o consentimento do administrador não foi concedido. Verifique se a permissão foi adicionada ao registro do aplicativo e se o consentimento do administrador foi fornecido. No portal do Azure, vá em Registros de aplicativo > Seu aplicativo > Permissões de API. Confirme se User.ReadWrite.All está listado com uma marca de verificação verde para consentimento do administrador.

A API retorna 400 Bad Request com código de erro “InvalidSkuId”

O SKU ID fornecido não corresponde a nenhum produto licenciado em seu locatário. Execute Get-MgSubscribedSku para listar todos os SKU IDs e seus SkuPartNumber. Certifique-se de estar usando o GUID correto para o Copilot. O SkuPartNumber COPILOT_MICROSOFT_365 corresponde ao produto CFQ7TTC0LG0Z.

A atribuição da licença é bem-sucedida, mas o usuário não vê o Copilot

Os recursos do Copilot podem levar até 24 horas para aparecer nos aplicativos do Microsoft 365. O provisionamento da licença é imediato no backend, mas a propagação no lado do cliente depende da versão do aplicativo do usuário e da atualização do token. Peça ao usuário para sair de todos os aplicativos do Microsoft 365 e entrar novamente. Se o problema persistir, verifique se o usuário tem a versão mais recente do Microsoft 365 Apps para empresas 2306 ou posterior.

Atribuição de Licença via API Graph vs. Atribuição Manual no Centro de Administração

Item	Atribuição Programática via API Graph	Atribuição Manual no Centro de Administração
Velocidade	Atribui licenças a centenas de usuários em segundos via script	Requer clicar em cada usuário ou enviar um CSV por vez
Repetibilidade	O script pode ser executado em um agendamento ou acionado pelo sistema de RH	Nenhuma automação integrada; é necessário repetir os passos manualmente
Tratamento de erros	O script registra falhas por usuário e continua o processamento	O administrador deve verificar manualmente cada usuário após a atribuição
Modelo de permissão	Usa permissões de aplicativo do Azure AD com consentimento do administrador	Requer função de Administrador Global ou Administrador de Licenças
Trilha de auditoria	Todas as chamadas de API são registradas nos logs de auditoria do Azure AD	As alterações são registradas no log de auditoria do Microsoft 365

Usar a API Graph é o método preferido para organizações que precisam automatizar o gerenciamento do ciclo de vida das licenças. A abordagem baseada em script reduz o erro humano e fornece uma trilha de auditoria clara de todas as alterações de licença.

Agora você pode usar a API do Microsoft Graph e o PowerShell para provisionar licenças do Copilot para usuários individuais ou em lote a partir de um arquivo CSV. Comece registrando um aplicativo do Azure AD com as permissões corretas e testando o script com um único usuário. Para cenários avançados, estenda o script para ler usuários de grupos do Microsoft Entra ID ou de um banco de dados de RH. Use o cmdlet Set-MgUserLicense com o parâmetro -RemoveLicenses para desprovisionar licenças quando os usuários saírem da organização.