Tutorial: Criar uma função personalizada do Azure usando o Azure PowerShell

Artigo
12/01/2023

Se as funções internas do Azure não atenderem às necessidades específicas de sua organização, você poderá criar funções personalizadas próprias. Para este tutorial, crie uma função personalizada chamada Tíquetes de suporte do leitor usando o Azure PowerShell. A função personalizada permite ao usuário ver tudo no painel de controle de uma assinatura e também abrir tíquetes de suporte.

Neste tutorial, você aprenderá como:

Criar uma função personalizada
Listar funções personalizadas
Atualizar uma função personalizada
Excluir uma função personalizada

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

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.

Pré-requisitos

Neste tutorial, você precisará de:

Permissões para criar funções personalizadas, como Administrador de Acesso do Usuário
Azure Cloud Shell ou Azure PowerShell

Entre no Azure PowerShell.

Criar uma função personalizada

A maneira mais fácil de criar uma função personalizada é começar com uma função interna, editá-la e criar uma nova função.

No PowerShell, use o comando Get-AzProviderOperation a fim de obter a lista de operações para o provedor de recursos Microsoft.Support. É útil conhecer as operações disponíveis para criar as permissões. Você também poderá ver uma lista de todas as operações em Operações do provedor de recursos do Azure.

Get-AzProviderOperation "Microsoft.Support/*" | FT Operation, Description -AutoSize

Operation                              Description
---------                              -----------
Microsoft.Support/register/action      Registers to Support Resource Provider
Microsoft.Support/supportTickets/read  Gets Support Ticket details (including status, severity, contact ...
Microsoft.Support/supportTickets/write Creates or Updates a Support Ticket. You can create a Support Tic...

Use o comando Get-AzRoleDefinition para exportar a função Leitor no formato JSON.

Get-AzRoleDefinition -Name "Reader" | ConvertTo-Json | Out-File C:\CustomRoles\ReaderSupportRole.json

Abra o arquivo ReaderSupportRole.json em um editor.

O exemplo a seguir mostra a saída JSON. Para obter informações sobre as diversas propriedades, confira Funções personalizadas do Azure.

{
  "Name": "Reader",
  "Id": "acdd72a7-3385-48ef-bd42-f606fba81ae7",
  "IsCustom": false,
  "Description": "Lets you view everything, but not make any changes.",
  "Actions": [
    "*/read"
  ],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": [
    "/"
  ]
}

Edite o arquivo JSON para adicionar a ação "Microsoft.Support/*" à propriedade Actions. Não se esqueça de incluir uma vírgula após a ação de leitura. Essa ação permitirá que o usuário crie tíquetes de suporte.
Obtenha a ID de sua assinatura usando o comando Get-AzSubscription.
```
Get-AzSubscription
```
Em AssignableScopes, adicione sua ID de assinatura com o seguinte formato: "/subscriptions/00000000-0000-0000-0000-000000000000"

Você deve adicionar IDs de assinatura explícitas; caso contrário, não será possível importar a função para a assinatura.
Exclua a linha da propriedade Id e altere a propriedade IsCustom para true.

Altere as propriedades Name e Description para "Tíquetes de suporte do leitor" e "Exibir tudo na assinatura e também abrir tíquetes de suporte".

Seu arquivo JSON deverá ter a seguinte aparência:

{
  "Name": "Reader Support Tickets",
  "IsCustom": true,
  "Description": "View everything in the subscription and also open support tickets.",
  "Actions": [
    "*/read",
    "Microsoft.Support/*"
  ],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/00000000-0000-0000-0000-000000000000"
  ]
}

Para criar a nova função personalizada, use o comando New-AzRoleDefinition e especifique o arquivo de definição da função JSON.

New-AzRoleDefinition -InputFile "C:\CustomRoles\ReaderSupportRole.json"

Name             : Reader Support Tickets
Id               : 22222222-2222-2222-2222-222222222222
IsCustom         : True
Description      : View everything in the subscription and also open support tickets.
Actions          : {*/read, Microsoft.Support/*}
NotActions       : {}
DataActions      : {}
NotDataActions   : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000}

A nova função personalizada agora está disponível no portal do Azure e pode ser atribuída a usuários, grupos ou entidades de serviço da mesma forma que as funções internas.

Listar funções personalizadas

Para listar todas as funções personalizadas, use o comando Get-AzRoleDefinition.

Get-AzRoleDefinition | ? {$_.IsCustom -eq $true} | FT Name, IsCustom

Name                   IsCustom
----                   --------
Reader Support Tickets     True

Você também pode ver a função personalizada no portal do Azure.

captura de tela de função personalizada importada no Portal do Azure

Atualizar uma função personalizada

Para atualizar a função personalizada, você pode atualizar o arquivo JSON ou usar o objeto PSRoleDefinition.

Para atualizar o arquivo JSON, use o comando Get-AzRoleDefinition para produzir a função personalizada no formato JSON.

Get-AzRoleDefinition -Name "Reader Support Tickets" | ConvertTo-Json | Out-File C:\CustomRoles\ReaderSupportRole2.json

Abra o arquivo em um editor.

Em Actions, adicione a ação de criar e gerenciar implantações de grupos de recursos "Microsoft.Resources/deployments/*".

O arquivo JSON atualizado deve ficar mais ou menos assim:

{
  "Name": "Reader Support Tickets",
  "Id": "22222222-2222-2222-2222-222222222222",
  "IsCustom": true,
  "Description": "View everything in the subscription and also open support tickets.",
  "Actions": [
    "*/read",
    "Microsoft.Support/*",
    "Microsoft.Resources/deployments/*"
  ],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/00000000-0000-0000-0000-000000000000"
  ]
}

Para atualizar a função personalizada, use o comando Set-AzRoleDefinition e especifique o arquivo JSON atualizado.

Set-AzRoleDefinition -InputFile "C:\CustomRoles\ReaderSupportRole2.json"

Name             : Reader Support Tickets
Id               : 22222222-2222-2222-2222-222222222222
IsCustom         : True
Description      : View everything in the subscription and also open support tickets.
Actions          : {*/read, Microsoft.Support/*, Microsoft.Resources/deployments/*}
NotActions       : {}
DataActions      : {}
NotDataActions   : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000}

Para usar o objeto PSRoleDefinition e atualizar a função personalizada, primeiro use o comando Get-AzRoleDefinition para obter a função.
```
$role = Get-AzRoleDefinition "Reader Support Tickets"
```
Chame o método Add para adicionar a ação de leitura das configurações de diagnóstico.
```
$role.Actions.Add("Microsoft.Insights/diagnosticSettings/*/read")
```

Use o comando Set-AzRoleDefinition para atualizar a função.

Set-AzRoleDefinition -Role $role

Name             : Reader Support Tickets
Id               : 22222222-2222-2222-2222-222222222222
IsCustom         : True
Description      : View everything in the subscription and also open support tickets.
Actions          : {*/read, Microsoft.Support/*, Microsoft.Resources/deployments/*,
                   Microsoft.Insights/diagnosticSettings/*/read}
NotActions       : {}
DataActions      : {}
NotDataActions   : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000}

Excluir uma função personalizada

Use o comando Get-AzRoleDefinition para obter a ID da função personalizada.
```
Get-AzRoleDefinition "Reader Support Tickets"
```

Use o comando Remove-AzRoleDefinition e especifique a ID de função para excluir a função personalizada.

Remove-AzRoleDefinition -Id "22222222-2222-2222-2222-222222222222"

Confirm
Are you sure you want to remove role definition with id '22222222-2222-2222-2222-222222222222'.
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):

Quando solicitado a confirmar, digite Y.

Próximas etapas

Criar ou atualizar funções personalizadas do Azure usando o Azure PowerShell

Compartilhar via