创建 governanceRoleAssignmentRequest

  • 项目

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

警告

面向 Azure 资源的此版本特权标识管理 (PIM) API 即将弃用。 请使用新的 面向 Azure 资源角色的 Azure REST PIM API。

创建角色分配请求以表示对角色分配所需的操作。 下表列出了这些操作。

操作 类型
分配角色分配 AdminAdd
激活符合条件的角色分配 UserAdd
停用已激活的角色分配 UserRemove
删除角色分配 AdminRemove
更新角色分配 AdminUpdate
请求扩展角色分配 UserExtend
扩展角色分配 AdminExtend
请求续订已过期的角色分配 UserRenew
续订过期的角色分配 AdminRenew

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ❌

权限

下表显示了对每种受支持的资源类型调用此 API 所需的最低特权权限。 请遵循 最佳做法 来请求最低特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

支持的资源 委派（工作或学校帐户） 委派（个人 Microsoft 帐户） 应用程序
Microsoft Entra ID PrivilegedAccess.ReadWrite.AzureAD 不支持。 不支持。
Azure 资源 PrivilegedAccess.ReadWrite.AzureResources 不支持。 不支持。
组 PrivilegedAccess.ReadWrite.AzureADGroup 不支持。 不支持。

HTTP 请求

POST /privilegedAccess/azureResources/roleAssignmentRequests

请求标头

名称 说明
Authorization Bearer {code}
Content-type application/json

请求正文

在请求正文中，提供 governanceRoleAssignmentRequest 对象的 JSON 表示形式。

属性 类型 说明
resourceId String 与角色分配请求关联的 Azure 资源的唯一标识符。 Azure 资源可以包括订阅、资源组、虚拟机和 SQL 数据库。 必填。
roleDefinitionId String 与角色分配请求关联的 Azure 角色定义的标识符。 必填。
subjectId String 与角色分配请求关联的主体或使用者的唯一标识符。 主体可以是用户、组或服务主体。 必填。
assignmentState String 赋值的状态。 该值可以是 Eligible 和 Active。 必填。
type String 请求类型。 该值可以是 AdminAdd、、UserAdd、AdminUpdate、AdminRemoveUserExtendUserRemove、、 UserRenewAdminRenew和 。AdminExtend 必填。
reason String 出于审核和评审目的，需要为角色分配请求提供原因。
schedule governanceSchedule 角色分配请求的计划。 对于 、、 AdminUpdate和 AdminExtend的请求类型UserAddAdminAdd，它是必需的。

响应

如果成功，此方法在 201 Created 响应正文中返回响应代码和 governanceRoleAssignmentRequest 对象。

错误代码

此 API 返回标准 HTTP 错误代码。 此外，它还返回下表中列出的错误代码。

错误代码 错误消息 详细信息
400 BadRequest RoleNotFound roleDefinitionId找不到请求正文中提供的 。
400 BadRequest ResourceIsLocked 请求正文中提供的资源处于 状态 Locked ，无法创建角色分配请求。
400 BadRequest SubjectNotFound subjectId找不到请求正文中提供的 。
400 BadRequest PendingRoleAssignmentRequest 系统中已存在挂起 的 governanceRoleAssignmentRequest 。
400 BadRequest RoleAssignmentExists 请求创建的 governanceRoleAssignment 已存在于系统中。
400 BadRequest RoleAssignmentDoesNotExist 系统中不存在请求更新/扩展的 governanceRoleAssignment 。
400 BadRequest RoleAssignmentRequestPolicyValidationFailed governanceRoleAssignmentRequest 不符合内部策略，无法创建。

示例

以下示例演示如何使用此 API。

示例 1：管理员将用户分配到角色

在此示例中，管理员将用户 nawu@contoso.com 分配到“计费读取者”角色。

注意： 除了权限，此示例还要求请求者在资源上至少有一个 Active 管理员角色分配 (owner 或 user access administrator) 。

属性 类型 必需 值
resourceId String 是 <resourceId>
roleDefinitionId 字符串 是 <roleDefinitionId>
subjectId 字符串 是 <subjectId>
assignmentState 字符串 是 符合条件的/活动
type 字符串 是 AdminAdd
reason String 取决于角色设置
schedule governanceSchedule 是

请求

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "ea48ad5e-e3b0-4d10-af54-39a45bbfe68d",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Eligible",
  "type": "AdminAdd",
  "reason": "Assign an eligible role",
  "schedule": {
    "startDateTime": "2018-05-12T23:37:43.356Z",
    "endDateTime": "2018-11-08T23:37:43.356Z",
    "type": "Once"
  }
}

响应

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "1232e4ea-741a-4be5-8044-5edabdd61672",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "ea48ad5e-e3b0-4d10-af54-39a45bbfe68d",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminAdd",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Evaluate Only",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:37:43.356Z",
    "endDateTime": "2018-11-08T23:37:43.356Z",
    "duration": "PT0S"
  }
}

示例 2：用户激活符合条件的角色

在此示例中，用户 nawu@contoso.com 激活符合条件的计费读取者角色。

属性 类型 必需 值
resourceId String 是 <resourceId>
roleDefinitionId 字符串 是 <roleDefinitionId>
subjectId 字符串 是 <subjectId>
assignmentState 字符串 是 活动
type 字符串 是 UserAdd
reason String 取决于角色设置
schedule governanceSchedule 是

请求

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "8b4d1d51-08e9-4254-b0a6-b16177aae376",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Active",
  "type": "UserAdd",
  "reason": "Activate the owner role",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:28:43.537Z",
    "duration": "PT9H"
  },
  "linkedEligibleRoleAssignmentId": "e327f4be-42a0-47a2-8579-0a39b025b394"
}

响应

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "3ad49a7c-918e-4d86-9f84-fab28f8658c0",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "8b4d1d51-08e9-4254-b0a6-b16177aae376",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "e327f4be-42a0-47a2-8579-0a39b025b394",
  "type": "UserAdd",
  "assignmentState": "Active",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Activate the owner role",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "EligibilityRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      },
      {
        "key": "JustificationRule",
        "value": "Grant"
      },
      {
        "key": "ActivationDayRule",
        "value": "Grant"
      },
      {
        "key": "ApprovalRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:28:43.537Z",
    "endDateTime": "0001-01-01T00:00:00Z",
    "duration": "PT9H"
  }
}

示例 3：用户停用分配的角色

在此示例中，用户 nawu@contoso.com 停用活动计费读取者角色。

属性 类型 必需 值
resourceId String 是 <resourceId>
roleDefinitionId 字符串 是 <roleDefinitionId>
subjectId 字符串 是 <subjectId>
assignmentState 字符串 是 活动
type 字符串 是 UserRemove
reason 字符串 否
schedule governanceSchedule 否

请求

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "bc75b4e6-7403-4243-bf2f-d1f6990be122",
  "resourceId": "fb016e3a-c3ed-4d9d-96b6-a54cd4f0b735",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Active",
  "type": "UserRemove",
  "reason": "Deactivate the role",
  "linkedEligibleRoleAssignmentId": "cb8a533e-02d5-42ad-8499-916b1e4822ec"
}

响应

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "abfcdb57-8e5d-42a0-ae67-7598b96fddb1",
  "resourceId": "fb016e3a-c3ed-4d9d-96b6-a54cd4f0b735",
  "roleDefinitionId": "bc75b4e6-7403-4243-bf2f-d1f6990be122",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "cb8a533e-02d5-42ad-8499-916b1e4822ec",
  "type": "UserRemove",
  "assignmentState": "Active",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Evaluate only",
  "schedule": null,
  "status": {
    "status": "Closed",
    "subStatus": "Revoked",
    "statusDetails": []
  }
}

示例 4：管理员从角色中删除用户

在此示例中，管理员将用户 nawu@contoso.com 从“计费读取者”角色中删除。

注意： 除了权限，此示例还要求请求者在资源上至少有一个 Active 管理员角色分配 (owner 或 user access administrator) 。

属性 类型 必需 值
resourceId String 是 <resourceId>
roleDefinitionId 字符串 是 <roleDefinitionId>
subjectId 字符串 是 <subjectId>
assignmentState 字符串 是 符合条件的/活动
type 字符串 是 AdminRemove
reason 字符串 否
schedule governanceSchedule 否

请求

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "65bb4622-61f5-4f25-9d75-d0e20cf92019",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "assignmentState": "Eligible",
  "type": "AdminRemove"
}

响应

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "c934fcb9-cf53-42ac-a8b4-6246f6726299",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "65bb4622-61f5-4f25-9d75-d0e20cf92019",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminRemove",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": null,
  "status": {
    "status": "Closed",
    "subStatus": "Revoked",
    "statusDetails": []
  },
  "schedule": null
}

示例 5：管理员更新角色分配

在此示例中，管理员将用户 nawu@contoso.com 的角色分配更新为所有者。

注意： 除了权限，此示例还要求请求者在资源上至少有一个 Active 管理员角色分配 (owner 或 user access administrator) 。

属性 类型 必需 值
resourceId String 是 <resourceId>
roleDefinitionId 字符串 是 <roleDefinitionId>
subjectId 字符串 是 <subjectId>
assignmentState 字符串 是 符合条件的/活动
type 字符串 是 AdminUpdate
reason String 依赖于 roleSettings
schedule governanceSchedule 是

请求

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "70521f3e-3b95-4e51-b4d2-a2f485b02103",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "1566d11d-d2b6-444a-a8de-28698682c445",
  "assignmentState": "Eligible",
  "type": "AdminUpdate",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-03-08T05:42:45.317Z",
    "endDateTime": "2018-06-05T05:42:31.000Z"
  }
}

响应

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "4f6d4802-b3ac-4f5a-86d7-a6a4edd7d383",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "70521f3e-3b95-4e51-b4d2-a2f485b02103",
  "subjectId": "1566d11d-d2b6-444a-a8de-28698682c445",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminUpdate",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": null,
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-03-08T05:42:45.317Z",
    "endDateTime": "2018-06-05T05:42:31Z",
    "duration": "PT0S"
  }
}

示例 6：管理员扩展即将过期的角色分配

此示例将用户 ANUJCUSER 即将过期的角色分配扩展到API 管理服务参与者。

注意： 除了权限，此示例还要求请求者在资源上至少有一个 Active 管理员角色分配 (owner 或 user access administrator) 。

属性 类型 必需 值
resourceId String 是 <resourceId>
roleDefinitionId 字符串 是 <roleDefinitionId>
subjectId 字符串 是 <subjectId>
assignmentState 字符串 是 符合条件的/活动
type 字符串 是 AdminExtend
reason String 依赖于 roleSettings
schedule governanceSchedule 是

请求

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "0e88fd18-50f5-4ee1-9104-01c3ed910065",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "assignmentState": "Eligible",
  "type": "AdminExtend",
  "reason": "extend role assignment",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:53:55.327Z",
    "endDateTime": "2018-08-10T23:53:55.327Z"
  }
}

响应

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "486f0c05-47c8-4498-9c06-086a78c83004",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "0e88fd18-50f5-4ee1-9104-01c3ed910065",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminExtend",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "extend role assignment",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:53:55.327Z",
    "endDateTime": "2018-08-10T23:53:55.327Z",
    "duration": "PT0S"
  }
}