SCIM API(用户)SCIM API (Users)

重要

此功能目前以公共预览版提供。This feature is in Public Preview.

备注

  • Azure Databricks 管理员可以调用所有 SCIM API 终结点。An Azure Databricks administrator can invoke all SCIM API endpoints.
  • 非管理员用户可以调用“获取用户”终结点以读取用户显示名称和 ID。Non-admin users can invoke the Users Get endpoint to read user display names and IDs.

借助 SCIM(用户),可以在 Azure Databricks 中创建用户并为他们提供适当的访问级别;当他们离开你的组织或不再需要访问 Azure Databricks 时,你还可以删除他们的访问权限(将他们取消预配)。SCIM (Users) lets you create users in Azure Databricks and give them the proper level of access and remove access for users (deprovision them) when they leave your organization or no longer need access to Azure Databricks.

获取用户 Get users

端点Endpoint HTTP 方法HTTP Method
2.0/preview/scim/v2/Users GET

管理员用户:在 Azure Databricks 工作区中检索所有用户的列表。Admin users: Retrieve a list of all users in the Azure Databricks workspace.

非管理员用户:检索 Azure Databricks 工作区中所有用户的列表,仅返回用户名、用户显示名称和对象 ID。Non-admin users: Retrieve a list of all users in the Azure Databricks workspace, returning username, user display name, and object ID only.

示例请求Example request

GET /api/2.0/preview/scim/v2/Users  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

可以使用筛选器来指定用户的子集。You can use filters to specify subsets of users. 例如,可以将 eq(“等于”)筛选器参数应用到 userName 以检索特定用户或用户子集:For example, you can apply the eq (equals) filter parameter to userName to retrieve a specific user or subset of users:

GET /api/2.0/preview/scim/v2/Users?filter=userName+eq+example@databricks.com  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

按 ID 获取用户Get user by ID

端点Endpoint HTTP 方法HTTP Method
2.0/preview/scim/v2/Users/{id} GET

管理员用户:在给定 Azure Databricks ID 的情况下,从 Azure Databricks 工作区中检索单个用户资源。Admin users: Retrieve a single user resource from the Azure Databricks workspace, given their Azure Databricks ID.

示例请求Example request

GET /api/2.0/preview/scim/v2/Users/100757  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

示例响应Example response

{
  "entitlements":[
    {
      "value":"allow-cluster-create"
    }
  ],
  "schemas":[
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "groups":[
    {
      "value":"123456"
    }
  ],
  "userName":"example@databricks.com"
}

创建用户Create user

端点Endpoint HTTP 方法HTTP Method
2.0/preview/scim/v2/Users POST

管理员用户:在 Azure Databricks 工作区中创建用户。Admin users: Create a user in the Azure Databricks workspace.

请求参数遵循标准 SCIM 2.0 协议。Request parameters follow the standard SCIM 2.0 protocol.

请求必须包括以下属性:Requests must include the following attributes:

  • schemas 设置为 urn:ietf:params:scim:schemas:core:2.0:Userschemas set to urn:ietf:params:scim:schemas:core:2.0:User
  • userName

示例请求Example request

POST /api/2.0/preview/scim/v2/Users HTTP/1.1
Host: <databricks-instance>
Authorization: Bearer dapi48…a6138b
Content-Type: application/scim+json
{
  "schemas":[
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName":"example@databricks.com",
  "groups":[
    {
       "value":"123456"
    }
  ],
  "entitlements":[
    {
       "value":"allow-cluster-create"
    }
  ]
}

PowerShell 示例PowerShell example

$url = "<databricks-instance>/api/2.0/preview/scim/v2/Users"
$bearer_token = "<token>"
$headers = @{Authorization = "Bearer $bearer_token"}
$par = '{
  "schemas":[
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName":"<username>",
  "displayName":"<firstname lastname>",
  "entitlements":[
    {
    "value":"allow-cluster-create"
    }
  ]
}'

Invoke-WebRequest $url -Method Post -Headers $headers -Body $par -ContentType 'application/json'

按 ID 更新用户 (PATCH)Update user by ID (PATCH)

端点Endpoint HTTP 方法HTTP Method
2.0/preview/scim/v2/Users/{id} PATCH

管理员用户:使用对特定属性(不可变属性 userNameuserId 除外)的操作来更新用户资源。Admin users: Update a user resource with operations on specific attributes, except those that are immutable (userName and userId). 建议使用 PATCH 方法(而不是 PUT 方法)来设置或更新用户权利。The PATCH method is recommended over the PUT method for setting or updating user entitlements.

请求参数遵循标准 SCIM 2.0 协议,并依赖于 schemas 属性的值。Request parameters follow the standard SCIM 2.0 protocol and depend on the value of the schemas attribute.

示例请求Example request

PATCH /api/2.0/preview/scim/v2/Users/100757  HTTP/1.1
Host: <databricks-instance>
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b
{
  "schemas":[
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[
    {
      "op":"add",
      "path":"entitlements",
      "value":[
        {
           "value":"allow-cluster-create"
        }
      ]
    }
  ]
}

按 ID 更新用户 (PUT)Update user by ID (PUT)

端点Endpoint HTTP 方法HTTP Method
2.0/preview/scim/v2/Users/{id} PUT

管理员用户:跨多个属性(不可变属性 userNameuserId 除外)覆盖用户资源。Admin users: Overwrite the user resource across multiple attributes, except those that are immutable (userName and userId).

请求必须包含设置为 urn:ietf:params:scim:schemas:core:2.0:Userschemas 属性。Request must include the schemas attribute, set to urn:ietf:params:scim:schemas:core:2.0:User.

备注

建议使用 PATCH 方法(而不是 PUT 方法)来设置或更新用户权利。The PATCH method is recommended over the PUT method for setting or updating user entitlements.

示例请求Example request

PUT /api/2.0/preview/scim/v2/Users/123456  HTTP/1.1
Host: <region>.databricks.azure.cn
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b
{
  "schemas":[
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName":"example@databricks.com",
  "entitlements":[
    {
       "value":"allow-cluster-create"
    }
  ],
  "groups":[
    {
       "value":"100000"
    }
  ]
}

按 ID 删除用户Delete user by ID

端点Endpoint HTTP 方法HTTP Method
2.0/preview/scim/v2/Users/{id} DELETE

管理员用户:停用用户资源。Admin users: Inactivate a user resource. 不拥有或不属于 Azure Databricks 工作区的用户将在 30 天后被自动清除。A user that does not own or belong to a workspace in Azure Databricks is automatically purged after 30 days.

示例请求Example request

DELETE /api/2.0/preview/scim/v2/Users/100757  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b