1. BaselineFile 接口说明
Baseline Files(基线文件)
接口一、完成 iModel 基线文件上传
POST https://api.bentley.com/imodels/{id}/baselinefile
通过确认文件已上传到文件存储,从基线文件完成 iModel 创建。
基线文件是未应用任何变更集的基础 iModel 文件。如果想从定制化基线文件创建 iModel 请查看 https://developer.bentley.com/apis/imodels/operations/create-imodel/#createanimodelusingabaselinefile
认证
需要在请求 Header 里包含 Authorization 字段,Authorization
字段要求是有效的带有 imodels:modify
scope 的 Bearer token。
想要了解更多关于授权以及如何获取 access token的细节,请参考这个https://developer.bentley.com/apis/overview/authorization/文档 。
授权
用户必须是包含给定项目的组织的组织管理员,或者在项目的级别上具有 imodels_manage
权限。
组织管理员必须在用户管理中至少分配以下角色之一: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:modify 作用域的 OAuth 访问令牌 |
Accept | 否 | 推荐设置为 application/vnd.bentley.itwin-platform.v1+json |
响应
- 返回 200 OK:
{
"baselineFile": {
"id": "5e19bee0-3aea-4355-a9f0-c6df9989ee7d",
"displayName": "5e19bee0-3aea-4355-a9f0-c6df9989ee7d.bim",
"fileSize": 12563,
"state": "initializationScheduled",
"_links": {
"creator": {
"href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/42101fba-847a-4f4e-85a8-a4bed89065e4"
},
"download": null
}
}
}
- 返回 401 Unauthorized:
此响应表示请求缺少有效的身份验证凭据。访问令牌可能未提供、或是由错误的颁发者颁发、没有所需的作用域或请求头的格式不正确。
{
"error": {
"code": "Unauthorized",
"message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
}
}
- 返回 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."
}
}
或者,它没有关联的基线文件实体或该文件未上传到存储
{
"error": {
"code": "FileNotFound",
"message": "Requested file is not available. File was not uploaded to file storage."
}
}
- Response 409 Conflict:
iModel 创建期间所指定的文件大小与上传文件的实际大小不匹配。
{
"error": {
"code": "DataConflict",
"message": "File size provided during iModel creation does not match actual file size."
}
}
- Response 422 Unprocessable Entity:
422(不可处理实体)状态代码表示由于客户端错误(例如,格式错误的请求语法),服务器无法处理请求。
{
"error": {
"code": "InvalidiModelsRequest",
"message": "Cannot complete Baseline File upload.",
"details": [{
"code": "InvalidChange",
"message": "Baseline File upload is not in progress."
}]
}
}
- Response 429 Too many requests:
此响应表示用户在给定的时间内发送了太多请求。
{
"error": {
"code": "TooManyRequests",
"message": "More requests were received than the subscription rate-limit allows."
}
}
响应头
名称 | 描述 |
---|---|
retry-after | 超过客户端订阅的速率限制的请求数 |
定义
- 基线文件响应:
基线文件对象的容器
表:
名称 | 类型 | 描述 |
---|---|---|
baselineFile | BaselineFile | Baseline File 属性 |
格式:
{
"type": "object",
"title": "Baseline File Response",
"description": "Container for Baseline File object.",
"properties": {
"baselineFile": {
"$ref": "#/components/schemas/BaselineFile",
"description": "Baseline File properties."
}
}
}
- 基线文件:
iModel 基线文件的元数据
表:
名称 | 类型 | 描述 |
---|---|---|
id | String | 基线文件的 ID |
displayName | String | 基线文件的名字 |
size | Int64 | 基线文件的大小(字节) |
state | String | 标识基线文件的状态。'initialized“表示基线文件已初始化。”initializationScheduled'表示基线文件创建已完成,初始化已被调度或当前初始化正在进行。"waitingForFile'表示尚未完成文件上传到文件存储。"initializationFailed"表示初始化基线文件失败。"fileIsBriefcase"表示文件不是 standalone iModel,不能用作基线文件。 |
_links | BaselineFileLinks | 包含指向基线文件相关数据的超链接 |
格式:
{
"type": "object",
"title": "Baseline File",
"description": "Metadata of Baseline File of the iModel.",
"properties": {
"id": {
"type": "string",
"description": "Id of the Baseline File."
},
"displayName": {
"type": "string",
"description": "Name of the Baseline File."
},
"size": {
"type": "integer",
"format": "int64",
"description": "Size of the Baseline File in bytes."
},
"state": {
"type": "string",
"description": "Indicates the state of the Baseline File. 'initialized' - Baseline File is initialized. 'initializationScheduled' - Baseline File creation is complete and initialization is scheduled or currently in progress. 'waitingForFile' - file upload to file storage hasn't been completed yet. 'initializationFailed' - initializing Baseline File failed. 'fileIsBriefcase' - file is not a standalone iModel and cannot be used as a Baseline File.",
"enum": [
"initialized",
"initializationScheduled",
"initializationFailed",
"waitingForFile",
"fileIsBriefcase"
]
},
"_links": {
"$ref": "#/components/schemas/BaselineFileLinks",
"description": "Contains the hyperlinks to the related data of the Baseline File."
}
}
}
- 基线文件链接:
指向 Briefcase 相关数据的超链接
表:
名称 | 类型 | 描述 |
---|---|---|
creator | Link | 基线文件创建者的信息 |
download | Link | 从 Azure Blob 存储下载基线文件的链接。仅当用户至少有 imodels_read 权限时设置,否则它总是设置为 null。 |
格式:
{
"type": "object",
"title": "Baseline File Links",
"description": "Hyperlinks to Briefcase related data.",
"properties": {
"creator": {
"$ref": "#/components/schemas/Link",
"description": "Information about the creator of the Baseline File."
},
"download": {
"$ref": "#/components/schemas/Link",
"description": "Link to download Baseline File from Azure Blob storage. Set only if the user has at least `imodels_read` permission, otherwise it is always set to null."
}
}
}
- 链接:
超链接对象
表:
名称 | 类型 | 描述 |
---|---|---|
href | String | 指向特定实体的超链接 |
格式:
{
"type": [
"object",
"null"
],
"description": "Hyperlink container.",
"properties": {
"href": {
"type": "string",
"description": "Hyperlink to the specific entity."
}
}
}
- 错误:
包含错误信息和特定错误的可选数组
表:
名称 | 类型 | 描述 |
---|---|---|
code | String | 服务器定义的一组错误代码之一 |
message | String | 易于阅读的错误信息 |
details | ErrorDetails[] | 可选数组,包含特定错误的详情 |
格式:
{
"type": "object",
"description": "Contains error information and an optional array of more specific errors.",
"properties": {
"code": {
"type": "string",
"description": "One of a server-defined set of error codes."
},
"message": {
"type": "string",
"description": "A human-readable representation of the error."
},
"details": {
"type": "array",
"description": "Optional array of more specific errors.",
"items": {
"$ref": "#/components/schemas/ErrorDetails"
}
}
},
"required": [
"code",
"message"
]
}
- 错误详情(ErrorDetails):
包含错误详情信息
表:
名称 | 类型 | 描述 |
---|---|---|
code | String | 服务器定义的一组错误代码之一 |
message | String | 易于阅读的错误信息 |
格式:
{
"type": "object",
"title": "Error Details",
"description": "Contains error information.",
"properties": {
"code": {
"type": "string",
"description": "One of a server-defined set of error codes."
},
"message": {
"type": "string",
"description": "A human-readable representation of the error."
}
},
"required": [
"code",
"message"
]
}
- 错误响应:
提供处理请求时发生的错误的详细信息。请注意,客户机不能假设每个失败的请求都会生成此模式的对象,或者响应中的所有属性都是非空的,因为错误可能会阻止构造此响应
表:
名称 | 类型 | 描述 |
---|---|---|
error | Error | 错误信息 |
格式:
{
"type": "object",
"title": "Error Response",
"description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
"properties": {
"error": {
"description": "Error information.",
"$ref": "#/components/schemas/Error"
}
},
"required": [
"error"
]
}
接口二、获取 iModel 基线文件详情
GET https://api.bentley.com/imodels/{id}/baselinefile
检索基线文件的元数据。基线文件是未应用任何变更集的基础 iModel 文件。
认证
需要在请求 Header 里包含 Authorization 字段,Authorization
字段要求是有效的带有 imodels:read
scope 的 Bearer token。
想要了解更多关于授权以及如何获取 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
注意:
download
属性需要用户至少拥有imodels_read
权限。如果用户只有imodels_webview
权限,则download
属性应一直为 null。
接口使用率限制
所有在 iTwin Platform 上的接口都有接口使用率限制。想了解更多相关信息请查看 https://developer.bentley.com/apis/overview/rate-limits/
请求
请求参数
参数名称 | 所在位置 | 是否必须 | 描述 |
---|---|---|---|
id | template | 是 | iModel 的 ID |
请求头
名称 | 是否必须 | 描述 |
---|---|---|
Authorization | 是 | 带有 imodels:modify 作用域的 OAuth 访问令牌 |
Accept | 否 | 推荐设置为 application/vnd.bentley.itwin-platform.v1+json |
响应
- 返回 200 OK:
{
"baselineFile": {
"id": "5e19bee0-3aea-4355-a9f0-c6df9989ee7d",
"displayName": "5e19bee0-3aea-4355-a9f0-c6df9989ee7d.bim",
"fileSize": 12563,
"state": "initialized",
"_links": {
"creator": {
"href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/42101fba-847a-4f4e-85a8-a4bed89065e4"
},
"download": {
"href": "https://imodelhub.blob.core.windows.net/imodelhub-5e19bee0-3aea-4355-a9f0-c6df9989ee7d/5e19bee0-3aea-4355-a9f0-c6df9989ee7d.bim?sv=2019-07-07&sr=b&sig=ByGsPs4cwKyUfnV6%2BjDZFDL3J7QiE0vl917MCX%2FC35Y%3D&st=2021-07-30T10%3A53%3A09.5224547Z&se=2021-07-30T11%3A13%3A09.5224552Z&sp=r"
}
}
}
}
- 返回 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."
}
}
或者它没有关联的基线文件实体
{
"error": {
"code": "BaselineFileNotFound",
"message": "Requested Baseline File is not available."
}
}
- Response 429 Too many requests:
此响应表示用户在给定的时间内发送了太多请求。
{
"error": {
"code": "TooManyRequests",
"message": "More requests were received than the subscription rate-limit allows."
}
}
响应头
名称 | 描述 |
---|---|
retry-after | 超过客户端订阅的速率限制的请求数 |
定义
此定义与接口一中的定义相同,请跳转查阅。