1. iModel 用户权限、图像、用户接口说明
权限
接口一、获取 iModel 用户权限
GET https://api.bentley.com/imodels/{id}/permissions
检索用户对指定 iModel 拥有的权限列表。iModels 权限可以在项目级别或 iModel 级别配置。此操作将返回为此特定 iModel 配置的权限,如果未配置 iModel 权限,则返回项目权限。
imodels_webview
- 允许在 web 浏览器中查看 iModel,但不允许在桌面应用程序中获取其本地副本和视图。
imodels_read
- 仅允许在只读状态下打开和查看 iModel。
imodels_write
- 允许对 iModel 进行更改。允许创建和修改命名版本。允许在PW connection 和 iModel 之间创建映射,以方便桥接。
imodels_manage
- 允许创建iModel。允许对 iModel 配置访问权限。允许管理整个 iModel 的锁、代码或本地副本。此权限既是 iModel 权限,也是项目级权限,但创建 iModel 操作要求用户在项目级拥有 imodels_manage
权限。使用 Projects API 检查用户是否可以在给定项目上创建 iModel。
imodels-delete
- 允许删除 iModel。此权限仅在项目级别可用。使用 Projects API 检查用户是否可以删除给定项目上的 iModel。
认证
需要在请求 Header 里包含 Authorization
字段,Authorization
字段要求是有效的且带有 imodels:read
作用域的 Bearer 令牌。
想要了解更多关于授权以及如何获取 access token的细节,请参考这个https://developer.bentley.com/apis/overview/authorization/文档 。
授权
用户必须在 iModel 级别上分配 imodels_webview
的权限,以及至少在项目级别上分配 imodels_webview
权限。如果未配置 iModel 级别的权限,则用户必须在项目级别分配 imodels_webview
权限。
或者,用户应该是此 iModel 所属的项目所在的组织上的组织管理员。
组织管理员必须在用户管理中至少分配以下角色之一:Account Administrator(账户管理员), Co-Administrator(联合管理员), or CONNECT Services Administrator(CONNECT 服务管理员)。想要了解更多有关于用户管理的信息,请查看 Bentley 社区 的 wiki 页面 https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0
接口使用率限制
所有在 iTwin Platform 上的接口都有接口使用率限制。想了解更多相关信息请查看 https://developer.bentley.com/apis/overview/rate-limits/
请求
请求参数
参数名称 | 所在位置 | 是否必须 | 描述 |
---|---|---|---|
id | template | 是 | iModel 的 ID |
请求头
名称 | 是否必须 | 描述 |
---|---|---|
Authorization | 是 | 带有 imodels:read 作用域的 OAuth 访问令牌 |
Accept | 否 | 推荐设置为 application/vnd.bentley.itwin-platform.v1+json |
响应
返回 200 OK:
OK
{ "permissions": [ "imodels_webview", "imodels_read", "imodels_write", "imodels_manage" ] }
返回 401 Unauthorized:
此响应表示请求缺少有效的身份验证凭据。访问令牌可能未提供、或是由错误的颁发者颁发、没有所需的作用域或请求头的格式不正确。
{
"error": {
"code": "Unauthorized",
"message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
}
}
- Response 404 Not Found:
无法找到指定的 iModel
{
"error": {
"code": "iModelNotFound",
"message": "Requested iModel is not available."
}
}
- Response 429 Too many requests:
此响应表示用户在给定的时间内发送了太多请求
{
"error": {
"code": "TooManyRequests",
"message": "More requests were received than the subscription rate-limit allows."
}
}
响应头
名称 | 描述 |
---|---|
retry-after | 超过客户端订阅的速率限制的请求数 |
缩略图
接口一、下载 iModel 缩略图
GET https://api.bentley.com/imodels/{id}/thumbnail[?size]
获取缩略图文件。返回的缩略图的类型为'image/png'
通过在 query 中设定 size 值以获取小/大缩略图。如果为指定 size,会返回小缩略图。
认证
需要在请求 Header 里包含 Authorization
字段,Authorization
字段要求是有效的且带有 imodels:read
作用域的 Bearer 令牌。
想要了解更多关于授权以及如何获取 access token的细节,请参考这个https://developer.bentley.com/apis/overview/authorization/文档 。
授权
用户必须在 iModel 级别上分配 imodels_webview
的权限,以及至少在项目级别上分配 imodels_webview
权限。如果未配置 iModel 级别的权限,则用户必须在项目级别分配 imodels_webview
权限。
或者,用户应该是此 iModel 所属的项目所在的组织上的组织管理员。
组织管理员必须在用户管理中至少分配以下角色之一:Account Administrator(账户管理员), Co-Administrator(联合管理员), or CONNECT Services Administrator(CONNECT 服务管理员)。想要了解更多有关于用户管理的信息,请查看 Bentley 社区 的 wiki 页面 https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0
接口使用率限制
所有在 iTwin Platform 上的接口都有接口使用率限制。想了解更多相关信息请查看 https://developer.bentley.com/apis/overview/rate-limits/
请求
请求参数
参数名称 | 所在位置 | 是否必须 | 描述 |
---|---|---|---|
id | template | 是 | iModel 的 ID |
size | query | 否 | 标识缩略图大小。如未提供值或者传入非法值,默认为 small |
请求头
名称 | 是否必须 | 描述 |
---|---|---|
Authorization | 是 | 带有 imodels:read 作用域的 OAuth 访问令牌 |
Accept | 否 | 推荐设置为 application/vnd.bentley.itwin-platform.v1+json |
响应
返回 200 OK:
OK
返回 401 Unauthorized:
此响应表示请求缺少有效的身份验证凭据。访问令牌可能未提供、或是由错误的颁发者颁发、没有所需的作用域或请求头的格式不正确。
{
"error": {
"code": "Unauthorized",
"message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
}
}
- Response 404 Not Found:
无法找到指定的 iModel
{
"error": {
"code": "iModelNotFound",
"message": "Requested iModel is not available."
}
}
Response 422 Unprocessable Entity:
状态代码表示由于客户端错误(例如,格式错误的请求语法),服务器无法处理请求。
{ "error": { "code": "InvalidiModelsRequest", "message": "Cannot get thumbnail.", "details": [{ "code": "InvalidValue", "message": "'invalidSize' is not a valid 'size'. Valid 'size' values are: 'small', 'large'.", "target": "size" }] } }
Response 429 Too many requests:
此响应表示用户在给定的时间内发送了太多请求
{
"error": {
"code": "TooManyRequests",
"message": "More requests were received than the subscription rate-limit allows."
}
}
响应头
名称 | 描述 |
---|---|
retry-after | 超过客户端订阅的速率限制的请求数 |
接口二、上传 iModel 缩略图
PUT https://api.bentley.com/imodels/{id}/thumbnail
上传缩略图文件。请求内容应该是图像的二进制内容。支持的缩略图类型为“image/png”或“image/jpeg”,但一旦上传,“image/jpeg”将转换为“image/png”。支持的最大缩略图大小为5 MB。
认证
需要在请求 Header 里包含 Authorization
字段,Authorization
字段要求是有效的且带有 imodels:modify
作用域的 Bearer 令牌。
想要了解更多关于授权以及如何获取 access token的细节,请参考这个https://developer.bentley.com/apis/overview/authorization/文档 。
授权
用户必须在 iModel 级别上分配 imodels_manage
的权限,以及至少在项目级别上分配 imodels_webview
权限。如果未配置 iModel 级别的权限,则用户必须在项目级别分配 imodels_manage
权限。
或者,用户应该是此 iModel 所属的项目所在的组织上的组织管理员。
组织管理员必须在用户管理中至少分配以下角色之一:Account Administrator(账户管理员), Co-Administrator(联合管理员), or CONNECT Services Administrator(CONNECT 服务管理员)。想要了解更多有关于用户管理的信息,请查看 Bentley 社区 的 wiki 页面 https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0
接口使用率限制
所有在 iTwin Platform 上的接口都有接口使用率限制。想了解更多相关信息请查看 https://developer.bentley.com/apis/overview/rate-limits/
请求
请求参数
参数名称 | 所在位置 | 是否必须 | 描述 |
---|---|---|---|
id | template | 是 | iModel 的 ID |
请求头
名称 | 是否必须 | 描述 |
---|---|---|
Authorization | 是 | 带有 imodels:read 作用域的 OAuth 访问令牌 |
Accept | 否 | 推荐设置为 application/vnd.bentley.itwin-platform.v1+json |
Content-Type | 是 | 标识请求主体的内容类型 |
请求主体
image
响应
返回 201 Created:
Created
返回 401 Unauthorized:
此响应表示请求缺少有效的身份验证凭据。访问令牌可能未提供、或是由错误的颁发者颁发、没有所需的作用域或请求头的格式不正确。
{
"error": {
"code": "Unauthorized",
"message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
}
}
Response 403 Forbidden:
用户无权上传
{ "error": { "code": "InsufficientPermissions", "message": "The user has insufficient permissions for the requested operation." } }
Response 404 Not Found:
无法找到指定的 iModel
{
"error": {
"code": "iModelNotFound",
"message": "Requested iModel is not available."
}
}
Response 413 Request Entity Too Large:
用户上传的文件超出限制的最大值
{ "error": { "code": "RequestTooLarge", "message": "Provided file is greater than the maximum allowed file size of 5MB." } }
Response 422 Unprocessable Entity:
状态代码表示由于客户端错误(例如,格式错误的请求语法),服务器无法处理请求。
{
"error": {
"code": "InvalidiModelsRequest",
"message": "Cannot upload thumbnail.",
"details": [{
"code": "InvalidRequestBody",
"message": "Invalid thumbnail format. Please use one of the supported media formats: 'image/jpeg', 'image/png'.",
"innerError": {
"code": "InvalidThumbnailFormat"
}
},
{
"code": "MissingRequiredHeader",
"message": "Required header is missing.",
"target": "content-type"
},
{
"code": "InvalidHeaderValue",
"message": "'image/gif' is not supported 'content-type'. Supported media types are 'image/jpeg', 'image/png'.",
"target": "content-type"
}
]
}
}
- Response 429 Too many requests:
此响应表示用户在给定的时间内发送了太多请求
{
"error": {
"code": "TooManyRequests",
"message": "More requests were received than the subscription rate-limit allows."
}
}
响应头
名称 | 描述 |
---|---|
retry-after | 超过客户端订阅的速率限制的请求数 |
用户
接口一、获取 iModel 用户
GET https://api.bentley.com/imodels/{id}/users/{userId}
获取用户的详情。
认证
需要在请求 Header 里包含 Authorization
字段,Authorization
字段要求是有效的且带有 imodels:read
作用域的 Bearer 令牌。
想要了解更多关于授权以及如何获取 access token的细节,请参考这个https://developer.bentley.com/apis/overview/authorization/文档 。
授权
用户必须在 iModel 级别上分配 imodels_webview
的权限,以及至少在项目级别上分配 imodels_webview
权限。如果未配置 iModel 级别的权限,则用户必须在项目级别分配 imodels_webview
权限。
或者,用户应该是此 iModel 所属的项目所在的组织上的组织管理员。
组织管理员必须在用户管理中至少分配以下角色之一:Account Administrator(账户管理员), Co-Administrator(联合管理员), or CONNECT Services Administrator(CONNECT 服务管理员)。想要了解更多有关于用户管理的信息,请查看 Bentley 社区 的 wiki 页面 https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0
接口使用率限制
所有在 iTwin Platform 上的接口都有接口使用率限制。想了解更多相关信息请查看 https://developer.bentley.com/apis/overview/rate-limits/
请求
请求参数
参数名称 | 所在位置 | 是否必须 | 描述 |
---|---|---|---|
id | template | 是 | iModel 的 ID |
userId | template | 是 | 用户 ID |
请求头
名称 | 是否必须 | 描述 |
---|---|---|
Authorization | 是 | 带有 imodels:read 作用域的 OAuth 访问令牌 |
Accept | 否 | 推荐设置为 application/vnd.bentley.itwin-platform.v1+json |
响应
返回 200 OK:
OK
{ "user": { "id": "ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f", "displayName": "hanson.deck@cohesivecompanies.com", "givenName": "Hanson", "surname": "Deck", "email": "hanson.deck@cohesivecompanies.com", "_links": { "self": { "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f" } } } }
返回 401 Unauthorized:
此响应表示请求缺少有效的身份验证凭据。访问令牌可能未提供、或是由错误的颁发者颁发、没有所需的作用域或请求头的格式不正确。
{
"error": {
"code": "Unauthorized",
"message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
}
}
- Response 404 Not Found:
(1)无法找到指定的 iModel
{
"error": {
"code": "iModelNotFound",
"message": "Requested iModel is not available."
}
}
(2)无法找到用户
{
"error": {
"code": "UserNotFound",
"message": "Requested user is not available."
}
}
- Response 429 Too many requests:
此响应表示用户在给定的时间内发送了太多请求
{
"error": {
"code": "TooManyRequests",
"message": "More requests were received than the subscription rate-limit allows."
}
}
响应头
名称 | 描述 |
---|---|
retry-after | 超过客户端订阅的速率限制的请求数 |
接口二、获取 iModel 用户列表
GET https://api.bentley.com/imodels/{id}/users[?$top][&$skip]
通过 iModelId 获取链接到某个 iModel 的用户的列表
说明
Header 中的 Perfer
可用于指定客户端需要多少元数据结果。Preer
用于指示特定的服务器行为是客户端首选的,但不是成功完成请求所必需的。
此操作支持“return=representation”和“return=minimal”首选项。
“return=representation”首选项表示客户端希望服务器在响应成功请求时包含一个表示资源当前状态的实体。“return=minimal”首选项表示客户端希望服务器对成功的请求只返回最小的响应。如果未指定首选标头,则这是默认首选项。
认证
需要在请求 Header 里包含 Authorization
字段,Authorization
字段要求是有效的且带有 imodels:read
作用域的 Bearer 令牌。
想要了解更多关于授权以及如何获取 access token的细节,请参考这个https://developer.bentley.com/apis/overview/authorization/文档 。
授权
用户必须在 iModel 级别上分配 imodels_webview
的权限,以及至少在项目级别上分配 imodels_webview
权限。如果未配置 iModel 级别的权限,则用户必须在项目级别分配 imodels_webview
权限。
或者,用户应该是此 iModel 所属的项目所在的组织上的组织管理员。
组织管理员必须在用户管理中至少分配以下角色之一:Account Administrator(账户管理员), Co-Administrator(联合管理员), or CONNECT Services Administrator(CONNECT 服务管理员)。想要了解更多有关于用户管理的信息,请查看 Bentley 社区 的 wiki 页面 https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0
接口使用率限制
所有在 iTwin Platform 上的接口都有接口使用率限制。想了解更多相关信息请查看 https://developer.bentley.com/apis/overview/rate-limits/
请求
请求参数
参数名称 | 所在位置 | 是否必须 | 描述 |
---|---|---|---|
id | template | 是 | iModel 的 ID |
$top | query | 否 | $top 请求查询的集合结果中中要包含结果的数目。例如,仅返回第一个集合项,请提供以下查询:$top=1。如果此参数未提供则默认为100。此参数的值不能超过1000 |
$skip | query | 否 | $skip 选项请求查询集合中要跳过且不包含在结果中的项数。例如,要从第三位开始返回集合中的项目,请提供以下查询:$skip=2。 |
请求头
名称 | 是否必须 | 描述 |
---|---|---|
Authorization | 是 | 带有 imodels:read 作用域的 OAuth 访问令牌 |
Accept | 否 | 推荐设置为 application/vnd.bentley.itwin-platform.v1+json |
Prefer | 否 | 标识响应中所携带信息的详细等级。此操作支持“return=representation”和“return=minimal”首选项 |
响应
返回 200 OK:
OK
(1)Prefer: return=minimal
{ "users": [{ "id": "ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f", "displayName": "hanson.deck@cohesivecompanies.com", "_links": { "self": { "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f" } } }, { "id": "cdde5818-21ff-4e54-a014-cf1d85205896", "displayName": "hans.down@cohesivecompanies.com", "_links": { "self": { "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/cdde5818-21ff-4e54-a014-cf1d85205896" } } } ], "_links": { "self": { "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users?$skip=0&$top=100" }, "prev": { "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users?$skip=0&$top=100" }, "next": { "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users?$skip=100&$top=100" } } }
(2)Prefer: return=representation
{ "users": [{ "id": "ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f", "displayName": "hanson.deck@cohesivecompanies.com", "givenName": "Hanson", "surname": "Deck", "email": "hanson.deck@cohesivecompanies.com", "_links": { "self": { "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f" } } }, { "id": "cdde5818-21ff-4e54-a014-cf1d85205896", "displayName": "hans.down@cohesivecompanies.com", "givenName": "Hans", "surname": "Down", "email": "hans.down@cohesivecompanies.com", "_links": { "self": { "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/cdde5818-21ff-4e54-a014-cf1d85205896" } } } ], "_links": { "self": { "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users?$skip=0&$top=100" }, "prev": { "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users?$skip=0&$top=100" }, "next": { "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users?$skip=100&$top=100" } } }
返回 401 Unauthorized:
此响应表示请求缺少有效的身份验证凭据。访问令牌可能未提供、或是由错误的颁发者颁发、没有所需的作用域或请求头的格式不正确。
{
"error": {
"code": "Unauthorized",
"message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
}
}
- Response 404 Not Found:
无法找到指定的 iModel
{
"error": {
"code": "iModelNotFound",
"message": "Requested iModel is not available."
}
}
Response 422 Unprocessable Entity:
状态代码表示由于客户端错误(例如,格式错误的请求语法),服务器无法处理请求。
{ "error": { "code": "InvalidiModelsRequest", "message": "Cannot get users.", "details": [{ "code": "InvalidValue", "message": "'-1' is not a valid '$skip' value. '$skip' must be a non-negative integer.", "target": "$skip" }] } }
Response 429 Too many requests:
此响应表示用户在给定的时间内发送了太多请求
{
"error": {
"code": "TooManyRequests",
"message": "More requests were received than the subscription rate-limit allows."
}
}
响应头
名称 | 描述 |
---|---|
retry-after | 超过客户端订阅的速率限制的请求数 |