Estrutura de definição da iniciativa da Política do Azure

2025-04-06

As iniciativas permitem agrupar várias definições de política relacionadas para simplificar atribuições e gerenciamento porque você trabalha com um grupo como um único item. Por exemplo, você pode agrupar definições de política de marcação relacionadas em uma única iniciativa. Em vez de atribuir cada política individualmente, você aplica a iniciativa.

Você usa JSON para criar uma definição de iniciativa de política. A definição de iniciativa política contém elementos para:

nome a apresentar
descrição
metadados
versão
parâmetros
definições de política
grupos de políticas (esta propriedade faz parte do recurso Conformidade Regulatória (Pré-visualização))

O exemplo a seguir ilustra como criar uma iniciativa para lidar com duas tags: costCenter e productName. Ele usa duas políticas internas para aplicar o valor de tag padrão.

{
    "properties": {
        "displayName": "Billing Tags Policy",
        "policyType": "Custom",
        "description": "Specify cost Center tag and product name tag",
        "version" : "1.0.0",
        "metadata": {
            "version": "1.0.0",
            "category": "Tags"
        },
        "parameters": {
            "costCenterValue": {
                "type": "String",
                "metadata": {
                    "description": "required value for Cost Center tag"
                },
                "defaultValue": "DefaultCostCenter"
            },
            "productNameValue": {
                "type": "String",
                "metadata": {
                    "description": "required value for product Name tag"
                },
                "defaultValue": "DefaultProduct"
            }
        },
        "policyDefinitions": [{
                "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62",
                "definitionVersion": "1.*.*"
                "parameters": {
                    "tagName": {
                        "value": "costCenter"
                    },
                    "tagValue": {
                        "value": "[parameters('costCenterValue')]"
                    }
                }
            },
            {
                "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/2a0e14a6-b0a6-4fab-991a-187a4f81c498",
                "parameters": {
                    "tagName": {
                        "value": "costCenter"
                    },
                    "tagValue": {
                        "value": "[parameters('costCenterValue')]"
                    }
                }
            },
            {
                "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/1e30110a-5ceb-460c-a204-c1c3969c6d62",
                "parameters": {
                    "tagName": {
                        "value": "productName"
                    },
                    "tagValue": {
                        "value": "[parameters('productNameValue')]"
                    }
                }
            },
            {
                "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/2a0e14a6-b0a6-4fab-991a-187a4f81c498",
                "parameters": {
                    "tagName": {
                        "value": "productName"
                    },
                    "tagValue": {
                        "value": "[parameters('productNameValue')]"
                    }
                }
            }
        ]
    }
}

Os internos e padrões da Política do Azure estão em Exemplos de Política do Azure.

Metadados

A propriedade opcional metadata armazena informações sobre a definição da iniciativa de política. Os clientes podem definir quaisquer propriedades e valores úteis para sua organização no metadata. No entanto, há algumas propriedades comuns usadas pela Política Azure e em políticas integradas.

Propriedades comuns de metadados

version (string): rastreia detalhes sobre a versão do conteúdo de uma definição de iniciativa de política. Para integrados, esta versão de metadados seguirá a propriedade versão do integrado. É recomendável usar a propriedade 'version' em vez desta versão de metadados.
category (string): determina em qual categoria no portal do Azure a definição de política é exibida.

Nota

Para uma iniciativa de Conformidade Regulamentar, a categoryConformidade Regulamentar deve ser.
preview (booleano): Ficha verdadeira ou falsa indicando se a definição da iniciativa política está em pré-visualização.
deprecated (booleano): Sinalizador verdadeiro ou falso para se a definição da iniciativa política tiver sido marcada como obsoleta.

Versão (pré-visualização)

As iniciativas de políticas incorporadas podem alojar várias versões com o mesmo definitionID. Se nenhum número de versão for especificado, todas as experiências mostrarão a versão mais recente da definição. Para ver uma versão específica de uma funcionalidade incorporada, deve ser especificada na API, SDK ou interface do utilizador. Para fazer referência a uma versão específica de uma definição dentro de uma atribuição, consulte Versão da definição dentro da atribuição

O serviço de Política do Azure usa version, previewe deprecated propriedades para transmitir o estado e o nível de alteração para uma definição ou iniciativa de política interna. O formato do version é: {Major}.{Minor}.{Patch}. Quando uma definição de política está no estado de pré-visualização, o sufixo preview é anexado à propriedade version e tratado como um valor booleano. Quando uma definição de política é preterida, a depreciação é capturada como um booleano nos metadados da definição usando "deprecated": "true".

Versão principal (exemplo: 2.0.0): introduz alterações significativas, como mudanças importantes na lógica das regras, remoção de parâmetros e a adição de um efeito obrigatório por omissão.
Versão menor (exemplo: 2.1.0): introduz alterações, como modificações menores na lógica das regras, adição de novos valores permitidos de parâmetros, alteração de IDs de definição de função, e a adição ou remoção de definições dentro de uma iniciativa.
Versão do patch (exemplo: 2.1.4): introduz alterações nas sequências de caracteres ou metadados e cenários de segurança de emergência (raros).

As iniciativas internas são versionadas e versões específicas de definições de política internas também podem ser referenciadas em iniciativas internas ou personalizadas. Para obter mais informações, consulte definição de referência e versões.

Durante a pré-visualização, ao criar uma iniciativa por meio do portal, você não poderá especificar versões para referências de definição de política integradas. Todas as referências de política incorporadas em iniciativas personalizadas criadas através do portal serão, em vez disso, padronizadas para a versão mais recente da definição de política.

Para obter mais informações sobre as versões incorporadas da Política do Azure, consulte Versionamento incorporado. Para saber mais sobre o que significa uma política ser obsoleta ou estar em prévia, consulte Políticas em pré-visualização e obsoletas.

Parâmetros

Os parâmetros ajudam a simplificar a gestão das políticas ao reduzirem o número de definições de política. Pense em parâmetros como os campos em um formulário - name, address, city, state. Estes parâmetros permanecem sempre os mesmos, no entanto os seus valores mudam com base no indivíduo que preenche o formulário. Os parâmetros funcionam da mesma forma quando se elaboram iniciativas políticas. Ao incluir parâmetros em uma definição de iniciativa de política, você pode reutilizar esse parâmetro nas políticas incluídas.

Nota

Depois que uma iniciativa é atribuída, os parâmetros de nível de iniciativa não podem ser alterados. Devido a isso, a recomendação é definir um defaultValue ao definir o parâmetro.

Propriedades do parâmetro

Um parâmetro tem as seguintes propriedades que são usadas na definição de iniciativa política:

name: O nome do seu parâmetro. Usado pela função de parameters implantação dentro da regra de políticas. Para obter mais informações, consulte o uso de um valor de parâmetro.
type: Determina se o parâmetro é uma cadeia de caracteres, matriz, objeto, booleano, inteiro, float ou datetime.
metadata: Define subpropriedades usadas principalmente pelo portal do Azure para exibir informações amigáveis:
- description: (Opcional) A explicação de para que o parâmetro é usado. Pode ser usado para fornecer exemplos de valores aceitáveis.
- displayName: O nome amigável mostrado no portal para o parâmetro.
- strongType: (Opcional) Usado ao atribuir a definição de política através do portal. Fornece uma lista sensível ao contexto. Para obter mais informações, consulte strongType.
defaultValue: (Opcional) Define o valor do parâmetro em uma atribuição se nenhum valor for dado.
allowedValues: (Opcional) Fornece uma matriz de valores que o parâmetro aceita durante a atribuição.

Como exemplo, você pode definir uma definição de iniciativa de política para limitar os locais de recursos nas várias definições de política incluídas. Um parâmetro para essa definição de iniciativa política poderia ser locaisPermitidos. O parâmetro fica então disponível para cada definição de política incluída e definido durante a atribuição da iniciativa política.

"parameters": {
    "init_allowedLocations": {
        "type": "array",
        "metadata": {
            "description": "The list of allowed locations for resources.",
            "displayName": "Allowed locations",
            "strongType": "___location"
        },
        "defaultValue": [ "westus2" ],
        "allowedValues": [
            "eastus2",
            "westus2",
            "westus"
        ]
    }
}

Passando um valor de parâmetro para uma definição de política

Você declara quais parâmetros de iniciativa você passa para quais definições de política incluídas na matriz policyDefinitions da definição de iniciativa. Embora o nome do parâmetro possa ser o mesmo, o uso de nomes diferentes nas iniciativas do que nas definições de política simplifica a legibilidade do código.

Por exemplo, o parâmetro de iniciativa init_allowedLocations definido anteriormente pode ser passado para várias definições de política incluídas e seus parâmetros, sql_locations e vm_locations, como este:

"policyDefinitions": [
    {
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/0ec8fc28-d5b7-4603-8fec-39044f00a92b",
        "policyDefinitionReferenceId": "allowedLocationsSQL",
        "parameters": {
            "sql_locations": {
                "value": "[parameters('init_allowedLocations')]"
            }
        }
    },
    {
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/aa09bd0f-aa5f-4343-b6ab-a33a6a6304f3",
        "policyDefinitionReferenceId": "allowedLocationsVMs",
        "parameters": {
            "vm_locations": {
                "value": "[parameters('init_allowedLocations')]"
            }
        }
    }
]

Este exemplo faz referência ao parâmetro init_allowedLocations que foi demonstrado nas propriedades do parâmetro.

strongType

Dentro da metadata propriedade, você pode usar strongType para fornecer uma lista de opções de seleção múltipla no portal do Azure. strongType pode ser um tipo de recurso suportado ou um valor permitido. Para determinar se um tipo de recurso é válido para strongType, use Get-AzResourceProvider.

Alguns tipos de recursos não retornados por Get-AzResourceProvider são suportados. Esses tipos de recursos são:

Microsoft.RecoveryServices/vaults/backupPolicies

Os valores permitidos do tipo não-recurso para strongType são:

___location
resourceTypes
storageSkus
vmSKUs
existingResourceGroups

Definições de política

A policyDefinitions porção da definição da iniciativa é uma matriz que inclui as definições de políticas existentes na iniciativa. Como mencionado em Passando um valor de parâmetro para uma definição de política, essa propriedade é onde os parâmetros de iniciativa são passados para a definição de política.

Propriedades de definição de política

Cada elemento de matriz que representa uma definição de política tem as seguintes propriedades:

policyDefinitionId (string): a ID da definição de política personalizada ou interna a ser incluída.
policyDefinitionReferenceId (string): Um nome curto para a definição de política incluída.
parameters: (Opcional) Os pares nome/valor para passar um parâmetro de iniciativa para a definição de política incluída como uma propriedade nessa definição de política. Para obter mais informações, consulte Parâmetros.
definitionVersion : (Opcional) A versão da definição interna a que se refere. Se nenhuma for especificada, refere-se à versão principal mais recente no momento da atribuição e incorpora automaticamente quaisquer atualizações menores. Para obter mais informações, consulte a versão da definição
groupNames (matriz de cadeias de caracteres): (Opcional) O grupo do qual a definição de política é membro. Para obter mais informações, consulte Grupos de políticas.

Aqui está um exemplo de policyDefinitions que inclui duas definições de política, cada uma recebendo o mesmo parâmetro de iniciativa.

"policyDefinitions": [
    {
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/0ec8fc28-d5b7-4603-8fec-39044f00a92b",
        "policyDefinitionReferenceId": "allowedLocationsSQL",
        "definitionVersion": "1.2.*"
        "parameters": {
            "sql_locations": {
                "value": "[parameters('init_allowedLocations')]"
            }
        }
    },
    {
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/aa09bd0f-aa5f-4343-b6ab-a33a6a6304f3",
        "policyDefinitionReferenceId": "allowedLocationsVMs",
        "parameters": {
            "vm_locations": {
                "value": "[parameters('init_allowedLocations')]"
            }
        }
    }
]

Grupos de definição de políticas

As definições de política em uma definição de iniciativa podem ser agrupadas e categorizadas. O recurso de Conformidade Regulatória (visualização) da Política do Azure usa essa propriedade para agrupar definições em controles e domínios de conformidade. Esta informação está definida na policyDefinitionGroupspropriedade array. Mais detalhes de agrupamento podem ser encontrados em um objeto policyMetadata criado pela Microsoft. Para obter informações, consulte objetos de metadados.

Definição de políticas agrupa parâmetros

Cada elemento de matriz em policyDefinitionGroups deve ter ambas as seguintes propriedades:

name (string) [required]: O nome abreviado do grupo. Em Conformidade Regulatória, o controle. O valor desta propriedade é usado por groupNames in policyDefinitions.
category (string): A hierarquia à qual o grupo pertence. Em Conformidade Regulatória, o domínio de conformidade do controle.
displayName (string): O nome amigável para o grupo ou controle. Utilizado pelo portal.
description (string): uma descrição do que o grupo ou controle abrange.
additionalMetadataId(string): a localização do objeto policyMetadata que tem detalhes adicionais sobre o controle e o domínio de conformidade.

Nota

Os clientes podem apontar para um objeto policyMetadata existente. No entanto, esses objetos são de somente leitura e são criados apenas pela Microsoft.

Um exemplo da policyDefinitionGroups propriedade da definição de iniciativa interna do NIST tem esta aparência:

"policyDefinitionGroups": [
    {
        "name": "NIST_SP_800-53_R4_AC-1",
        "additionalMetadataId": "/providers/Microsoft.PolicyInsights/policyMetadata/NIST_SP_800-53_R4_AC-1"
    }
]

Objetos de metadados

As funcionalidades integradas de conformidade regulatória desenvolvidas pela Microsoft têm informações adicionais sobre cada controlo. Esta informação é:

Exibido no portal do Azure na visão geral de um controle em uma iniciativa de Conformidade Regulamentar.
Disponível via API REST. Consulte o Microsoft.PolicyInsights provedor de recursos e o grupo de operação policyMetadata.
Disponível através da CLI do Azure. Consulte o comando az policy metadata.

Importante

Os objetos de metadados para conformidade regulatória são somente leitura e não podem ser criados pelos clientes.

Os metadados de um agrupamento de políticas têm as properties seguintes informações no nó:

metadataId: A ID de controle à qual o agrupamento se relaciona.
category (obrigatório): O domínio de conformidade ao qual o controle pertence.
title (obrigatório): O nome amigável do ID de controle.
owner (obrigatório): Identifica quem é responsável pelo controle no Azure: Cliente, Microsoft, Compartilhado.
description: Informações adicionais sobre o controlo.
requirements: Detalhes sobre a responsabilidade da implementação do controle.
additionalContentUrl: Um link para mais informações sobre o controle. Essa propriedade geralmente é um link para a seção de documentação que abrange esse controle no padrão de conformidade.

Abaixo está um exemplo do objeto policyMetadata . Este exemplo de metadados pertence ao controle NIST SP 800-53 R4 AC-1 .

{
  "properties": {
    "metadataId": "NIST SP 800-53 R4 AC-1",
    "category": "Access Control",
    "title": "Access Control Policy and Procedures",
    "owner": "Shared",
    "description": "**The organization:**    \na. Develops, documents, and disseminates to [Assignment: organization-defined personnel or roles]:  \n1. An access control policy that addresses purpose, scope, roles, responsibilities, management commitment, coordination among organizational entities, and compliance; and  \n2. Procedures to facilitate the implementation of the access control policy and associated access controls; and  \n
\nb. Reviews and updates the current:  \n1. Access control policy [Assignment: organization-defined frequency]; and  \n2. Access control procedures [Assignment: organization-defined frequency].",
    "requirements": "**a.**  The customer is responsible for developing, documenting, and disseminating access control policies and procedures. The customer access control policies and procedures address access to all customer-deployed resources and customer system access (e.g., access to customer-deployed virtual machines, access to customer-built applications).  \n**b.**  The customer is responsible for reviewing and updating access control policies and procedures in accordance with FedRAMP requirements.",
    "additionalContentUrl": "https://nvd.nist.gov/800-53/Rev4/control/AC-1"
  },
  "id": "/providers/Microsoft.PolicyInsights/policyMetadata/NIST_SP_800-53_R4_AC-1",
  "name": "NIST_SP_800-53_R4_AC-1",
  "type": "Microsoft.PolicyInsights/policyMetadata"
}

Próximos passos

Ver a estrutura da definição
Reveja exemplos em Exemplos de Política do Azure.
Veja Compreender os efeitos da política.
Entenda como criar políticas de forma programática.
Saiba como obter dados de conformidade.
Saiba como corrigir recursos não compatíveis.
Analise o que é um grupo de gerenciamento com Organize seus recursos com grupos de gerenciamento do Azure.

Comentários

Esta página foi útil?