Tworzenie lub aktualizowanie ról niestandardowych platformy Azure przy użyciu interfejsu API REST

Artykuł
12/09/2023

Jeśli wbudowane role platformy Azure nie spełniają konkretnych potrzeb organizacji, możesz utworzyć własne role niestandardowe. W tym artykule opisano sposób tworzenia, aktualizowania lub usuwania ról niestandardowych przy użyciu interfejsu API REST.

Wymagania wstępne

Należy użyć następującej wersji:

2015-07-01 lub nowsze

Aby uzyskać więcej informacji, zobacz Wersje interfejsów API rest kontroli dostępu opartej na rolach platformy Azure.

Wyświetlanie listy wszystkich definicji ról niestandardowych

Aby wyświetlić listę wszystkich definicji ról niestandardowych w dzierżawie, użyj interfejsu API REST definicji ról — lista .

W poniższym przykładzie wymieniono wszystkie niestandardowe definicje ról w dzierżawie:

Zażądaj

GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01

Response

{
    "value": [
        {
            "properties": {
                "roleName": "Billing Reader Plus",
                "type": "CustomRole",
                "description": "Read billing data and download invoices",
                "assignableScopes": [
                    "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
                ],
                "permissions": [
                    {
                        "actions": [
                            "Microsoft.Authorization/*/read",
                            "Microsoft.Billing/*/read",
                            "Microsoft.Commerce/*/read",
                            "Microsoft.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.CostManagement/*/read",
                            "Microsoft.Billing/invoices/download/action",
                            "Microsoft.CostManagement/exports/*"
                        ],
                        "notActions": [
                            "Microsoft.CostManagement/exports/delete"
                        ],
                        "dataActions": [],
                        "notDataActions": []
                    }
                ],
                "createdOn": "2021-05-22T21:57:23.5764138Z",
                "updatedOn": "2021-05-22T21:57:23.5764138Z",
                "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
                "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
            },
            "id": "/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
            "type": "Microsoft.Authorization/roleDefinitions",
            "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
        }
    ]
}

Wyświetlanie listy wszystkich definicji ról niestandardowych w zakresie

Aby wyświetlić listę niestandardowych definicji ról w zakresie, użyj interfejsu API REST Definicji ról — lista .

Zacznij od następującego żądania:

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01

W identyfikatorze URI zastąp element {scope} zakresem, dla którego chcesz wyświetlić listę ról.

Scope	Typ
`subscriptions/{subscriptionId1}`	Subskrypcja
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupa zasobów
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Zasób
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupa zarządzania

Zastąp element {filter} typem roli.

Filtr	opis
`$filter=type+eq+'CustomRole'`	Filtruj na podstawie typu CustomRole

W poniższym przykładzie wymieniono wszystkie niestandardowe definicje ról w subskrypcji:

Zażądaj

GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01

Response

{
    "value": [
        {
            "properties": {
                "roleName": "Billing Reader Plus",
                "type": "CustomRole",
                "description": "Read billing data and download invoices",
                "assignableScopes": [
                    "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
                ],
                "permissions": [
                    {
                        "actions": [
                            "Microsoft.Authorization/*/read",
                            "Microsoft.Billing/*/read",
                            "Microsoft.Commerce/*/read",
                            "Microsoft.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.CostManagement/*/read",
                            "Microsoft.Billing/invoices/download/action",
                            "Microsoft.CostManagement/exports/*"
                        ],
                        "notActions": [
                            "Microsoft.CostManagement/exports/delete"
                        ],
                        "dataActions": [],
                        "notDataActions": []
                    }
                ],
                "createdOn": "2021-05-22T21:57:23.5764138Z",
                "updatedOn": "2021-05-22T21:57:23.5764138Z",
                "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
                "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
            },
            "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
            "type": "Microsoft.Authorization/roleDefinitions",
            "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
        }
    ]
}

Wyświetlanie listy niestandardowej definicji roli według nazwy

Aby uzyskać informacje o niestandardowej definicji roli według jego nazwy wyświetlanej , użyj definicji ról — pobierz interfejs API REST.

Zacznij od następującego żądania:

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01

W identyfikatorze URI zastąp element {scope} zakresem, dla którego chcesz wyświetlić listę ról.

Scope	Typ
`subscriptions/{subscriptionId1}`	Subskrypcja
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupa zasobów
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Zasób
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupa zarządzania

Zastąp element {filter} nazwą wyświetlaną roli.

Filtr	opis
`$filter=roleName+eq+'{roleDisplayName}'`	Użyj zakodowanej pod adresem URL postaci dokładnej nazwy wyświetlanej roli. Na przykład `$filter=roleName+eq+'Virtual%20Machine%20Contributor'`

W poniższym przykładzie wymieniono niestandardową definicję roli o nazwie Czytelnik rozliczeń Plus w subskrypcji:

Zażądaj

GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=roleName+eq+'Billing Reader Plus'&api-version=2022-04-01

Response

{
    "value": [
        {
            "properties": {
                "roleName": "Billing Reader Plus",
                "type": "CustomRole",
                "description": "Read billing data and download invoices",
                "assignableScopes": [
                    "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
                ],
                "permissions": [
                    {
                        "actions": [
                            "Microsoft.Authorization/*/read",
                            "Microsoft.Billing/*/read",
                            "Microsoft.Commerce/*/read",
                            "Microsoft.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.CostManagement/*/read",
                            "Microsoft.Billing/invoices/download/action",
                            "Microsoft.CostManagement/exports/*"
                        ],
                        "notActions": [
                            "Microsoft.CostManagement/exports/delete"
                        ],
                        "dataActions": [],
                        "notDataActions": []
                    }
                ],
                "createdOn": "2021-05-22T21:57:23.5764138Z",
                "updatedOn": "2021-05-22T21:57:23.5764138Z",
                "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
                "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
            },
            "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
            "type": "Microsoft.Authorization/roleDefinitions",
            "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
        }
    ]
}

Wyświetlanie listy niestandardowej definicji roli według identyfikatora

Aby uzyskać informacje o niestandardowej definicji roli według jego unikatowego identyfikatora, użyj definicji ról — pobierz interfejs API REST.

Użyj interfejsu API REST definicji ról — lista , aby uzyskać identyfikator GUID roli.

Zacznij od następującego żądania:

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

W identyfikatorze URI zastąp element {scope} zakresem, dla którego chcesz wyświetlić listę ról.

Scope	Typ
`subscriptions/{subscriptionId1}`	Subskrypcja
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupa zasobów
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	Zasób
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupa zarządzania

Zastąp element {roleDefinitionId} identyfikatorem GUID definicji roli.

Poniższy przykład zawiera listę niestandardowej definicji roli z identyfikatorem 17adabda-4bf1-4f4e-8c97-1f0cab6dea1c w subskrypcji:

Zażądaj

GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c?api-version=2022-04-01

Response

{
    "properties": {
        "roleName": "Billing Reader Plus",
        "type": "CustomRole",
        "description": "Read billing data and download invoices",
        "assignableScopes": [
            "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Authorization/*/read",
                    "Microsoft.Billing/*/read",
                    "Microsoft.Commerce/*/read",
                    "Microsoft.Consumption/*/read",
                    "Microsoft.Management/managementGroups/read",
                    "Microsoft.CostManagement/*/read",
                    "Microsoft.Billing/invoices/download/action",
                    "Microsoft.CostManagement/exports/*"
                ],
                "notActions": [
                    "Microsoft.CostManagement/exports/delete"
                ],
                "dataActions": [],
                "notDataActions": []
            }
        ],
        "createdOn": "2021-05-22T21:57:23.5764138Z",
        "updatedOn": "2021-05-22T21:57:23.5764138Z",
        "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
        "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
    },
    "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
    "type": "Microsoft.Authorization/roleDefinitions",
    "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
}

Tworzenie roli niestandardowej

Aby utworzyć rolę niestandardową, użyj definicji ról — tworzenie lub aktualizowanie interfejsu API REST. Aby wywołać ten interfejs API, musisz zalogować się przy użyciu użytkownika, któremu przypisano rolę, która ma Microsoft.Authorization/roleDefinitions/write uprawnienia do wszystkich elementów assignableScopes. W przypadku ról wbudowanych tylko właściciel i dostęp użytkowników Administracja istrator obejmują to uprawnienie.

Przejrzyj listę operacji dostawcy zasobów, które są dostępne do tworzenia uprawnień dla roli niestandardowej.
Użyj narzędzia GUID, aby wygenerować unikatowy identyfikator, który będzie używany dla niestandardowego identyfikatora roli. Identyfikator ma format: 00000000-0000-0000-0000-000000000000

Zacznij od następującego żądania i treści:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

{
  "name": "{roleDefinitionId}",
  "properties": {
    "roleName": "",
    "description": "",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [

        ],
        "notActions": [

        ]
      }
    ],
    "assignableScopes": [
      "/subscriptions/{subscriptionId1}",
      "/subscriptions/{subscriptionId2}",
      "/subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}",
      "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroup2}",
      "/providers/Microsoft.Management/managementGroups/{groupId1}"
    ]
  }
}

W identyfikatorze URI zastąp element {scope} pierwszą assignableScopes rolą niestandardową.

Scope	Typ
`subscriptions/{subscriptionId1}`	Subskrypcja
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupa zasobów
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupa zarządzania

Zastąp element {roleDefinitionId} identyfikatorem GUID roli niestandardowej.
W treści żądania zastąp element {roleDefinitionId} identyfikatorem GUID.
Jeśli assignableScopes jest subskrypcją lub grupą zasobów, zastąp wystąpienia {subscriptionId} lub {resourceGroup} identyfikatorami.
Jeśli assignableScopes jest grupą zarządzania, zastąp wystąpienie {groupId} identyfikatorem grupy zarządzania.
actions W właściwości dodaj akcje, które można wykonać dla roli.
notActions W właściwości dodaj akcje wykluczone z dozwolonego actionselementu .

We właściwościach roleName i description określ unikatową nazwę roli i opis. Aby uzyskać więcej informacji na temat właściwości, zobacz Role niestandardowe platformy Azure.

Poniżej przedstawiono przykład treści żądania:

{
  "name": "88888888-8888-8888-8888-888888888888",
  "properties": {
    "roleName": "Virtual Machine Operator",
    "description": "Can monitor and restart virtual machines.",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [
          "Microsoft.Storage/*/read",
          "Microsoft.Network/*/read",
          "Microsoft.Compute/*/read",
          "Microsoft.Compute/virtualMachines/start/action",
          "Microsoft.Compute/virtualMachines/restart/action",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Support/*"
        ],
        "notActions": []
      }
    ],
    "assignableScopes": [
      "/subscriptions/00000000-0000-0000-0000-000000000000",
      "/providers/Microsoft.Management/managementGroups/marketing-group"
    ]
  }
}

Aktualizacja roli niestandardowej

Aby zaktualizować rolę niestandardową, użyj definicji ról — tworzenie lub aktualizowanie interfejsu API REST. Aby wywołać ten interfejs API, musisz zalogować się przy użyciu użytkownika, któremu przypisano rolę, która ma Microsoft.Authorization/roleDefinitions/write uprawnienia do wszystkich assignableScopeselementów , takich jak Administracja istrator dostępu użytkowników.

Użyj definicji ról — lista lub definicje ról — pobierz interfejs API REST, aby uzyskać informacje o roli niestandardowej. Aby uzyskać więcej informacji, zobacz sekcję Lista wszystkich definicji ról niestandardowych .

Zacznij od następującego żądania:

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

W identyfikatorze URI zastąp element {scope} pierwszą assignableScopes rolą niestandardową.

Scope	Typ
`subscriptions/{subscriptionId1}`	Subskrypcja
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupa zasobów
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupa zarządzania

Zastąp element {roleDefinitionId} identyfikatorem GUID roli niestandardowej.

Na podstawie informacji o roli niestandardowej utwórz treść żądania w następującym formacie:

{
  "name": "{roleDefinitionId}",
  "properties": {
    "roleName": "",
    "description": "",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [

        ],
        "notActions": [

        ]
      }
    ],
    "assignableScopes": [
      "/subscriptions/{subscriptionId1}",
      "/subscriptions/{subscriptionId2}",
      "/subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}",
      "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroup2}",
      "/providers/Microsoft.Management/managementGroups/{groupId1}"
    ]
  }
}

Zaktualizuj treść żądania za pomocą zmian, które chcesz wprowadzić w roli niestandardowej.

Poniżej przedstawiono przykład treści żądania z dodaną nową akcją ustawień diagnostycznych:

{
  "name": "88888888-8888-8888-8888-888888888888",
  "properties": {
    "roleName": "Virtual Machine Operator",
    "description": "Can monitor and restart virtual machines.",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [
          "Microsoft.Storage/*/read",
          "Microsoft.Network/*/read",
          "Microsoft.Compute/*/read",
          "Microsoft.Compute/virtualMachines/start/action",
          "Microsoft.Compute/virtualMachines/restart/action",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Insights/diagnosticSettings/*",
          "Microsoft.Support/*"
        ],
        "notActions": []
      }
    ],
    "assignableScopes": [
      "/subscriptions/00000000-0000-0000-0000-000000000000",
      "/providers/Microsoft.Management/managementGroups/marketing-group"
    ]
  }
}

Usuwanie roli niestandardowej

Aby usunąć rolę niestandardową, użyj definicji ról — usuń interfejs API REST. Aby wywołać ten interfejs API, musisz zalogować się przy użyciu użytkownika, któremu przypisano rolę, która ma Microsoft.Authorization/roleDefinitions/delete uprawnienia do wszystkich elementów assignableScopes. W przypadku ról wbudowanych tylko właściciel i dostęp użytkowników Administracja istrator obejmują to uprawnienie.

Usuń wszystkie przypisania ról, które używają roli niestandardowej. Aby uzyskać więcej informacji, zobacz Znajdowanie przypisań ról w celu usunięcia roli niestandardowej.
Użyj definicji ról — lista lub definicje ról — pobierz interfejs API REST, aby uzyskać identyfikator GUID roli niestandardowej. Aby uzyskać więcej informacji, zobacz sekcję Lista wszystkich definicji ról niestandardowych .

Zacznij od następującego żądania:

DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

W identyfikatorze URI zastąp element {scope} zakresem, który chcesz usunąć rolę niestandardową.

Scope	Typ
`subscriptions/{subscriptionId1}`	Subskrypcja
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Grupa zasobów
`providers/Microsoft.Management/managementGroups/{groupId1}`	Grupa zarządzania

Zastąp element {roleDefinitionId} identyfikatorem GUID roli niestandardowej.

Tworzenie lub aktualizowanie ról niestandardowych platformy Azure przy użyciu interfejsu API REST

Wymagania wstępne

Wyświetlanie listy wszystkich definicji ról niestandardowych

Wyświetlanie listy wszystkich definicji ról niestandardowych w zakresie

Wyświetlanie listy niestandardowej definicji roli według nazwy

Wyświetlanie listy niestandardowej definicji roli według identyfikatora

Tworzenie roli niestandardowej

Aktualizacja roli niestandardowej

Usuwanie roli niestandardowej

Następne kroki

Dodatkowe zasoby