Atribuir funções do Contrato Enterprise a entidades de serviço

  • Artigo

Você pode gerenciar o registro do EA (Contrato Enterprise) no portal do Azure. Você pode criar funções diferentes para gerenciar sua organização, exibir custos e criar assinaturas. Este artigo ajuda você a automatizar algumas dessas tarefas usando o Azure PowerShell e as APIs REST com as entidades de serviço do Microsoft Entra ID.

Observação

Se você tiver várias contas de cobrança de EA em sua organização, deverá conceder as funções de EA às entidades de serviço do Microsoft Entra ID individualmente em cada conta de cobrança do EA.

Antes de começar, verifique se você está familiarizado com os seguintes artigos:

Criar e autenticar sua entidade de serviço

Para automatizar as ações de EA usando uma entidade de serviço, você precisa criar uma identidade de aplicativo do Microsoft Entra, que pode se autenticar de maneira automatizada.

Siga as etapas nestes artigos para criar e autenticar usando sua entidade de serviço.

Este é um exemplo da página de registro de aplicativo.

Captura de tela mostrando como registrar um aplicativo.

Localizar a entidade de serviço e as IDs de locatário

Você precisa da ID do objeto da entidade de serviço e da ID do locatário. Você precisará dessas informações para as operações de atribuição de permissão mais adiante neste artigo. Todos os aplicativos são registrados no Microsoft Entra ID no locatário. Dois tipos de objetos são criados quando o registro do aplicativo é concluído:

  • Objeto de aplicativo – a ID do aplicativo é o que você vê em Aplicativos empresariais. A ID não deve ser usada para conceder funções EA.
  • Objeto Entidade de Serviço – o objeto Entidade de Serviço é o que você vê na janela Registro da Empresa no Microsoft Entra ID. A ID do objeto é usada para conceder funções EA à entidade de serviço.

  1. Abra a ID do Microsoft Entra e selecione Aplicativos empresariais.

  2. Encontre seu aplicativo na lista.

    Captura de tela mostrando um exemplo de aplicativo empresarial.

  3. Selecione o aplicativo para localizar a ID do aplicativo e a ID do objeto:

    Captura de tela mostrando uma ID do aplicativo e uma ID do objeto para um aplicativo empresarial.

  4. Acesse a página Visão geral do Microsoft Entra ID para encontrar a ID do locatário.

    Captura de tela que mostra a ID do locatário.

Observação

O valor da sua ID de locatário do Microsoft Entra é semelhante a um GUID com o seguinte formato: 11111111-1111-1111-1111-111111111111.

Permissões que podem ser atribuídas à entidade de serviço

Mais adiante neste artigo, você dará permissão ao aplicativo do Microsoft Entra para executar ações usando uma função do EA. Você pode atribuir apenas as seguintes funções à entidade de serviço e precisa da ID de definição de função, exatamente como mostrado.

Função Ações permitidas ID de definição de função
EnrollmentReader Os leitores de registro podem exibir dados nos escopos de registro, departamento e conta. Os dados contêm encargos para todas as assinaturas nos escopos, incluindo entre locatários. Pode exibir o saldo de Pagamento antecipado do Azure (anteriormente chamado de compromisso monetário) associado ao registro. 24f8edb6-1668-4659-b5e2-40bb5f3a7d7e
Comprador do EA Compra ordens de reserva e vê as transações de reserva. Ele tem todas as permissões do EnrollmentReader, que, por sua vez, terá todas as permissões do DepartmentReader. Pode exibir o uso e os encargos em todas as contas e assinaturas. Pode exibir o saldo de Pagamento antecipado do Azure (anteriormente chamado de compromisso monetário) associado ao registro. da6647fb-7651-49ee-be91-c43c4877f0c4
DepartmentReader Baixe os detalhes de uso do departamento administrado. Pode exibir o uso e os encargos associados ao departamento. db609904-a47f-4794-9be8-9bd86fbffd8a
SubscriptionCreator Crie assinaturas no escopo de conta fornecido. a0bcee42-bf30-4d1b-926a-48d21664ef71
  • Uma função EnrollmentReader pode ser atribuída a uma entidade de serviço somente por um usuário que tenha uma função de gravador de registro. A função EnrollmentReader atribuída a uma entidade de serviço não é mostrada no portal do Azure. Ela é criada por meio de programação e se destina apenas ao uso programático.
  • Uma função DepartmentReader pode ser atribuída a uma entidade de serviço somente por um usuário que tenha uma função de gravador de registro ou gravador de departamento.
  • Uma função SubscriptionCreator pode ser atribuída a uma entidade de serviço somente por um usuário que seja o proprietário da conta de registro (administrador do EA). A função não é mostrada no portal do Azure. Ela é criada por meio de programação e se destina apenas ao uso programático.
  • A função de comprador do EA não é mostrada no portal do Azure. Ela é criada por meio de programação e se destina apenas ao uso programático.

Ao conceder uma função EA a uma entidade de serviço, você deve usar a propriedade billingRoleAssignmentName necessária. O parâmetro é um GUID único que você precisa fornecer. Você pode gerar um GUID usando o comando New-Guid do PowerShell. Você também pode usar o site do Gerador de GUID/UUID online para gerar um GUID exclusivo.

Uma entidade de serviço pode ter apenas uma função.

Atribuir permissão de função de conta de registro à entidade de serviço

  1. Leia o artigo da API REST Atribuições de função – Put. Enquanto você lê o artigo, selecione Experimentar para começar usando a entidade de serviço.

    Captura de tela mostrando a opção Experimentar no artigo Put.

  2. Use suas credenciais de conta para entrar no locatário com o acesso de registro que deseja atribuir.

  3. Forneça os parâmetros a seguir como parte da solicitação de API.

    • billingAccountName: esse parâmetro é a ID da conta de cobrança. Você pode encontrá-lo no portal do Azure na página de visão geral do Gerenciamento de Custos e Cobrança.

      Captura de tela mostrando a ID da conta de cobrança.

    • billingRoleAssignmentName: esse parâmetro é um GUID exclusivo que você precisa fornecer. Você pode gerar um GUID usando o comando New-Guid do PowerShell. Você também pode usar o site do Gerador de GUID/UUID online para gerar um GUID exclusivo.

    • api-version: use a versão 2019-10-01-preview. Use o corpo da solicitação de exemplo em Atribuições de função – Put – Exemplos.

      O corpo da solicitação tem um código JSON com três parâmetros que você precisará usar.

      Parâmetro Onde encontrá-las
      properties.principalId É o valor da ID do Objeto. Consulte Localizar sua entidade de serviço e IDs de locatário.
      properties.principalTenantId Consulte Localizar sua entidade de serviço e IDs de locatário.
      properties.roleDefinitionId /providers/Microsoft.Billing/billingAccounts/{BillingAccountName}/billingRoleDefinitions/24f8edb6-1668-4659-b5e2-40bb5f3a7d7e

      O nome da conta de cobrança é o mesmo parâmetro que você usou nos parâmetros da API. É a ID de registro que você vê no portal do Azure.

      Observe que 24f8edb6-1668-4659-b5e2-40bb5f3a7d7e é uma ID de definição de função de cobrança para um EnrollmentReader.

  4. Selecione Executar para iniciar o comando.

    Captura de tela mostrando um exemplo de atribuição de função com informações de exemplo prontas para execução.

    Uma resposta 200 OK mostra que a entidade de serviço foi adicionada com êxito.

Agora você pode usar a entidade de serviço para acessar automaticamente as APIs do EA. A entidade de serviço tem a função EnrollmentReader.

Atribuir permissão de função do Comprador de EA à entidade de serviço

Para a função de comprador do EA, use as mesmas etapas para o leitor de registro. Especifique a roleDefinitionId usando o seguinte exemplo:

"/providers/Microsoft.Billing/billingAccounts/1111111/billingRoleDefinitions/ da6647fb-7651-49ee-be91-c43c4877f0c4"

Atribuir a função de leitor de departamento à entidade de serviço

  1. Leia o artigo da API REST Atribuições de função do departamento de registro – Put. Durante a leitura do artigo, selecione Experimentar.

    Captura de tela mostrando a opção Experimentar no artigo Atribuições de função do departamento de registro – Put.

  2. Use suas credenciais de conta para entrar no locatário com o acesso de registro que deseja atribuir.

  3. Forneça os parâmetros a seguir como parte da solicitação de API.

    • billingAccountName: esse parâmetro é a ID da conta de cobrança. Você pode encontrá-lo no portal do Azure na página de visão geral do Gerenciamento de Custos e Cobrança.

      Captura de tela mostrando a ID da conta de cobrança.

    • billingRoleAssignmentName: esse parâmetro é um GUID exclusivo que você precisa fornecer. Você pode gerar um GUID usando o comando New-Guid do PowerShell. Você também pode usar o site do Gerador de GUID/UUID online para gerar um GUID exclusivo.

    • departmentName: esse parâmetro é a ID do departamento. Veja as IDs do departamento no portal do Azure na página Gerenciamento de Custos e Cobrança>Departamentos.

      Para este exemplo, usamos o departamento ACE. A ID do exemplo é 84819.

      Captura de tela mostrando uma ID de departamento de exemplo.

    • api-version: use a versão 2019-10-01-preview. Use a amostra em Atribuições de função do departamento de registro – Put.

      O corpo da solicitação tem um código JSON com três parâmetros que você precisará usar.

      Parâmetro Onde encontrá-las
      properties.principalId É o valor da ID do Objeto. Consulte Localizar sua entidade de serviço e IDs de locatário.
      properties.principalTenantId Consulte Localizar sua entidade de serviço e IDs de locatário.
      properties.roleDefinitionId /providers/Microsoft.Billing/billingAccounts/{BillingAccountName}/billingRoleDefinitions/db609904-a47f-4794-9be8-9bd86fbffd8a

      O nome da conta de cobrança é o mesmo parâmetro que você usou nos parâmetros da API. É a ID de registro que você vê no portal do Azure.

      A ID de definição da função de cobrança de db609904-a47f-4794-9be8-9bd86fbffd8a destina-se a um leitor de departamento.

  4. Selecione Executar para iniciar o comando.

    Captura de tela mostrando um exemplo da opção Experimentar do REST Atribuições de função do departamento de registro – Put, com informações de exemplo prontas para execução.

    Uma resposta 200 OK mostra que a entidade de serviço foi adicionada com êxito.

Agora você pode usar a entidade de serviço para acessar automaticamente as APIs do EA. A entidade de serviço tem a função DepartmentReader.

Atribuir a função de criador de assinatura à entidade de serviço

  1. Leia o artigo Atribuições de função da conta de registro –Put. Ao lê-la, selecione Experimentar para atribuir a função de criador de assinatura à entidade de serviço.

    Captura de tela mostrando a opção Experimentar no artigo Atribuições de função da conta de registro – Put.

  2. Use suas credenciais de conta para entrar no locatário com o acesso de registro que deseja atribuir.

  3. Forneça os parâmetros a seguir como parte da solicitação de API. Leia o artigo em Atribuições de função da conta de registro – Put – Parâmetros de URI.

    • billingAccountName: esse parâmetro é a ID da conta de cobrança. Você pode encontrá-lo no portal do Azure na página de visão geral do Gerenciamento de Custos e Cobrança.

      Captura de tela que mostra a ID da conta de cobrança.

    • billingRoleAssignmentName: esse parâmetro é um GUID exclusivo que você precisa fornecer. Você pode gerar um GUID usando o comando New-Guid do PowerShell. Você também pode usar o site do Gerador de GUID/UUID online para gerar um GUID exclusivo.

    • enrollmentAccountName: esse parâmetro é a ID da conta. Encontre a ID da conta para o nome da conta no portal do Azure na página Gerenciamento de Custos e Cobrança.

      Para este exemplo, usamos a conta de teste do GTM. A ID é 196987.

      Captura de tela mostrando a ID da conta.

    • api-version: use a versão 2019-10-01-preview. Use a amostra em Atribuições de função do departamento de registro – Put – Exemplos.

      O corpo da solicitação tem um código JSON com três parâmetros que você precisará usar.

      Parâmetro Onde encontrá-las
      properties.principalId É o valor da ID do Objeto. Consulte Localizar sua entidade de serviço e IDs de locatário.
      properties.principalTenantId Consulte Localizar sua entidade de serviço e IDs de locatário.
      properties.roleDefinitionId /providers/Microsoft.Billing/billingAccounts/{BillingAccountID}/enrollmentAccounts/{enrollmentAccountID}/billingRoleDefinitions/a0bcee42-bf30-4d1b-926a-48d21664ef71

      O nome da conta de cobrança é o mesmo parâmetro que você usou nos parâmetros da API. É a ID de registro que você vê no portal do Azure.

      A ID de definição da função de cobrança de a0bcee42-bf30-4d1b-926a-48d21664ef71 é para a função de criador da assinatura.

  4. Selecione Executar para iniciar o comando.

    Captura de tela mostrando o artigo Opção Experimentar nas Atribuições de função da conta de registro – Put.

    Uma resposta 200 OK mostra que a entidade de serviço foi adicionada com êxito.

Agora você pode usar a entidade de serviço para acessar automaticamente as APIs do EA. A entidade de serviço tem a função SubscriptionCreator.

Verificar atribuições de função da entidade de serviço

As atribuições de função da entidade de serviço não estão visíveis no portal do Azure. Você pode exibir as atribuições de função da conta de inscrição, incluindo a função de criador da assinatura, com a API Atribuições de Função de Cobrança - Lista por Conta de Inscrição - REST (Cobrança do Azure). Use a API para verificar se a atribuição de função foi bem-sucedida.

Solucionar problemas

Você deve identificar e usar a ID de objeto do aplicativo Enterprise em que concedeu a função EA. Se você usar a ID do objeto de algum outro aplicativo, as chamadas à API falharão. Verifique se você está usando a ID de objeto de aplicativo Enterprise correta.

Se você receber o seguinte erro ao fazer sua chamada à API, poderá estar usando incorretamente o valor da ID do objeto da entidade de serviço localizado em Registros de Aplicativo. Para resolver esse erro, verifique se você está usando a ID do objeto da entidade de serviço de Aplicativos Empresariais, não registros de aplicativo.

The provided principal Tenant Id = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and principal Object Id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx are not valid

Próximas etapas

Comece a usar sua conta de cobrança do Contrato Enterprise.