Criar assinaturas do Contrato Enterprise do Azure de modo programático com as APIs mais recentes

  • Artigo

Este artigo ajudará você a criar assinaturas do EA (Contrato Enterprise) do Azure de modo programático para uma conta de cobrança do EA usando as versões mais recentes da API. Caso ainda esteja usando a versão prévia mais antiga, confira Criar assinaturas do Azure de modo programático com APIs herdadas.

Neste artigo, você aprenderá a criar assinaturas programaticamente usando o Azure Resource Manager.

Ao criar uma assinatura do Azure de forma programática, ela se enquadra nos termos do contrato em que você recebe serviços do Azure da Microsoft ou de um revendedor certificado. Para obter mais informações, confira Informações Legais do Microsoft Azure.

Observação

Recomendamos que você use o módulo Az PowerShell do Azure para interagir com o Azure. Para começar, consulte Instalar o Azure PowerShell. Para saber como migrar para o módulo Az PowerShell, confira Migrar o Azure PowerShell do AzureRM para o Az.

Você não pode criar planos de suporte programaticamente. Você pode comprar um novo ou atualizar um plano de suporte no portal do Azure. Navegue até Ajuda + suporte e, na parte superior da página, selecione Escolher o plano de suporte correto.

Pré-requisitos

Um usuário deve ter a função administrador da empresa ou a função de Proprietário em uma Conta de Registro para criar uma assinatura. Há duas maneiras de obter a função Proprietário em uma Conta de Registro:

Para usar uma entidade de serviço para criar uma assinatura do EA, um proprietário da conta de registro deve conceder a essa entidade de serviço a capacidade de criar assinaturas.

Ao usar uma entidade de serviço para criar assinaturas, use a ObjectId do aplicativo Microsoft Entra Enterprise como a ID da Entidade de Serviço usando o Microsoft Graph PowerShell ou a CLI do Azure. Você também pode usar as etapas em Localizar sua entidade de serviço e IDs de locatário para localizar a ID do objeto no portal do Azure para uma entidade de serviço existente.

Para obter mais informações sobre a solicitação de API de atribuição de função do EA, confira Atribuir funções aos nomes de entidade de serviço do Contrato Enterprise do Azure. O artigo inclui uma lista de funções (e IDs de definição de função) que podem ser atribuídas a uma entidade de serviço.

Observação

  • Lembre-se de usar a versão da API correta para dar permissões ao proprietário da conta de registro. Para este artigo e para as APIs documentadas nele, use a API 2019-10-01-preview.
  • Se estiver migrando para usar as APIs mais recentes, a configuração anterior feita com a versão de 01-07-2015 não é convertida automaticamente para ser usada com as APIs mais recentes.
  • As informações da Conta de Registro só ficam visíveis quando a função do usuário é Proprietário da Conta. Quando um usuário tem várias funções, a API usa a função menos restritiva dele.

Localize as contas às quais você tem acesso

Depois que você for adicionado a uma Conta de Registro associada a um Proprietário da Conta, o Azure usa a relação de conta para registro para determinar quando cobrar os encargos de assinatura. Todas as assinaturas criadas na conta serão cobradas no registro de EA do qual a conta faz parte. Para criar assinaturas, você deve passar valores sobre a conta de registro e as entidades de usuário a fim de ser dono da assinatura.

Para executar os comandos a seguir, você deve estar conectado ao diretório base do proprietário da conta, que é o diretório em que as assinaturas são criadas por padrão.

Solicitação para listar todas as contas de registro às quais você tem acesso:

GET https://management.azure.com/providers/Microsoft.Billing/billingaccounts/?api-version=2020-05-01

A resposta da API lista todas as contas de registro às quais você tem acesso:

{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/1234567",
      "name": "1234567",
      "properties": {
        "accountStatus": "Unknown",
        "accountType": "Enterprise",
        "agreementType": "EnterpriseAgreement",
        "soldTo": {
          "companyName": "Contoso",
          "country": "US "
        },
        "billingProfiles": {
          "hasMoreResults": false
        },
        "displayName": "Contoso",
        "enrollmentAccounts": [
          {
            "id": "/providers/Microsoft.Billing/billingAccounts/1234567/enrollmentAccounts/7654321",
            "name": "7654321",
            "type": "Microsoft.Billing/enrollmentAccounts",
            "properties": {
              "accountName": "Contoso",
              "accountOwnerEmail": "kenny@contoso.onmicrosoft.com",
              "costCenter": "Test",
              "isDevTest": false
            }
          }
        ],
        "hasReadAccess": false
      },
      "type": "Microsoft.Billing/billingAccounts"
    }
  ]
}

O valor de um escopo do orçamento e de id são a mesma coisa. O id de sua conta de registro é o escopo do orçamento com o qual a solicitação de assinatura é iniciada. É importante saber a ID porque é um parâmetro obrigatório que você usará posteriormente neste artigo para criar uma assinatura.

Crie assinaturas em uma conta de registro específico

O exemplo a seguir cria uma assinatura denominada Assinatura da Equipe de Desenvolvimento na conta de registro selecionada na etapa anterior.

Usando um dos métodos a seguir, você cria um nome de alias de assinatura. Recomendamos que, ao criar o nome do alias, você:

  • Use caracteres alfanuméricos e hifens
  • Comece com uma letra e termine com um caractere alfanumérico
  • Não use ponto final

Um alias é usado para substituição simples de uma cadeia de caracteres definida pelo usuário em vez do GUID da assinatura. Em outras palavras, você pode usá-lo como um atalho. Saiba mais sobre o alias em Alias – Criar. Nos exemplos a seguir, o sampleAlias é criado, mas você pode usar qualquer cadeia de caracteres que desejar.

Se você tiver várias funções de usuário além da função Proprietário da Conta, deverá recuperar a ID da conta por meio do portal do Azure. Em seguida, você pode usar a ID para criar assinaturas programaticamente.

Chame a API PUT para criar uma solicitação/um alias de criação de assinatura.

PUT https://management.azure.com/providers/Microsoft.Subscription/aliases/{{guid}}?api-version=2021-10-01api-version=2021-10-01

No corpo da solicitação, forneça o billingScope e a id de um de seus enrollmentAccounts.

{
  "properties": {
        "billingScope": "/providers/Microsoft.Billing/BillingAccounts/1234567/enrollmentAccounts/7654321",
        "DisplayName": "Dev Team Subscription", //Subscription Display Name
        "Workload": "Production"
  }
}

Os valores permitidos para Workload são Production e DevTest.

Resposta

{
  "id": "/providers/Microsoft.Subscription/aliases/sampleAlias",
  "name": "sampleAlias",
  "type": "Microsoft.Subscription/aliases",
  "properties": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "provisioningState": "Accepted"
  }
}

É possível executar uma função GET na mesma URL para obter o status da solicitação.

Solicitação

GET https://management.azure.com/providers/Microsoft.Subscription/aliases/{{guid}}?api-version=2021-10-01

Resposta

{
  "id": "/providers/Microsoft.Subscription/aliases/sampleAlias",
  "name": "sampleAlias",
  "type": "Microsoft.Subscription/aliases",
  "properties": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "provisioningState": "Succeeded"
  }
}

Um status em andamento será retornado como um estado Accepted em provisioningState.

Criar assinatura e tornar subscriptionOwnerId o proprietário

Quando uma entidade de serviço utiliza a API de Alias de Assinatura para criar uma nova assinatura e não inclui additionalProperties na solicitação, a entidade de serviço torna-se automaticamente a proprietária da nova assinatura. Se você não quiser que a entidade de serviço seja a proprietária, poderá especificar subscriptionTenantId e subscriptionOwnerId em additionalProperties. Esse processo torna o subscriptionOwnerId especificado o proprietário da nova assinatura, e não a entidade de serviço.

Exemplo de corpo da solicitação:


{
    "properties": {
        "billingScope": "/providers/Microsoft.Billing/billingAccounts/{EABillingAccountId}/enrollmentAccounts/{EnrollmentAccountId}",
        "displayName": "{SubscriptionName}",
        "workLoad": "Production",
        "resellerId": null,
        "additionalProperties": {
            "managementGroupId": "",
            "subscriptionTenantId": "{SubscriptionTenantId}", // Here you input the tenant GUID where the subscription resides after creation
            "subscriptionOwnerId": "{ObjectId that becomes the owner of the subscription}", // Here you input the objectId which is set as the subscription owner when it gets created.
            "tags": {}
        }
    }
}

Criar assinaturas em um locatário diferente

Com a API REST do Alias de assinatura, você pode criar uma assinatura em um locatário diferente utilizando o parâmetro subscriptionTenantId no corpo da solicitação. Sua Entidade de Serviço do Azure (SPN) precisa obter um token do seu locatário de origem para criar a assinatura. Depois de criar a assinatura, você deve obter um token do seu locatário de destino para aceitar a transferência usando a API de Aceitação de Propriedade.

Para obter mais informações sobre como criar assinaturas de EA em outro locatário, confira como Criar assinatura em outro locatário e exibir solicitações de transferência.

Usar o modelo do ARM ou o Bicep

A seção anterior mostrou como criar uma assinatura com o PowerShell, a CLI ou a API REST. Para automatizar a criação de assinaturas, considere o uso de um modelo do ARM (Azure Resource Manager) ou de um arquivo Bicep.

O modelo do ARM a seguir cria uma assinatura. Para billingScope, forneça a ID da conta de registro. A assinatura é criada no grupo de gerenciamento raiz. Depois de criar a assinatura, você poderá movê-la para outro grupo de gerenciamento.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "subscriptionAliasName": {
            "type": "string",
            "metadata": {
                "description": "Provide a name for the alias. This name will also be the display name of the subscription."
            }
        },
        "billingScope": {
            "type": "string",
            "metadata": {
                "description": "Provide the full resource ID of billing scope to use for subscription creation."
            }
        }
    },
    "resources": [
        {
            "scope": "/",
            "name": "[parameters('subscriptionAliasName')]",
            "type": "Microsoft.Subscription/aliases",
            "apiVersion": "2021-10-01",
            "properties": {
                "workLoad": "Production",
                "displayName": "[parameters('subscriptionAliasName')]",
                "billingScope": "[parameters('billingScope')]"
            }
        }
    ],
    "outputs": {}
}

Também é possível usar um arquivo Bicep para criar a assinatura.

targetScope = 'managementGroup'

@description('Provide a name for the alias. This name will also be the display name of the subscription.')
param subscriptionAliasName string

@description('Provide the full resource ID of billing scope to use for subscription creation.')
param billingScope string

resource subscriptionAlias 'Microsoft.Subscription/aliases@2021-10-01' = {
  scope: tenant()
  name: subscriptionAliasName
  properties: {
    workload: 'Production'
    displayName: subscriptionAliasName
    billingScope: billingScope
  }
}

Implante o modelo no nível do grupo de gerenciamento. Os exemplos a seguir mostram a implantação do modelo do ARM de JSON, mas você pode implantar um arquivo Bicep como alternativa.

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/mg1/providers/Microsoft.Resources/deployments/exampledeployment?api-version=2020-06-01

Com um corpo de solicitação:

{
  "location": "eastus",
  "properties": {
    "templateLink": {
      "uri": "http://mystorageaccount.blob.core.windows.net/templates/template.json"
    },
    "parameters": {
      "subscriptionAliasName": {
        "value": "sampleAlias"
      },
      "billingScope": {
        "value": "/providers/Microsoft.Billing/BillingAccounts/1234567/enrollmentAccounts/7654321"
      }
    },
    "mode": "Incremental"
  }
}

Para mover uma assinatura para um novo grupo de gerenciamento, use o modelo do ARM a seguir.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "targetMgId": {
            "type": "string",
            "metadata": {
                "description": "Provide the ID of the management group that you want to move the subscription to."
            }
        },
        "subscriptionId": {
            "type": "string",
            "metadata": {
                "description": "Provide the ID of the existing subscription to move."
            }
        }
    },
    "resources": [
        {
            "scope": "/",
            "type": "Microsoft.Management/managementGroups/subscriptions",
            "apiVersion": "2020-05-01",
            "name": "[concat(parameters('targetMgId'), '/', parameters('subscriptionId'))]",
            "properties": {
            }
        }
    ],
    "outputs": {}
}

Também é possível usar o arquivo Bicep a seguir.

targetScope = 'managementGroup'

@description('Provide the ID of the management group that you want to move the subscription to.')
param targetMgId string

@description('Provide the ID of the existing subscription to move.')
param subscriptionId string

resource subToMG 'Microsoft.Management/managementGroups/subscriptions@2020-05-01' = {
  scope: tenant()
  name: '${targetMgId}/${subscriptionId}'
}

Limitações da API de criação de assinatura do Azure Enterprise

  • Somente as assinaturas do Azure Enterprise poderão ser criadas usando essa API.
  • Há um limite de 5.000 assinaturas por conta de registro. Depois disso, mais assinaturas da conta podem ser criadas apenas no portal do Azure. Para criar mais assinaturas por meio da API, crie outra conta de registro. Assinaturas canceladas, excluídas e transferidas são consideradas para o limite de 5000.
  • Os usuários que não são Proprietários da Conta, mas foram adicionados a uma conta de registro por meio do controle de acesso baseado em função do Azure, não podem criar assinaturas no portal do Azure.

Próximas etapas