1. Changesets 接口说明

Changesets（变更集）

接口一、创建 iModel 的变更集

POST https://api.bentley.com/imodels/{id}/briefcases

创建一个变更集的元数据。

了解更多关于使用 iTwin.js 创建和获取变更集的信息请查阅：https://www.itwinjs.org/learning/imodelhub/briefcases/

重要要点：此操作只能由 iTwin.js 使用。要创建和上传有效的变更集，请使用 iTwin.js 库。

推送变更集包括三个步骤：

创建变更集元数据
通过使用上一步响应中的 upload 属性的链接，将变更集的相关文件上传到 Blob 存储

Request syntax:
    PUT upload HTTP/1.1
Request headers:
    x-ms-blob-type: BlockBlob

确认变更集文件已成功上传，完成变更集的推送。请查阅更新 iModel 变更集操作的文档。

认证

需要在请求 Header 里包含 Authorization 字段，Authorization 字段要求是有效的且带有 imodels:modify 作用域的 Bearer 令牌。

想要了解更多关于授权以及如何获取 access token的细节，请参考这个https://developer.bentley.com/apis/overview/authorization/文档。

授权

用户必须在 iModel 级别上分配 imodels_write 的权限，以及至少在项目级别上分配 imodels_webview 权限。如果未配置 iModel 级别的权限，则用户必须在项目级别分配 imodels_write 权限。

或者，用户应该是此 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:modify` 作用域的 OAuth 访问令牌
Accept	否	推荐设置为 `application/vnd.bentley.itwin-platform.v1+json`
Content-Type	否	标识请求主体的内容类型。支持的类型为 `application/json`

请求 body

Changeset (create)

名称	类型	是否必须	描述
id	String	是	变更集的 ID
description	String 或者 null	否	变更集的描述
parentId	String 或者 null	否	父变更集的 ID
briefcaseId	整数	是	用来创建变更集的 briefcase 的 ID
fileSize	整数	是	以字节的格式标识变更集文件的大小
containingChanges	整数或者 null	否	描述变更集包含的更改类型。说明变更集包含的更改。0-常规，1-模式，2-定义，4-空间数据，8-图纸和图纸，16-视图和模型，32-全局属性。ContainingChanges 是标志值，因此除了 Schema 之外的所有更改类型都可以组合。

例子

{
    "id": "1f2e04b666edce395e37a795e2231e995cbf8349",
    "description": "Changeset 15",
    "parentId": "f7618612c572d7db8e3e6095d622d0d8aff22874",
    "containingChanges": 0,
    "fileSize": 109,
    "briefcaseId": 2
}

响应

返回 201 No Created：

Created

{
    "changeset": {
        "id": "1f2e04b666edce395e37a795e2231e995cbf8349",
        "displayName": "256",
        "description": "Changeset 15",
        "index": 0,
        "parentId": "f7618612c572d7db8e3e6095d622d0d8aff22874",
        "state": "waitingForFile",
        "containingChanges": 0,
        "fileSize": 109,
        "briefcaseId": 2,
        "creatorId": null,
        "pushDateTime": null,
        "application": null,
        "synchronizationInfo": null,
        "_links": {
            "creator": null,
            "namedVersion": null,
            "self": {
                "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/1f2e04b666edce395e37a795e2231e995cbf8349"
            },
            "upload": {
                "href": "https://imodelhub.blob.core.windows.net/imodelhub-5e19bee0-3aea-4355-a9f0-c6df9989ee7d/1f2e04b666edce395e37a795e2231e995cbf8349.cs?sv=2019-07-07&sr=b&sig=IKzMBa%2Be3TjSebXj6rWmDHiG4FEoxtPA2vJUyTVZ%2B%2BI%3D&st=2021-07-30T09%3A02%3A10.1944006Z&se=2021-07-30T09%3A22%3A10.1944012Z&sp=rw"
            },
            "complete": {
                "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/1f2e04b666edce395e37a795e2231e995cbf8349"
            }
        }
    }
}

返回 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：

（1）未找到指定的 iModel

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

（2）未找到指定的 briefcase

{
    "error": {
        "code": "BriefcaseNotFound",
        "message": "Requested Briefcase is not available."
    }
}

Response 409 Conflict：

具有相同id的变更集已存在，“parentId”属性值未指向最新的更改，或者其他用户当前正在推送变更集。

（1）有新的变更存在

{
    "error": {
        "code": "NewerChangesExist",
        "message": "'parentId' does not match latest Changeset."
    }
}

（2）变更集存在

{
    "error": {
        "code": "ChangesetExists",
        "message": "Changeset with the same id already exists within the iModel."
    }
}

（3）与其他用户冲突

{
    "error": {
        "code": "ConflictWithAnotherUser",
        "message": "Another user is pushing a Changeset."
    }
}

Response 422 Unprocessable Entity：

状态代码表示由于客户端错误（例如，格式错误的请求语法），服务器无法处理请求。

（1）不合法的 iModels 请求

{
    "error": {
        "code": "InvalidiModelsRequest",
        "message": "Cannot create Changeset.",
        "details": [{
                "code": "InvalidValue",
                "message": "Provided 'fileSize' value is not valid. 'fileSize' must be a non-negative integer value.",
                "target": "fileSize"
            },
            {
                "code": "MissingRequiredProperty",
                "message": "Required property is missing.",
                "target": "id"
            },
            {
                "code": "InvalidRequestBody",
                "message": "Failed to parse request body. Make sure it is a valid JSON."
            }
        ]
    }
}

（2）请求主体缺失

{
    "error": {
        "code": "MissingRequestBody",
        "message": "Request body was not provided."
    }
}

Response 429 Too many requests：

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

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

响应头

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

接口二、获取变更集的检查点

GET https://api.bentley.com/imodels/{id}/changesets/{changeset}/checkpoint

检查点是一个预处理的iModel基线文件，其中包含已应用的某个更改集的更改，并已存储在服务器上。这可以用来减少应用到特定版本的 iModel 所需的变更集数量。

当为变更集创建命名版本时，将生成一个检查点。

检查点可以以两种不同的形式存储起来：

download 属性会包含一个指向完整的 .bim 文件的 Azure Blob 存储链接，这个 .bim 文件所含的更改应用于通过 changesetIndex 和 changesetId 属性指定的变更集。
containerAccessInfo 将拥有 Azure Blob 容器的访问密钥，该容器将检查点存储在4 MB块中。重要提示：此属性只能由 iTwin.js 库使用。

成功生成的检查点将具有一个或两个属性。

认证

需要在请求 Header 里包含 Authorization 字段，Authorization 字段要求是有效的且带有 imodels:read 作用域的 Bearer 令牌。

想要了解更多关于授权以及如何获取 access token的细节，请参考这个https://developer.bentley.com/apis/overview/authorization/文档。

授权

用户必须在 iModel 级别上分配 imodels_read 的权限，以及至少在项目级别上分配 imodels_webview 权限。如果未配置 iModel 级别的权限，则用户必须在项目级别分配 imodels_read 权限。

或者，用户应该是此 iModel 所属的项目所在的组织上的组织管理员。

接口使用率限制

所有在 iTwin Platform 上的接口都有接口使用率限制。想了解更多相关信息请查看 https://developer.bentley.com/apis/overview/rate-limits/

请求

请求参数

参数名称	所在位置	是否必须	描述
id	template	是	iModel 的 ID
changeset	template	是	变更集的 ID 或者索引

请求头

名称	是否必须	描述
Authorization	是	带有 `imodels:read` 作用域的 OAuth 访问令牌
Accept	否	推荐设置为 `application/vnd.bentley.itwin-platform.v1+json`

响应

返回 200 OK：

{
    "checkpoint": {
        "changesetIndex": 1,
        "changesetId": "a1ecbdc8c4f6173004f9f881914a57c5511a362b",
        "state": "successful",
        "containerAccessInfo": {
            "account": "imodelhubsa01",
            "sas": "?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",
            "container": "imodelblocks-5e19bee0-3aea-4355-a9f0-c6df9989ee7d",
            "dbName": "a1ecbdc8c4f6173004f9f881914a57c5511a362b.bim"
        },
        "_links": {
            "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：

（1）未找到指定的 iModel

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

（2）未找到指定的变更集

{
    "error": {
        "code": "ChangesetNotFound",
        "message": "Requested Changeset is not available."
    }
}

（3）未找到指定的检查点

{
    "error": {
        "code": "CheckpointNotFound",
        "message": "Requested Checkpoint 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}/changesets/{changeset}

获取变更集的元数据。

了解更多关于使用 iTwin.js 创建和获取变更集的信息请查阅：https://www.itwinjs.org/learning/imodelhub/briefcases/。

认证

需要在请求 Header 里包含 Authorization 字段，Authorization 字段要求是有效的且带有 imodels:read 作用域的 Bearer 令牌。

想要了解更多关于授权以及如何获取 access token的细节，请参考这个https://developer.bentley.com/apis/overview/authorization/文档。

授权

用户必须在 iModel 级别上分配 imodels_webview 的权限，以及至少在项目级别上分配 imodels_webview 权限。如果未配置 iModel 级别的权限，则用户必须在项目级别分配 imodels_webview 权限。

或者，用户应该是此 iModel 所属的项目所在的组织上的组织管理员。

注意：download属性需要用户至少拥有 imodels_read 权限。如果用户只有 imodels_webview 权限那么 download 属性常空。

接口使用率限制

所有在 iTwin Platform 上的接口都有接口使用率限制。想了解更多相关信息请查看 https://developer.bentley.com/apis/overview/rate-limits/

请求

请求参数

参数名称	所在位置	是否必须	描述
id	template	是	iModel 的 ID
changeset	template	是	变更集的 ID 或者索引

请求头

名称	是否必须	描述
Authorization	是	带有 `imodels:read` 作用域的 OAuth 访问令牌
Accept	否	推荐设置为 `application/vnd.bentley.itwin-platform.v1+json`

响应

返回 200 OK：

{
    "changeset": {
        "id": "1f2e04b666edce395e37a795e2231e995cbf8349",
        "displayName": "256",
        "description": "Changeset 15",
        "index": 256,
        "parentId": "f7618612c572d7db8e3e6095d622d0d8aff22874",
        "creatorId": "ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f",
        "pushDateTime": "2020-10-21T06:35:30.7000000Z",
        "state": "fileUploaded",
        "containingChanges": 0,
        "fileSize": 109,
        "briefcaseId": 2,
        "application": {
            "name": "iTwin Synchronizer"
        },
        "synchronizationInfo": {
            "changedFiles": [
                "File1.dgn",
                "File2.dgn"
            ]
        },
        "_links": {
            "creator": {
                "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f"
            },
            "namedVersion": {
                "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/namedversions/0c18d073-d1e2-4862-9d6b-a5a63ade4f52"
            },
            "self": {
                "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/1f2e04b666edce395e37a795e2231e995cbf8349"
            },
            "download": {
                "href": "https://imodelhub.blob.core.windows.net/imodelhub-5e19bee0-3aea-4355-a9f0-c6df9989ee7d/1f2e04b666edce395e37a795e2231e995cbf8349.cs?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：

（1）未找到指定的 iModel

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

（2）未找到指定的变更集

{
    "error": {
        "code": "ChangesetNotFound",
        "message": "Requested Changeset 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}/changesets[?$top][&$skip][&$orderBy][&afterIndex][&lastIndex]

通过 iModel ID 获取 iModel 对应的变更集的列表。

变更集构成了 iModel 变更的一个线性时间线。了解更多关于使用 iTwin.js 创建和获取变更集的信息请查阅：https://www.itwinjs.org/learning/imodelhub/briefcases/。

说明

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 所属的项目所在的组织上的组织管理员。

注意：download属性需要用户至少拥有 imodels_read 权限。如果用户只有 imodels_webview 权限那么 download 属性常空。

接口使用率限制

所有在 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。
$orderBy	query	否	$orderBy 选项允许客户端使用“asc”请求升序，或使用“desc”请求降序，按其中一个项属性对返回的集合进行排序。目前，变更集唯一受支持的属性是“index”。如果未指定“asc”或“desc”关键字，则集合将按升序排序。要按降序排列集合，请提供'desc'关键字，例如：$orderBy=index desc
afterIndex	query	否	afterIndex 选项选项允许客户端查询索引大于 query 中指定的索引的变更集。例如，要返回索引大于或等于 2 的变更集，请提供以下查询：afterIndex=1。当用户想要从 iModel 的本地副本中已经存在的变更集开始查询最新的变更集时，此查询选项非常有用。这可以与 lastIndex 选项一起使用，以指定变更集索引范围，afterIndex 表示范围的独占开始。
lastIndex	query	否	lastIndex 选项允许客户端查询索引小于或等于 query 中指定的索引的变更集。例如，要返回索引小于或等于10的变更集，请提供以下查询：lastIndex=10。这可以与afterIndex 选项一起使用，以指定变更集索引范围，lastIndex 表示范围的包含末端。

请求头

名称	是否必须	描述
Authorization	是	带有 `imodels:read` 作用域的 OAuth 访问令牌
Accept	否	推荐设置为 `application/vnd.bentley.itwin-platform.v1+json`
Prefer	否	标识响应中所携带信息的详细等级。此操作支持“return=representation”和“return=minimal”首选项

响应

返回 200 OK：

（1）Prefer: return=minimal

{
    "changesets": [{
            "id": "a1ecbdc8c4f6173004f9f881914a57c5511a362b",
            "displayName": "1",
            "description": "Changeset 0",
            "index": 1,
            "parentId": "",
            "creatorId": "ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f",
            "pushDateTime": "2020-10-21T06:34:45.007Z",
            "state": "fileUploaded",
            "containingChanges": 0,
            "fileSize": 109,
            "briefcaseId": 2,
            "_links": {
                "creator": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f"
                },
                "self": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/a1ecbdc8c4f6173004f9f881914a57c5511a362b"
                }
            }
        },
        {
            "id": "7caef8ab5afcd99c9e618fb37978c3a03d0409c7",
            "displayName": "2",
            "description": "Changeset 1",
            "index": 2,
            "parentId": "a1ecbdc8c4f6173004f9f881914a57c5511a362b",
            "creatorId": "ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f",
            "pushDateTime": "2020-10-21T06:34:48.123Z",
            "state": "fileUploaded",
            "containingChanges": 0,
            "fileSize": 139,
            "briefcaseId": 2,
            "_links": {
                "creator": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f"
                },
                "self": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/7caef8ab5afcd99c9e618fb37978c3a03d0409c7"
                }
            }
        },
        {
            "id": "a587345859410ce5c2811c7c558d4578938efa00",
            "displayName": "3",
            "description": "Changeset 2",
            "index": 3,
            "parentId": "7caef8ab5afcd99c9e618fb37978c3a03d0409c7",
            "creatorId": "27e3ecc7-ae44-4c9d-b0b5-2f65ec146f1d",
            "pushDateTime": "2020-10-21T06:34:51.13Z",
            "state": "fileUploaded",
            "containingChanges": 2,
            "fileSize": 109,
            "briefcaseId": 2,
            "_links": {
                "creator": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/27e3ecc7-ae44-4c9d-b0b5-2f65ec146f1d"
                },
                "self": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/a587345859410ce5c2811c7c558d4578938efa00"
                }
            }
        },
        {
            "id": "13a61888798b687d41f7c748d7414b428766281f",
            "displayName": "4",
            "description": "Changeset 3",
            "index": 4,
            "parentId": "a587345859410ce5c2811c7c558d4578938efa00",
            "creatorId": "27e3ecc7-ae44-4c9d-b0b5-2f65ec146f1d",
            "pushDateTime": "2020-10-21T06:34:54.13Z",
            "state": "fileUploaded",
            "containingChanges": 18,
            "fileSize": 109,
            "briefcaseId": 2,
            "_links": {
                "creator": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/27e3ecc7-ae44-4c9d-b0b5-2f65ec146f1d"
                },
                "self": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/13a61888798b687d41f7c748d7414b428766281f"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets?$skip=100&$top=100"
        },
        "prev": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets?$skip=0&$top=100"
        },
        "next": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets?$skip=200&$top=100"
        }
    }
}

（2）Prefer: return=representation

{
    "changesets": [{
            "id": "a1ecbdc8c4f6173004f9f881914a57c5511a362b",
            "displayName": "1",
            "description": "Changeset 0",
            "index": 1,
            "parentId": "",
            "creatorId": "ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f",
            "pushDateTime": "2020-10-21T06:34:45.007Z",
            "state": "fileUploaded",
            "containingChanges": 0,
            "fileSize": 109,
            "briefcaseId": 2,
            "application": {
                "name": "iTwin Synchronizer"
            },
            "synchronizationInfo": {
                "changedFiles": [
                    "File1.dgn",
                    "File2.dgn"
                ]
            },
            "_links": {
                "creator": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f"
                },
                "namedVersion": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/namedversions/a9f63fc0-ecab-440b-ba59-1a617e15f543"
                },
                "self": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/a1ecbdc8c4f6173004f9f881914a57c5511a362b"
                },
                "download": {
                    "href": "https://imodelhub.blob.core.windows.net/imodelhub-5e19bee0-3aea-4355-a9f0-c6df9989ee7d/a1ecbdc8c4f6173004f9f881914a57c5511a362b.cs?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"
                }
            }
        },
        {
            "id": "7caef8ab5afcd99c9e618fb37978c3a03d0409c7",
            "displayName": "2",
            "description": "Changeset 1",
            "index": 2,
            "parentId": "a1ecbdc8c4f6173004f9f881914a57c5511a362b",
            "creatorId": "ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f",
            "pushDateTime": "2020-10-21T06:34:48.123Z",
            "state": "fileUploaded",
            "containingChanges": 0,
            "fileSize": 139,
            "briefcaseId": 2,
            "application": {
                "name": "iTwin Synchronizer"
            },
            "synchronizationInfo": {
                "changedFiles": [
                    "File1.dgn"
                ]
            },
            "_links": {
                "creator": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f"
                },
                "namedVersion": null,
                "self": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/7caef8ab5afcd99c9e618fb37978c3a03d0409c7"
                },
                "download": {
                    "href": "https://imodelhub.blob.core.windows.net/imodelhub-5e19bee0-3aea-4355-a9f0-c6df9989ee7d/7caef8ab5afcd99c9e618fb37978c3a03d0409c7.cs?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"
                }
            }
        },
        {
            "id": "a587345859410ce5c2811c7c558d4578938efa00",
            "displayName": "3",
            "description": "Changeset 2",
            "index": 3,
            "parentId": "7caef8ab5afcd99c9e618fb37978c3a03d0409c7",
            "creatorId": "27e3ecc7-ae44-4c9d-b0b5-2f65ec146f1d",
            "pushDateTime": "2020-10-21T06:34:51.13Z",
            "state": "fileUploaded",
            "containingChanges": 2,
            "fileSize": 109,
            "briefcaseId": 2,
            "application": {
                "name": "Synchro Modeler"
            },
            "synchronizationInfo": null,
            "_links": {
                "creator": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/27e3ecc7-ae44-4c9d-b0b5-2f65ec146f1d"
                },
                "namedVersion": null,
                "self": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/a587345859410ce5c2811c7c558d4578938efa00"
                },
                "download": {
                    "href": "https://imodelhub.blob.core.windows.net/imodelhub-5e19bee0-3aea-4355-a9f0-c6df9989ee7d/a587345859410ce5c2811c7c558d4578938efa00.cs?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"
                }
            }
        },
        {
            "id": "13a61888798b687d41f7c748d7414b428766281f",
            "displayName": "4",
            "description": "Changeset 3",
            "index": 4,
            "parentId": "a587345859410ce5c2811c7c558d4578938efa00",
            "creatorId": "27e3ecc7-ae44-4c9d-b0b5-2f65ec146f1d",
            "pushDateTime": "2020-10-21T06:34:54.13Z",
            "state": "fileUploaded",
            "containingChanges": 18,
            "fileSize": 109,
            "briefcaseId": 2,
            "application": {
                "name": "Synchro Modeler"
            },
            "synchronizationInfo": null,
            "_links": {
                "creator": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/27e3ecc7-ae44-4c9d-b0b5-2f65ec146f1d"
                },
                "namedVersion": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/namedversions/2c35f213-8d83-44b9-b20f-750b81502121"
                },
                "self": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/13a61888798b687d41f7c748d7414b428766281f"
                },
                "download": {
                    "href": "https://imodelhub.blob.core.windows.net/imodelhub-5e19bee0-3aea-4355-a9f0-c6df9989ee7d/13a61888798b687d41f7c748d7414b428766281f.cs?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"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets?$skip=100&$top=100"
        },
        "prev": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets?$skip=0&$top=100"
        },
        "next": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets?$skip=200&$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：

（1）请求的 iModel 无效

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

Response 422 Unprocessable Entity：

状态代码表示由于客户端错误（例如，格式错误的请求语法），服务器无法处理请求。

{
    "error": {
        "code": "InvalidiModelsRequest",
        "message": "Cannot get Changesets.",
        "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	超过客户端订阅的速率限制的请求数

接口五、更新 iModel 的变更集信息

PATCH https://api.bentley.com/imodels/{id}/changesets/{changesetId}

确认变更集文件已经上传到文件存储，并完成变更集的推送。

认证

需要在请求 Header 里包含 Authorization 字段，Authorization 字段要求是有效的且带有 imodels:modify 作用域的 Bearer 令牌。

想要了解更多关于授权以及如何获取 access token的细节，请参考这个https://developer.bentley.com/apis/overview/authorization/文档。

授权

或者，用户应该是此 iModel 所属的项目所在的组织上的组织管理员。

注意：download属性需要用户至少拥有 imodels_read 权限。如果用户只有 imodels_webview 权限那么 download 属性常空。

接口使用率限制

所有在 iTwin Platform 上的接口都有接口使用率限制。想了解更多相关信息请查看 https://developer.bentley.com/apis/overview/rate-limits/

请求

请求参数

参数名称	所在位置	是否必须	描述
id	template	是	iModel 的 ID
changesetId	template	是	变更集 ID

请求头

名称	是否必须	描述
Authorization	是	带有 `imodels:read` 作用域的 OAuth 访问令牌
Accept	否	推荐设置为 `application/vnd.bentley.itwin-platform.v1+json`
Content-Type	否	标识请求头的内容类型。支持的类型为 application/json

请求 body

Changeset (update)

名称	类型	是否必须	描述
briefcaseId	整数	是	用来创建变更集的 briefcase 的 ID
state	String	是	标识变更集的状态。应该设置为 'fileUploaded'

例子

{
    "state": "fileUploaded",
    "briefcaseId": 2
}

响应

返回 200 OK：

{
    "changeset": {
        "id": "1f2e04b666edce395e37a795e2231e995cbf8349",
        "displayName": "256",
        "description": "Changeset 15",
        "index": 256,
        "parentId": "f7618612c572d7db8e3e6095d622d0d8aff22874",
        "state": "fileUploaded",
        "containingChanges": 0,
        "fileSize": 109,
        "briefcaseId": 2,
        "creatorId": "ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f",
        "pushDateTime": "2020-10-21T06:35:30.7000000Z",
        "application": null,
        "synchronizationInfo": null,
        "_links": {
            "creator": {
                "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f"
            },
            "namedVersion": null,
            "self": {
                "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets/1f2e04b666edce395e37a795e2231e995cbf8349"
            },
            "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."
    }
}

Response 403 Forbidden：

用户无权更新变更集

{
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}

Response 404 Not Found：

（1）无法找到指定的 iModel

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

（2）无法找到指定的 Briefcase

{
    "error": {
        "code": "BriefcaseNotFound",
        "message": "Requested Briefcase is not available."
    }
}

（3）无法找到指定的文件

{
    "error": {
        "code": "FileNotFound",
        "message": "Requested file is not available. File was not uploaded to file storage."
    }
}

（4）无法找到指定的变更集

{
    "error": {
        "code": "ChangesetNotFound",
        "message": "Requested Changeset is not available."
    }
}

Response 409 Conflict：

（1）变更集已存在

{
    "error": {
        "code": "ChangesetExists",
        "message": "Changeset with the same id already exists within the iModel."
    }
}

（2）当前有用户正在推送变更集

{
    "error": {
        "code": "ConflictWithAnotherUser",
        "message": "Another user is pushing a Changeset."
    }
}

Response 422 Unprocessable Entity：

状态代码表示由于客户端错误（例如，格式错误的请求语法），服务器无法处理请求。

（1）非法的 iModel 请求

{
    "error": {
        "code": "InvalidiModelsRequest",
        "message": "Cannot update Changeset.",
        "details": [{
                "code": "InvalidValue",
                "message": "Provided 'state' value is not valid. Should be set to 'fileUploaded'.",
                "target": "state"
            },
            {
                "code": "MissingRequiredProperty",
                "message": "Required property is missing.",
                "target": "state"
            },
            {
                "code": "InvalidRequestBody",
                "message": "Failed to parse request body. Make sure it is a valid JSON."
            }
        ]
    }
}

（2）请求主体缺失

{
    "error": {
        "code": "MissingRequestBody",
        "message": "Request body was not provided."
    }
}

Response 429 Too many requests：

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

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

响应头

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

1. Changesets 接口说明

Changesets（变更集）

接口一、创建 iModel 的变更集

认证

授权

接口使用率限制

请求

请求头

请求 body

例子

响应

接口二、获取变更集的检查点

认证

授权

接口使用率限制

请求

请求头

响应

接口三、获取 iModel 的变更集

认证

授权

接口使用率限制

请求

请求头

响应

接口四、获取 iModel 的变更集集合

说明

认证

授权

接口使用率限制

请求

请求头

响应

接口五、更新 iModel 的变更集信息

认证

授权

接口使用率限制

请求

请求头

请求 body

例子

响应

results matching ""

No results matching ""