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
响应
  1. 返回 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
        }
    }
}
  1. 返回 401 Unauthorized：

此响应表示请求缺少有效的身份验证凭据。访问令牌可能未提供、或是由错误的颁发者颁发、没有所需的作用域或请求头的格式不正确。

{
    "error": {
        "code": "Unauthorized",
        "message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
    }
}
  1. 返回 403 Forbidden：

用户无权完成基线文件上载。

{
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}
  1. 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."
    }
}
  1. Response 409 Conflict：

iModel 创建期间所指定的文件大小与上传文件的实际大小不匹配。

{
    "error": {
        "code": "DataConflict",
        "message": "File size provided during iModel creation does not match actual file size."
    }
}
  1. 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."
        }]
    }
}
  1. Response 429 Too many requests：

此响应表示用户在给定的时间内发送了太多请求。

{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

响应头

名称 描述
retry-after 超过客户端订阅的速率限制的请求数
定义
  1. 基线文件响应：

基线文件对象的容器

表：

名称 类型 描述
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."
        }
    }
}
  1. 基线文件：

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."
        }
    }
}
  1. 基线文件链接：

指向 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."
        }
    }
}
  1. 链接：

超链接对象

表：

名称 类型 描述
href String 指向特定实体的超链接

格式：

{
    "type": [
        "object",
        "null"
    ],
    "description": "Hyperlink container.",
    "properties": {
        "href": {
            "type": "string",
            "description": "Hyperlink to the specific entity."
        }
    }
}
  1. 错误：

包含错误信息和特定错误的可选数组

表：

名称 类型 描述
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"
    ]
}
  1. 错误详情（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"
    ]
}
  1. 错误响应：

提供处理请求时发生的错误的详细信息。请注意，客户机不能假设每个失败的请求都会生成此模式的对象，或者响应中的所有属性都是非空的，因为错误可能会阻止构造此响应

表：

名称 类型 描述
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

响应

  1. 返回 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"
            }
        }
    }
}
  1. 返回 401 Unauthorized：

此响应表示请求缺少有效的身份验证凭据。访问令牌可能未提供、或是由错误的颁发者颁发、没有所需的作用域或请求头的格式不正确。

{
    "error": {
        "code": "Unauthorized",
        "message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
    }
}
  1. Response 404 Not Found：

未找到指定的 iModel

{
    "error": {
        "code": "iModelNotFound",
        "message": "Requested iModel is not available."
    }
}

或者它没有关联的基线文件实体

{
    "error": {
        "code": "BaselineFileNotFound",
        "message": "Requested Baseline File is not available."
    }
}
  1. Response 429 Too many requests：

此响应表示用户在给定的时间内发送了太多请求。

{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

响应头

名称 描述
retry-after 超过客户端订阅的速率限制的请求数
定义

此定义与接口一中的定义相同，请跳转查阅。

results matching ""

    No results matching ""