Policy Definitions - Create Or Update

Servicio:: Policy

Versión de la API:: 2025-11-01

Esta operación crea o actualiza una definición de política en la suscripción dada con el nombre de pila.

PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/{policyDefinitionName}?api-version=2025-11-01

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
policyDefinitionName	path	True	string pattern: ^[^<>%&:\?.+/][^<>*%&:\?.+/ ]+$	Nombre de la definición de directiva que se va a obtener.
subscriptionId	path	True	string (uuid)	Identificador de la suscripción de destino. El valor debe ser un UUID.
api-version	query	True	string minLength: 1	Versión de API que se usará para esta operación.

Cuerpo de la solicitud

Nombre	Tipo	Description
properties.description	string	Descripción de la definición de directiva.
properties.displayName	string	Nombre para mostrar de la definición de directiva.
properties.externalEvaluationEnforcementSettings	ExternalEvaluationEnforcementSettings	Los detalles del origen de los resultados de evaluación externa requeridos por la directiva durante la evaluación de cumplimiento.
properties.metadata		Metadatos de definición de directiva. Los metadatos son un objeto terminado abierto y normalmente es una colección de pares clave-valor.
properties.mode	string	Modo de definición de directiva. Algunos ejemplos son All, Indexed, Microsoft.KeyVault.Data.
properties.parameters	<string, ParameterDefinitionsValue>	Definiciones de parámetros para los parámetros usados en la regla de directiva. Las claves son los nombres de parámetro.
properties.policyRule		Regla de directiva.
properties.policyType	PolicyType	Tipo de definición de directiva. Los valores posibles son NotSpecified, BuiltIn, Custom y Static.
properties.version	string	La versión de definición de directiva en formato #.#.#
properties.versions	string[]	Lista de versiones disponibles para esta definición de directiva.

Respuestas

Nombre	Tipo	Description
201 Created	PolicyDefinition	Recurso 'PolicyDefinition' crear operación exitosa
Other Status Codes	ErrorResponse	Una respuesta de error inesperada.

Seguridad

azure_auth

Azure Active Directory OAuth2 Flow.

Tipo: oauth2
Flujo: implicit
Dirección URL de autorización: https://login.microsoftonline.com/common/oauth2/authorize

Ámbitos

Nombre	Description
user_impersonation	suplantar la cuenta de usuario

Ejemplos

Create or update a policy definition

Create or update a policy definition with advanced parameters

Create or update a policy definition with external evaluation enforcement settings

Create or update a policy definition

Solicitud de ejemplo

HTTP

PUT https://management.azure.com/subscriptions/ae640e6b-ba3e-4256-9d62-2993eecfa6f2/providers/Microsoft.Authorization/policyDefinitions/ResourceNaming?api-version=2025-11-01

{
  "properties": {
    "description": "Force resource names to begin with given 'prefix' and/or end with given 'suffix'",
    "displayName": "Enforce resource naming convention",
    "metadata": {
      "category": "Naming"
    },
    "mode": "All",
    "parameters": {
      "prefix": {
        "type": "String",
        "metadata": {
          "description": "Resource name prefix",
          "displayName": "Prefix"
        }
      },
      "suffix": {
        "type": "String",
        "metadata": {
          "description": "Resource name suffix",
          "displayName": "Suffix"
        }
      }
    },
    "policyRule": {
      "if": {
        "not": {
          "field": "name",
          "like": "[concat(parameters('prefix'), '*', parameters('suffix'))]"
        }
      },
      "then": {
        "effect": "deny"
      }
    }
  }
}

Respuesta de muestra

status code:: 201

{
  "name": "ResourceNaming",
  "type": "Microsoft.Authorization/policyDefinitions",
  "id": "/subscriptions/ae640e6b-ba3e-4256-9d62-2993eecfa6f2/providers/Microsoft.Authorization/policyDefinitions/ResourceNaming",
  "properties": {
    "description": "Force resource names to begin with 'prefix' and end with 'suffix'",
    "displayName": "Naming Convention",
    "metadata": {
      "category": "Naming"
    },
    "mode": "All",
    "parameters": {
      "prefix": {
        "type": "String",
        "metadata": {
          "description": "Resource name prefix",
          "displayName": "Prefix"
        }
      },
      "suffix": {
        "type": "String",
        "metadata": {
          "description": "Resource name suffix",
          "displayName": "Suffix"
        }
      }
    },
    "policyRule": {
      "if": {
        "not": {
          "field": "name",
          "like": "[concat(parameters('prefix'), '*', parameters('suffix'))]"
        }
      },
      "then": {
        "effect": "deny"
      }
    },
    "policyType": "Custom",
    "version": "1.2.1",
    "versions": [
      "1.2.1",
      "1.0.0"
    ]
  }
}

Create or update a policy definition with advanced parameters

Solicitud de ejemplo

HTTP

PUT https://management.azure.com/subscriptions/ae640e6b-ba3e-4256-9d62-2993eecfa6f2/providers/Microsoft.Authorization/policyDefinitions/EventHubDiagnosticLogs?api-version=2025-11-01

{
  "properties": {
    "description": "Audit enabling of logs and retain them up to a year. This enables recreation of activity trails for investigation purposes when a security incident occurs or your network is compromised",
    "displayName": "Event Hubs should have diagnostic logging enabled",
    "metadata": {
      "category": "Event Hub"
    },
    "mode": "Indexed",
    "parameters": {
      "requiredRetentionDays": {
        "type": "Integer",
        "allowedValues": [
          0,
          30,
          90,
          180,
          365
        ],
        "defaultValue": 365,
        "metadata": {
          "description": "The required diagnostic logs retention in days",
          "displayName": "Required retention (days)"
        }
      }
    },
    "policyRule": {
      "if": {
        "equals": "Microsoft.EventHub/namespaces",
        "field": "type"
      },
      "then": {
        "effect": "AuditIfNotExists",
        "details": {
          "type": "Microsoft.Insights/diagnosticSettings",
          "existenceCondition": {
            "allOf": [
              {
                "equals": "true",
                "field": "Microsoft.Insights/diagnosticSettings/logs[*].retentionPolicy.enabled"
              },
              {
                "equals": "[parameters('requiredRetentionDays')]",
                "field": "Microsoft.Insights/diagnosticSettings/logs[*].retentionPolicy.days"
              }
            ]
          }
        }
      }
    }
  }
}

Respuesta de muestra

status code:: 201

{
  "name": "ResourceNaming",
  "type": "Microsoft.Authorization/policyDefinitions",
  "id": "/subscriptions/ae640e6b-ba3e-4256-9d62-2993eecfa6f2/providers/Microsoft.Authorization/policyDefinitions/ResourceNaming",
  "properties": {
    "description": "Audit enabling of logs and retain them up to a year. This enables recreation of activity trails for investigation purposes when a security incident occurs or your network is compromised",
    "displayName": "Event Hubs should have diagnostic logging enabled",
    "metadata": {
      "category": "Event Hub"
    },
    "mode": "Indexed",
    "parameters": {
      "requiredRetentionDays": {
        "type": "Integer",
        "allowedValues": [
          0,
          30,
          90,
          180,
          365
        ],
        "defaultValue": 365,
        "metadata": {
          "description": "The required diagnostic logs retention in days",
          "displayName": "Required retention (days)"
        }
      }
    },
    "policyRule": {
      "if": {
        "equals": "Microsoft.EventHub/namespaces",
        "field": "type"
      },
      "then": {
        "effect": "AuditIfNotExists",
        "details": {
          "type": "Microsoft.Insights/diagnosticSettings",
          "existenceCondition": {
            "allOf": [
              {
                "equals": "true",
                "field": "Microsoft.Insights/diagnosticSettings/logs[*].retentionPolicy.enabled"
              },
              {
                "equals": "[parameters('requiredRetentionDays')]",
                "field": "Microsoft.Insights/diagnosticSettings/logs[*].retentionPolicy.days"
              }
            ]
          }
        }
      }
    },
    "version": "1.2.1",
    "versions": [
      "1.2.1",
      "1.0.0"
    ]
  }
}

Create or update a policy definition with external evaluation enforcement settings

Solicitud de ejemplo

HTTP

PUT https://management.azure.com/subscriptions/ae640e6b-ba3e-4256-9d62-2993eecfa6f2/providers/Microsoft.Authorization/policyDefinitions/RandomizeVMAllocation?api-version=2025-11-01

{
  "properties": {
    "description": "Randomly disable VM allocation in eastus by having policy rule reference the outcome of invoking an external endpoint using the CoinFlip endpoint that returns random values.",
    "displayName": "Randomize VM Allocation",
    "externalEvaluationEnforcementSettings": {
      "endpointSettings": {
        "kind": "CoinFlip",
        "details": {
          "successProbability": 0.5
        }
      },
      "missingTokenAction": "audit",
      "roleDefinitionIds": [
        "subscriptions/ae640e6b-ba3e-4256-9d62-2993eecfa6f2/providers/Microsoft.Authorization/roleDefinitions/f0cc2aea-b517-48f6-8f9e-0c01c687907b"
      ]
    },
    "metadata": {
      "category": "VM"
    },
    "mode": "Indexed",
    "policyRule": {
      "if": {
        "allOf": [
          {
            "equals": "Microsoft.Compute/virtualMachines",
            "field": "type"
          },
          {
            "equals": "eastus",
            "field": "location"
          },
          {
            "equals": "false",
            "value": "[claims().isValid]"
          }
        ]
      },
      "then": {
        "effect": "deny"
      }
    }
  }
}

Respuesta de muestra

status code:: 201

{
  "name": "RandomizeVMAllocation",
  "type": "Microsoft.Authorization/policyDefinitions",
  "id": "/subscriptions/ae640e6b-ba3e-4256-9d62-2993eecfa6f2/providers/Microsoft.Authorization/policyDefinitions/RandomizeVMAllocation",
  "properties": {
    "description": "Randomly disable VM allocation in eastus by having policy rule reference the outcome of invoking an external endpoint using the CoinFlip endpoint that returns random values.",
    "displayName": "Randomize VM Allocation",
    "externalEvaluationEnforcementSettings": {
      "endpointSettings": {
        "kind": "CoinFlip",
        "details": {
          "successProbability": 0.5
        }
      },
      "missingTokenAction": "audit",
      "roleDefinitionIds": [
        "subscriptions/ae640e6b-ba3e-4256-9d62-2993eecfa6f2/providers/Microsoft.Authorization/roleDefinitions/f0cc2aea-b517-48f6-8f9e-0c01c687907b"
      ]
    },
    "metadata": {
      "category": "VM"
    },
    "mode": "Indexed",
    "policyRule": {
      "if": {
        "allOf": [
          {
            "equals": "Microsoft.Compute/virtualMachines",
            "field": "type"
          },
          {
            "equals": "eastus",
            "field": "location"
          },
          {
            "equals": "false",
            "value": "[claims().isValid]"
          }
        ]
      },
      "then": {
        "effect": "deny"
      }
    },
    "policyType": "Custom",
    "version": "1.2.1",
    "versions": [
      "1.2.1",
      "1.0.0"
    ]
  }
}

Definiciones

Nombre	Description
createdByType	Tipo de identidad que creó el recurso.
ErrorAdditionalInfo	Información adicional sobre el error de administración de recursos.
ErrorDetail	Detalle del error.
ErrorResponse	Respuesta de error
ExternalEvaluationEndpointSettings	La configuración de un punto de conexión externo que proporciona resultados de evaluación.
ExternalEvaluationEnforcementSettings	Los detalles del origen de los resultados de evaluación externa requeridos por la directiva durante la evaluación de cumplimiento.
ParameterDefinitionsValue	La definición de un parámetro que puede proporcionarse a la póliza.
ParameterDefinitionsValueMetadata	Metadatos generales para el parámetro .
ParameterType	Tipo de datos del parámetro.
PolicyDefinition	La definición de la política.
PolicyType	Tipo de definición de directiva. Los valores posibles son NotSpecified, BuiltIn, Custom y Static.
systemData	Metadatos relativos a la creación y última modificación del recurso.

createdByType

Enumeración

Tipo de identidad que creó el recurso.

Valor	Description
User
Application
ManagedIdentity
Key

ErrorAdditionalInfo

Objeto

Información adicional sobre el error de administración de recursos.

Nombre	Tipo	Description
info	object	Información adicional.
type	string	Tipo de información adicional.

ErrorDetail

Objeto

Detalle del error.

Nombre	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	Información adicional del error.
code	string	Código de error.
details	ErrorDetail[]	Detalles del error.
message	string	El mensaje de error.
target	string	Destino del error.

ErrorResponse

Objeto

Respuesta de error

Nombre	Tipo	Description
error	ErrorDetail	Objeto de error.

ExternalEvaluationEndpointSettings

Objeto

La configuración de un punto de conexión externo que proporciona resultados de evaluación.

Nombre	Tipo	Description
details		Detalles del punto de conexión.
kind	string	El tipo del punto de conexión.

ExternalEvaluationEnforcementSettings

Objeto

Los detalles del origen de los resultados de evaluación externa requeridos por la directiva durante la evaluación de cumplimiento.

Nombre	Tipo	Description
endpointSettings	ExternalEvaluationEndpointSettings	La configuración de un punto de conexión externo que proporciona resultados de evaluación.
missingTokenAction	string	Qué hacer al evaluar una directiva de cumplimiento que requiere una evaluación externa y falta el token. Los valores posibles son Audit y Deny y se admiten expresiones de lenguaje.
resultLifespan	string	La duración del resultado de la invocación del punto de conexión después del cual ya no es válido. Se espera que el valor siga el formato de duración ISO 8601 y se admiten expresiones de lenguaje.
roleDefinitionIds	string[]	Para invocar el punto de conexión, necesitará una matriz de los identificadores de definición de rol que necesitará el MSI de la asignación.

ParameterDefinitionsValue

Objeto

La definición de un parámetro que puede proporcionarse a la póliza.

Nombre	Tipo	Description
allowedValues	AllowedValues[]	Valores permitidos para el parámetro .
defaultValue		Valor predeterminado del parámetro si no se proporciona ningún valor.
metadata	ParameterDefinitionsValueMetadata	Metadatos generales para el parámetro .
schema		Proporciona validación de entradas de parámetro durante la asignación mediante un esquema JSON autodefinido. Esta propiedad solo es compatible con parámetros de tipo objeto y sigue la implementación del Esquema Json.NET 2019-09. Puedes aprender más sobre el uso de esquemas en https://json-schema.org/ y borradores de prueba en https://www.jsonschemavalidator.net/.
type	ParameterType	Tipo de datos del parámetro.

ParameterDefinitionsValueMetadata

Objeto

Metadatos generales para el parámetro .

Nombre	Tipo	Description
assignPermissions	boolean	Configura en true para que el portal Azure genere asignaciones de roles sobre el ID de recurso o el valor del alcance de este parámetro durante la asignación de políticas. Esta propiedad es útil en caso de que desee asignar permisos fuera del ámbito de asignación.
description	string	Descripción del parámetro .
displayName	string	Nombre para mostrar del parámetro.
strongType	string	Se usa al asignar la definición de directiva a través del portal. Proporciona una lista con reconocimiento de contexto de valores entre los que el usuario puede elegir.

ParameterType

Enumeración

Tipo de datos del parámetro.

Valor	Description
String	El tipo de parámetro de cadena.
Array	El tipo de parámetro del array.
Object	El tipo de parámetro del objeto.
Boolean	El tipo de parámetro booleano.
Integer	El tipo de parámetro entero.
Float	El tipo de parámetro flotante.
DateTime	El tipo de parámetro fecha-hora.