Policy Definitions - Create Or Update

Servizio:: Policy

Versione API:: 2025-11-01

Questa operazione crea o aggiorna una definizione di policy nell'abbonamento fornito con il nome proprio.

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

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
policyDefinitionName	path	True	string pattern: ^[^<>%&:\?.+/][^<>*%&:\?.+/ ]+$	Nome della definizione di criteri da ottenere.
subscriptionId	path	True	string (uuid)	ID della sottoscrizione di destinazione. Il valore deve essere un UUID.
api-version	query	True	string minLength: 1	Versione dell'API da usare per questa operazione.

Corpo della richiesta

Nome	Tipo	Descrizione
properties.description	string	Descrizione della definizione dei criteri.
properties.displayName	string	Nome visualizzato della definizione dei criteri.
properties.externalEvaluationEnforcementSettings	ExternalEvaluationEnforcementSettings	Dettagli dell'origine dei risultati della valutazione esterna richiesti dai criteri durante la valutazione dell'imposizione.
properties.metadata		Metadati della definizione dei criteri. I metadati sono un oggetto aperto terminato ed è in genere una raccolta di coppie chiave-valore.
properties.mode	string	Modalità di definizione dei criteri. Alcuni esempi sono Tutti, Indicizzati, Microsoft.KeyVault.Data.
properties.parameters	<string, ParameterDefinitionsValue>	Definizioni dei parametri per i parametri usati nella regola dei criteri. Le chiavi sono i nomi dei parametri.
properties.policyRule		Regola dei criteri.
properties.policyType	PolicyType	Tipo di definizione dei criteri. I valori possibili sono NotSpecified, BuiltIn, Custom e Static.
properties.version	string	Versione della definizione dei criteri in formato #.#.# .
properties.versions	string[]	Elenco delle versioni disponibili per questa definizione di criteri.

Risposte

Nome	Tipo	Descrizione
201 Created	PolicyDefinition	Risorsa 'PolicyDefinition' crea l'operazione con successo
Other Status Codes	ErrorResponse	Risposta di errore imprevista.

Sicurezza

azure_auth

Azure Active Directory OAuth2 Flow.

Tipo: oauth2
Flow: implicit
URL di autorizzazione: https://login.microsoftonline.com/common/oauth2/authorize

Ambiti

Nome	Descrizione
user_impersonation	rappresentare l'account utente

Esempio

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

Esempio di richiesta

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"
      }
    }
  }
}

Risposta di esempio

Codice di stato:: 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

Esempio di richiesta

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"
              }
            ]
          }
        }
      }
    }
  }
}

Risposta di esempio

Codice di stato:: 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

Esempio di richiesta

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"
      }
    }
  }
}

Risposta di esempio

Codice di stato:: 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"
    ]
  }
}

Definizioni

Nome	Descrizione
createdByType	Tipo di identità che ha creato la risorsa.
ErrorAdditionalInfo	Informazioni aggiuntive sull'errore di gestione delle risorse.
ErrorDetail	Dettagli dell'errore.
ErrorResponse	Risposta di errore
ExternalEvaluationEndpointSettings	Impostazioni di un endpoint esterno che forniscono risultati di valutazione.
ExternalEvaluationEnforcementSettings	Dettagli dell'origine dei risultati della valutazione esterna richiesti dai criteri durante la valutazione dell'imposizione.
ParameterDefinitionsValue	La definizione di un parametro che può essere fornito alla policy.
ParameterDefinitionsValueMetadata	Metadati generali per il parametro .
ParameterType	Tipo di dati del parametro.
PolicyDefinition	La definizione della politica.
PolicyType	Tipo di definizione dei criteri. I valori possibili sono NotSpecified, BuiltIn, Custom e Static.
systemData	Metadati relativi alla creazione e all'ultima modifica della risorsa.

createdByType

Enumerazione

Tipo di identità che ha creato la risorsa.

Valore	Descrizione
User
Application
ManagedIdentity
Key

ErrorAdditionalInfo

Oggetto

Informazioni aggiuntive sull'errore di gestione delle risorse.

Nome	Tipo	Descrizione
info	object	Informazioni aggiuntive.
type	string	Tipo di informazioni aggiuntive.

ErrorDetail

Oggetto

Dettagli dell'errore.

Nome	Tipo	Descrizione
additionalInfo	ErrorAdditionalInfo[]	Informazioni aggiuntive sull'errore.
code	string	Codice di errore.
details	ErrorDetail[]	Dettagli dell'errore.
message	string	Messaggio di errore.
target	string	Destinazione dell'errore.

ErrorResponse

Oggetto

Risposta di errore

Nome	Tipo	Descrizione
error	ErrorDetail	Oggetto error.

ExternalEvaluationEndpointSettings

Oggetto

Impostazioni di un endpoint esterno che forniscono risultati di valutazione.

Nome	Tipo	Descrizione
details		Dettagli dell'endpoint.
kind	string	Tipo di endpoint.

ExternalEvaluationEnforcementSettings

Oggetto

Dettagli dell'origine dei risultati della valutazione esterna richiesti dai criteri durante la valutazione dell'imposizione.

Nome	Tipo	Descrizione
endpointSettings	ExternalEvaluationEndpointSettings	Impostazioni di un endpoint esterno che forniscono risultati di valutazione.
missingTokenAction	string	Cosa fare quando si valuta un criterio di imposizione che richiede una valutazione esterna e il token non è presente. I valori possibili sono Audit e Deny e le espressioni di linguaggio sono supportate.
resultLifespan	string	Durata del risultato della chiamata dell'endpoint dopo la quale non è più valida. È previsto che il valore segua il formato di durata ISO 8601 e le espressioni di linguaggio siano supportate.
roleDefinitionIds	string[]	Per richiamare l'endpoint, una matrice della definizione del ruolo ID dell'identità del servizio gestito dell'assegnazione.

ParameterDefinitionsValue

Oggetto

La definizione di un parametro che può essere fornito alla policy.

Nome	Tipo	Descrizione
allowedValues	AllowedValues[]	Valori consentiti per il parametro .
defaultValue		Valore predefinito per il parametro se non viene specificato alcun valore.
metadata	ParameterDefinitionsValueMetadata	Metadati generali per il parametro .
schema		Fornisce la convalida degli input dei parametri durante l'assegnazione usando uno schema JSON self-defined. Questa proprietà è supportata solo per i parametri di tipo oggetto e segue l'implementazione dello schema Json.NET 2019-09. Puoi imparare di più sull'uso degli schemi a https://json-schema.org/ e a test draft degli schemi a https://www.jsonschemavalidator.net/.
type	ParameterType	Tipo di dati del parametro.

ParameterDefinitionsValueMetadata

Oggetto

Metadati generali per il parametro .

Nome	Tipo	Descrizione
assignPermissions	boolean	Imposta su true per far sì che il portale Azure crei assegnazioni di ruolo sull'ID risorsa o sul valore dell'ambito della risorsa di questo parametro durante l'assegnazione delle policy. Questa proprietà è utile nel caso in cui si desideri assegnare autorizzazioni all'esterno dell'ambito di assegnazione.
description	string	Descrizione del parametro.
displayName	string	Nome visualizzato per il parametro.
strongType	string	Usato quando si assegna la definizione dei criteri tramite il portale. Fornisce un elenco di valori con riconoscimento del contesto tra cui scegliere l'utente.

ParameterType

Enumerazione

Tipo di dati del parametro.

Valore	Descrizione
String	Il tipo di parametro stringa.
Array	Il tipo di parametro dell'array.
Object	Il tipo di parametro oggetto.
Boolean	Il tipo di parametro booleano.
Integer	Il tipo di parametro intero.
Float	Il tipo di parametro float.
DateTime	Il tipo di parametro data-ora.