Policy Definitions - Create Or Update

Dienst:: Policy

API-Version:: 2025-11-01

Diese Operation erstellt oder aktualisiert eine Richtliniendefinition im gegebenen Abonnement mit dem gegebenen Namen.

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

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
policyDefinitionName	path	True	string pattern: ^[^<>%&:\?.+/][^<>*%&:\?.+/ ]+$	Der Name der abzurufenden Richtliniendefinition.
subscriptionId	path	True	string (uuid)	Hierbei handelt es sich um die ID des Zielabonnements. Der Wert muss eine UUID sein.
api-version	query	True	string minLength: 1	Die API-Version, die für diesen Vorgang verwendet werden soll.

Anforderungstext

Name	Typ	Beschreibung
properties.description	string	Die Beschreibung der Richtliniendefinition.
properties.displayName	string	Der Anzeigename der Richtliniendefinition.
properties.externalEvaluationEnforcementSettings	ExternalEvaluationEnforcementSettings	Die Details der Quelle externer Auswertungsergebnisse, die von der Richtlinie während der Erzwingungsbewertung benötigt werden.
properties.metadata		Die Metadaten der Richtliniendefinition. Metadaten sind ein offenes beendetes Objekt und sind in der Regel eine Sammlung von Schlüsselwertpaaren.
properties.mode	string	Der Richtliniendefinitionsmodus. Einige Beispiele sind "All", "Indexed", "Microsoft.KeyVault.Data".
properties.parameters	<string, ParameterDefinitionsValue>	Die Parameterdefinitionen für Parameter, die in der Richtlinienregel verwendet werden. Die Schlüssel sind die Parameternamen.
properties.policyRule		Die Richtlinienregel.
properties.policyType	PolicyType	Der Typ der Richtliniendefinition. Mögliche Werte sind NotSpecified, BuiltIn, Custom und Static.
properties.version	string	Die Richtliniendefinitionsversion im #.#.#.#-Format.
properties.versions	string[]	Eine Liste der verfügbaren Versionen für diese Richtliniendefinition.

Antworten

Name	Typ	Beschreibung
201 Created	PolicyDefinition	Die Erstellungsoperation der Ressource 'PolicyDefinition' war erfolgreich
Other Status Codes	ErrorResponse	Unerwartete Fehlerantwort.

Sicherheit

azure_auth

Azure Active Directory OAuth2 Flow.

Typ: oauth2
Ablauf: implicit
Autorisierungs-URL: https://login.microsoftonline.com/common/oauth2/authorize

Bereiche

Name	Beschreibung
user_impersonation	Identitätswechsel ihres Benutzerkontos

Beispiele

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

Beispielanforderung

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

Beispiel für eine Antwort

Statuscode:: 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

Beispielanforderung

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

Beispiel für eine Antwort

Statuscode:: 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

Beispielanforderung

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

Beispiel für eine Antwort

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

Definitionen

Name	Beschreibung
createdByType	Der Identitätstyp, der die Ressource erstellt hat.
ErrorAdditionalInfo	Der Ressourcenverwaltungsfehler zusätzliche Informationen.
ErrorDetail	Das Fehlerdetails.
ErrorResponse	Fehlerantwort
ExternalEvaluationEndpointSettings	Die Einstellungen eines externen Endpunkts, der Auswertungsergebnisse bereitstellt.
ExternalEvaluationEnforcementSettings	Die Details der Quelle externer Auswertungsergebnisse, die von der Richtlinie während der Erzwingungsbewertung benötigt werden.
ParameterDefinitionsValue	Die Definition eines Parameters, der der Policy bereitgestellt werden kann.
ParameterDefinitionsValueMetadata	Allgemeine Metadaten für den Parameter.
ParameterType	Der Datentyp des Parameters.
PolicyDefinition	Die Definition der Police.
PolicyType	Der Typ der Richtliniendefinition. Mögliche Werte sind NotSpecified, BuiltIn, Custom und Static.
systemData	Metadaten zur Erstellung und letzten Änderung der Ressource.

createdByType

Enumeration

Der Identitätstyp, der die Ressource erstellt hat.

Wert	Beschreibung
User
Application
ManagedIdentity
Key

ErrorAdditionalInfo

Objekt

Der Ressourcenverwaltungsfehler zusätzliche Informationen.

Name	Typ	Beschreibung
info	object	Die zusätzlichen Informationen.
type	string	Der zusätzliche Informationstyp.

ErrorDetail

Objekt

Das Fehlerdetails.

Name	Typ	Beschreibung
additionalInfo	ErrorAdditionalInfo[]	Die zusätzlichen Informationen des Fehlers.
code	string	Der Fehlercode.
details	ErrorDetail[]	Die Fehlerdetails.
message	string	Die Fehlermeldung.
target	string	Das Fehlerziel.

ErrorResponse

Objekt

Fehlerantwort

Name	Typ	Beschreibung
error	ErrorDetail	Das Fehlerobjekt.

ExternalEvaluationEndpointSettings

Objekt

Die Einstellungen eines externen Endpunkts, der Auswertungsergebnisse bereitstellt.

Name	Typ	Beschreibung
details		Die Details des Endpunkts.
kind	string	Die Art des Endpunkts.

ExternalEvaluationEnforcementSettings

Objekt

Die Details der Quelle externer Auswertungsergebnisse, die von der Richtlinie während der Erzwingungsbewertung benötigt werden.

Name	Typ	Beschreibung
endpointSettings	ExternalEvaluationEndpointSettings	Die Einstellungen eines externen Endpunkts, der Auswertungsergebnisse bereitstellt.
missingTokenAction	string	Was zu tun ist, wenn eine Erzwingungsrichtlinie ausgewertet wird, die eine externe Auswertung erfordert und das Token fehlt. Mögliche Werte sind Audit- und Deny- und Sprachausdrücke werden unterstützt.
resultLifespan	string	Die Lebensdauer des Endpunktaufrufergebnisses, nach dem er nicht mehr gültig ist. Es wird erwartet, dass der Wert dem ISO 8601-Dauerformat entspricht und Sprachausdrücke unterstützt werden.
roleDefinitionIds	string[]	Ein Array der Rollendefinitions-IDs, die die MSI-Datei der Zuordnung benötigt, um den Endpunkt aufzurufen.

ParameterDefinitionsValue

Objekt

Die Definition eines Parameters, der der Policy bereitgestellt werden kann.

Name	Typ	Beschreibung
allowedValues	AllowedValues[]	Die zulässigen Werte für den Parameter.
defaultValue		Der Standardwert für den Parameter, wenn kein Wert angegeben wird.
metadata	ParameterDefinitionsValueMetadata	Allgemeine Metadaten für den Parameter.
schema		Stellt die Überprüfung von Parametereingaben während der Zuweisung mithilfe eines selbst definierten JSON-Schemas bereit. Diese Eigenschaft wird nur für Objekttypparameter unterstützt und folgt der Implementierung des JsonNET Schema 2019-09. Mehr über die Verwendung von Schemata kannst du bei https://json-schema.org/ lernen und Entwurfsschemata testen bei https://www.jsonschemavalidator.net/.
type	ParameterType	Der Datentyp des Parameters.

ParameterDefinitionsValueMetadata

Objekt

Allgemeine Metadaten für den Parameter.

Name	Typ	Beschreibung
assignPermissions	boolean	Setzen Sie auf true, damit das Azure Portal während der Richtlinienzuweisung Rollenzuweisungen auf der Ressourcen-ID oder dem Ressourcenumfangswert dieses Parameters erstellt. Diese Eigenschaft ist nützlich, falls Sie Berechtigungen außerhalb des Zuordnungsbereichs zuweisen möchten.
description	string	Die Beschreibung des Parameters.
displayName	string	Der Anzeigename für den Parameter.
strongType	string	Wird beim Zuweisen der Richtliniendefinition über das Portal verwendet. Stellt eine kontextbezogene Liste mit Werten bereit, aus der der Benutzer auswählen kann.

ParameterType

Enumeration

Der Datentyp des Parameters.

Wert	Beschreibung
String	Der String-Parametertyp.
Array	Der Array-Parametertyp.
Object	Der Objektparametertyp.
Boolean	Der boolesche Parametertyp.
Integer	Der ganzzahlige Parametertyp.
Float	Der Float-Parametertyp.
DateTime	Der Datum-Zeit-Parametertyp.