Guia de início rápido: crie e implante seu primeiro arquivo Bicep com recursos do Microsoft Graph
Neste início rápido, você cria um arquivo Bicep que declara um grupo de segurança do Microsoft Entra e uma identidade de serviço gerenciado (MSI), representando um recurso do Microsoft Graph e um recurso do Azure, respectivamente. Em seguida, você adiciona o MSI como proprietário do grupo. Você também aprende como a extensão Bicep simplifica o desenvolvimento fornecendo segurança de tipo, validação de sintaxe e preenchimento automático. Finalmente, você implanta o arquivo Bicep usando um usuário conectado.
Importante
Este artigo de início rápido usa referências de tipo dinâmico em vez de tipos internos que foram preteridos e serão desativados em 24 de janeiro de 2025. Até a data da aposentadoria, os tipos embutidos, indicados por extension microsoftGraph, coexistirão com os novos tipos dinâmicos. Se qualquer um dos seus arquivos Bicep existentes usar tipos internos, mude para o uso de tipos dinâmicos para evitar problemas futuros de implantação de arquivos Bicep.
Importante
O Microsoft Graph Bicep está atualmente em pré-visualização. Veja Termos de Utilização Complementares da Pré-visualizações do Microsoft Azure para obter os termos legais que se aplicam às funcionalidades do Azure que estão na versão beta, na pré-visualização ou que ainda não foram lançadas para disponibilidade geral.
Pré-requisitos
Ter uma assinatura válida do Azure: se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
Instale as ferramentas do Bicep para criação e implantação. Este guia de início rápido usa o VS Code com a extensão Bicep para criação e a CLI do Azure para implantação. Exemplos também são fornecidos para o Azure PowerShell. A versão mínima necessária do Bicep é v0.30.3.
Ter uma função do Microsoft Entra que lhe atribua permissões para criar um grupo de segurança. Os usuários têm essa permissão por padrão. No entanto, os administradores podem desativar esse padrão, caso em que você precisa receber pelo menos a função de Administrador de Grupos.
Adicionar um grupo de aplicativos do Microsoft Graph
Inicie o VS Code e crie dois novos arquivos, main.bicep e bicepconfig.json na mesma pasta.
Em seguida, para poder declarar recursos do Microsoft Graph em um arquivo Bicep, você precisa habilitar o recurso de visualização do Bicep e especificar as versões do tipo Microsoft Graph Bicep, configurando bicepconfig.json.
Este exemplo usa os recursos v1.0 e declara um nome de extensão amigável "microsoftGraphV1_0" para fazer referência à versão do br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:0.1.8-preview tipo no Microsoft Artifact Registry.
{
"experimentalFeaturesEnabled": {
"extensibility": true
},
// specify an alias for the version of the v1.0 dynamic types package you want to use
"extensions": {
"microsoftGraphV1_0": "br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:0.1.8-preview"
}
}
Você também pode declarar recursos do Microsoft Graph de beta e v1.0 no mesmo arquivo Bicep adicionando outra referência a uma versão de tipo beta do Microsoft Artifact Registry.
Em main.bicep, digite extension microsoftGraphV1_0, onde microsoftGraphV1_0 é seu nome amigável para fazer referência ao pacote de tipos dinâmicos no Microsoft Artifact Registry. A extension instrução permite que o compilador Bicep saiba que você está incluindo os tipos do Microsoft Graph definidos no bicepconfig.json. Na próxima linha, defina um recurso usando a resource palavra-chave. Digite resource exampleGroup e adicione um espaço.
extension microsoftGraphV1_0
resource exampleGroup
Quando você adiciona um espaço após o nome simbólico, uma lista de tipos de recursos é exibida. Continue digitando grupo até poder selecionar Microsoft.Graph/Groups nas opções disponíveis.
Gorjeta
Se você não vir as opções do intellisense no VS Code, certifique-se de ter instalado a extensão Bicep conforme especificado em Pré-requisitos. Se você tiver instalado a extensão, dê ao serviço de idioma Bicep algum tempo para iniciar depois de abrir o arquivo Bicep. Uma notificação no canto inferior direito indica que o serviço está a iniciar. Quando essa notificação desaparece, o serviço está em execução.
Depois de selecionar Microsoft.Graph/Groups, são apresentadas as versões de API disponíveis - beta ou v1.0. Sempre selecione v1.0, a menos que não esteja disponível ou que as propriedades de recursos necessárias só estejam disponíveis em versão beta. Para este início rápido, use v1.0.
Após a cotação única para o tipo de recurso, adicione = e um espaço. São apresentadas opções para adicionar propriedades ao recurso. Selecione as propriedades necessárias.
Esta opção adiciona todas as propriedades para o tipo de recurso que são necessárias para a implantação. Depois de selecionar essa opção, seu grupo tem as seguintes propriedades:
resource exampleGroup 'Microsoft.Graph/groups@v1.0' = {
displayName:
mailEnabled:
mailNickname:
securityEnabled:
uniqueName:
}
Forneça valores para essas propriedades, definindo mailEnabled como false e securityEnabled como true. uniqueName representa uma chave imutável fornecida pelo cliente para este recurso de grupo.
Adicionar um recurso de identidade gerenciado
O VS Code com a extensão Bicep simplifica o desenvolvimento fornecendo trechos predefinidos, como um trecho que cria uma identidade gerenciada. Em main.bicep, digite man e selecione res-managed-identity na lista e pressione [TAB] ou [ENTER].
Observação: no momento, não há suporte para trechos de recursos extensíveis, como recursos do Microsoft Graph.
Seu arquivo Bicep agora contém o seguinte código:
resource managedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' = {
name: 'name'
location: location
}
Você pode corrigir o erro de definição de parâmetro ausente adicionando uma definição de parâmetro para location. Na definição de extensão, adicione param location string = resourceGroup().location. Para obter mais informações sobre a função usada aqui, consulte resourceGroup(). Altere o nome da identidade gerenciada de name para exampleManagedIdentity.
Tornar a identidade gerenciada um proprietário do recurso de grupo
exampleGroup No recurso, crie uma nova linha em uniqueName, digite ow, que mostra os proprietários como a única opção de propriedade correspondente e pressione [TAB] ou [ENTER].
A propriedade owners é uma matriz, portanto, adicione [] e agora faça referência ao ID principal da identidade gerenciada usando intellisense, digitando m e escolhendo managedIdentity (o nome simbólico para a identidade gerenciada), digitando um . e escolhendo propriedades, digitando outro . e escolhendo principalId.
Seu arquivo main.bicep agora deve se parecer com:
extension microsoftGraphV1_0
param location string = resourceGroup().location
resource exampleGroup 'Microsoft.Graph/groups@v1.0' = {
displayName: 'My example group'
mailEnabled: false
mailNickname: 'my-example-group'
securityEnabled: true
uniqueName: 'myExampleGroup'
owners: [managedIdentity.properties.principalId]
}
resource managedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' = {
name: 'exampleManagedIdentity'
location: location
}
Implantar o arquivo Bicep usando um usuário conectado
Implante o arquivo Bicep entrando na CLI do Azure ou no Azure PowerShell usando os exemplos a seguir. Os exemplos da CLI do Azure nesta documentação usam o console Bash.
## Sign in to Azure CLI
az login
## Create a resource group
az group create --name exampleRG --location eastus
## Deploy the Bicep file
az deployment group create --resource-group exampleRG --template-file main.bicep
Quando a implantação terminar, você verá uma mensagem indicando que a implantação foi bem-sucedida.
Nota
Devido a atrasos de replicação, adicionar a identidade de serviço gerenciado (MSI) como proprietário do grupo Microsoft Entra pode fazer com que a implantação falhe. Aguarde um pouco e, em seguida, implante o mesmo arquivo Bicep novamente.
Clean up resources (Limpar recursos)
Quando os recursos do Azure não forem mais necessários, use a CLI do Azure ou o módulo do Azure PowerShell para excluir o grupo de recursos de início rápido.
Nota
Os grupos de recursos são um conceito do Azure e não têm impacto nos recursos do Microsoft Graph. Os recursos do Microsoft Graph precisam ser limpos com uma solicitação adicional ao Microsoft Graph. Para isso, você pode usar a CLI do Azure ou o Azure PowerShell, a CLI do Microsoft Graph ou o Microsoft Graph PowerShell.
Os exemplos a seguir mostram comandos para excluir primeiro o recurso do Azure e, em seguida, o recurso do Microsoft Graph usando a CLI do Azure e o Azure PowerShell.
## Delete the resource group
az group delete --name exampleRG
## Delete the Microsoft Graph group
az rest --method delete --url 'https://graph.microsoft.com/v1.0/groups%28uniqueName=%27myExampleGroup%27%29'