1. Briefcase 接口说明

Briefcase（公文包）

接口一、创建 iModel briefcase

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

创建一个新的 briefcase。

Briefcase 是 iModel 的本地副本，用户可以获取这些副本来使用 iModel。用户可以对其 iModel 副本进行更改，然后将其作为单个变更集文件推送到 iModelHub 中。了解更多关于 briefcase 的信息请查看 https://www.itwinjs.org/learning/imodelhub/briefcases/ 。

认证

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

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

授权

用户必须是在 iModel 级别上有 imodels_read 的权限以及至少在项目级别上有 imodels_webview 的权限。 如果在 iModel 级别上没有为用户配置权限，那么用户必须在项目级别上有 imodels_read 的权限。

或者，用户应该是此 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 否 标识请求 body 的内容类型。支持的媒体类型为 application/json
请求 body

Briefcase（必须）

名称 类型 是否必须 描述
deviceName String 或 null 否 持有 briefcase 的设备的名称
例子
{
    "deviceName": "Device name"
}
响应
  1. 返回 201 Created：
{
    "briefcase": {
        "id": "2",
        "briefcaseId": 2,
        "displayName": "#2 Device Name",
        "ownerId": "42101fba-847a-4f4e-85a8-a4bed89065e4",
        "acquiredDateTime": "2020-10-20T10:51:33.1700000Z",
        "fileSize": 2048,
        "deviceName": "Device Name",
        "_links": {
            "owner": {
                "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/42101fba-847a-4f4e-85a8-a4bed89065e4"
            }
        }
    }
}
  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."
    }
}
  1. Response 422 Unprocessable Entity：

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

{
    "error": {
        "code": "InvalidiModelsRequest",
        "message": "Cannot acquire Briefcase.",
        "details": [{
                "code": "InvalidValue",
                "message": "Provided 'deviceName' is not valid. The value exceeds allowed 255 characters.",
                "target": "deviceName"
            },
            {
                "code": "InvalidHeaderValue",
                "message": "'application/xml' is not supported 'content-type'. Supported media type is 'application/json'.",
                "target": "content-type"
            },
            {
                "code": "ResourceQuotaExceeded",
                "message": "Maximum number of Briefcases per user limit reached.",
                "innerError": {
                    "code": "MaximumNumberOfBriefcasesPerUser"
                }
            }
        ]
    }
}
  1. Response 429 Too many requests：

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

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

或者，

{
    "error": {
        "code": "RateLimitExceeded",
        "message": "Maximum number of briefcases per user per minute reached."
    }
}

响应头

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

briefcase 对象的容器

表：

名称 类型 描述
briefcase Briefcase Briefcase 属性

格式：

{
    "type": "object",
    "title": "Briefcase Response",
    "description": "Container for Briefcase object.",
    "properties": {
        "briefcase": {
            "$ref": "#/components/schemas/Briefcase",
            "description": "Briefcase properties."
        }
    }
}
  1. Briefcase（获取）：

要获取的 Breifcase 的属性

表：

名称 类型 描述
deviceName String 或 null 持有 briefcase 的设备名称

格式：

{
    "type": "object",
    "title": "Briefcase (acquire)",
    "description": "Properties of the Breifcase to be acquired.",
    "properties": {
        "deviceName": {
            "type": [
                "string",
                "null"
            ],
            "description": "Name of the device which will hold the briefcase."
        }
    }
}
  1. Briefcase：

Briefcase 是一个保存 iModel 副本的文件

表：

名称 类型 描述
id String briefcase 的 ID
briefcaseId Integer 整数形式的 briefcase 的 ID
displayName String Briefcase 的展示名称，对应 id 和 deviceName 属性
acquiredDateTime String 获得 briefcase 的时间
fileSize Integer briefcase 文件的大小，以字节表示
deviceName String 或 null 持有 briefcase 的设备名称
_links BriefcaseLinks 包含指向 briefcase 相关数据的超链接

格式：

{
    "type": "object",
    "description": "Briefcase is a file holding a copy of an iModel.",
    "properties": {
        "id": {
            "type": "string",
            "description": "Id of the Briefcase."
        },
        "briefcaseId": {
            "type": "integer",
            "description": "Id of the Briefcase as an integer."
        },
        "displayName": {
            "type": "string",
            "description": "Display name of the Briefcase. Corresponds to id and deviceName properties."
        },
        "acquiredDateTime": {
            "type": "string",
            "description": "Date when the Briefcase was acquired."
        },
        "fileSize": {
            "type": "integer",
            "description": "Size of the Briefcase in bytes."
        },
        "deviceName": {
            "type": [
                "string",
                "null"
            ],
            "description": "Name of the device which will hold the briefcase."
        },
        "_links": {
            "$ref": "#/components/schemas/BriefcaseLinks",
            "description": "Contains the hyperlinks to the related data of the Briefcase."
        }
    }
}
  1. Briefcase 链接：

指向 briefcase 相关数据的超链接

表：

名称 类型 描述
owner Link briefcase 持有人的信息

格式：

{
    "type": "object",
    "title": "Briefcase Links",
    "description": "Hyperlinks to Briefcase related data.",
    "properties": {
        "owner": {
            "$ref": "#/components/schemas/Link",
            "description": "Information about the owner of the Briefcase."
        }
    }
}
  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 briefcase

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

检索 briefcase 的详细信息。

Briefcase 是 iModel 的本地副本，用户可以获取这些副本来使用 iModel。用户可以对其 iModel 副本进行更改，然后将其作为单个变更集文件推送到 iModelHub 中。了解更多关于 briefcase 的信息请查看 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 所属的项目所在的组织上的组织管理员。

组织管理员必须在用户管理中至少分配以下角色之一：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
briefcaseId template 是 Briefcase 的 Id
请求头
名称 是否必须 描述
Authorization 是 带有 imodels:read 作用域的 OAuth 访问令牌
Accept 否 推荐设置为 application/vnd.bentley.itwin-platform.v1+json
响应

  1. 返回 200 OK：

    {
    "briefcase": {
        "id": "2",
        "briefcaseId": 2,
        "displayName": "#2 Device Name",
        "ownerId": "42101fba-847a-4f4e-85a8-a4bed89065e4",
        "acquiredDateTime": "2020-10-20T10:51:33.1700000Z",
        "fileSize": 2048,
        "deviceName": "Device Name",
        "_links": {
            "owner": {
                "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/42101fba-847a-4f4e-85a8-a4bed89065e4"
            }
        }
    }
}

  2. 返回 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."
    }
}

未找到指定的 briefcase

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

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

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

或者，

{
    "error": {
        "code": "RateLimitExceeded",
        "message": "Maximum number of briefcases per user per minute reached."
    }
}

响应头

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

briefcase 对象的容器

表：

名称 类型 描述
briefcase Briefcase Briefcase 属性

格式：

{
    "type": "object",
    "title": "Briefcase Response",
    "description": "Container for Briefcase object.",
    "properties": {
        "briefcase": {
            "$ref": "#/components/schemas/Briefcase",
            "description": "Briefcase properties."
        }
    }
}
  1. Briefcase：

Briefcase 是一个保存 iModel 副本的文件

表：

名称 类型 描述
id String briefcase 的 ID
briefcaseId Integer 整数形式的 briefcase 的 ID
displayName String Briefcase 的展示名称，对应 id 和 deviceName 属性
acquiredDateTime String 获得 briefcase 的时间
fileSize Integer briefcase 文件的大小，以字节表示
deviceName String 或 null 持有 briefcase 的设备名称
_links BriefcaseLinks 包含指向 briefcase 相关数据的超链接

格式：

{
    "type": "object",
    "description": "Briefcase is a file holding a copy of an iModel.",
    "properties": {
        "id": {
            "type": "string",
            "description": "Id of the Briefcase."
        },
        "briefcaseId": {
            "type": "integer",
            "description": "Id of the Briefcase as an integer."
        },
        "displayName": {
            "type": "string",
            "description": "Display name of the Briefcase. Corresponds to id and deviceName properties."
        },
        "acquiredDateTime": {
            "type": "string",
            "description": "Date when the Briefcase was acquired."
        },
        "fileSize": {
            "type": "integer",
            "description": "Size of the Briefcase in bytes."
        },
        "deviceName": {
            "type": [
                "string",
                "null"
            ],
            "description": "Name of the device which will hold the briefcase."
        },
        "_links": {
            "$ref": "#/components/schemas/BriefcaseLinks",
            "description": "Contains the hyperlinks to the related data of the Briefcase."
        }
    }
}
  1. Briefcase 链接：

指向 briefcase 相关数据的超链接

表：

名称 类型 描述
owner Link briefcase 持有人的信息

格式：

{
    "type": "object",
    "title": "Briefcase Links",
    "description": "Hyperlinks to Briefcase related data.",
    "properties": {
        "owner": {
            "$ref": "#/components/schemas/Link",
            "description": "Information about the owner of the Briefcase."
        }
    }
}
  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 briefcase 列表

GET https://api.bentley.com/imodels/{id}/briefcases[?$top][&$skip][&ownerId]

通过 iModel Id 获取指定 iModel 的一组 briefcase。

Briefcase 是 iModel 的本地副本，用户可以获取这些副本来使用 iModel。用户可以对其 iModel 副本进行更改，然后将其作为单个变更集文件推送到 iModelHub 中。了解更多关于 briefcase 的信息请查看 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 级别上有 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。
ownerId query 否 允许用户通过 ownerId 参数过滤 briefcase。当前此参数唯一支持的值是 me，它关联着当前的用户。当前用户是用于请求的访问令牌所属的用户，例如，返回当前用户拥有的 briefcase，请提供以下查询：ownerId=me
请求头
名称 是否必须 描述
Authorization 是 带有 imodels:read 作用域的 OAuth 访问令牌
Accept 否 推荐设置为 application/vnd.bentley.itwin-platform.v1+json
Prefer 否 标识响应中所携带信息的详细等级。此操作支持“return=representation”和“return=minimal”首选项
响应

  1. 返回 200 OK：

    （1）return=minimal

    {
    "briefcases": [{
            "id": "2",
            "displayName": "#2 Device Name"
        },
        {
            "id": "3",
            "displayName": "#3 Device Name"
        }
    ],
    "_links": {
        "self": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/briefcases?$skip=0&$top=100"
        },
        "prev": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/briefcases?$skip=0&$top=100"
        },
        "next": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/briefcases?$skip=0&$top=100"
        }
    }
}

    （2）return=representation

    {
    "briefcases": [{
            "id": "2",
            "briefcaseId": 2,
            "displayName": "#2 Device Name",
            "ownerId": "42101fba-847a-4f4e-85a8-a4bed89065e4",
            "acquiredDateTime": "2020-10-20T10:51:33.1700000Z",
            "fileSize": 2048,
            "deviceName": "Device Name",
            "_links": {
                "owner": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/42101fba-847a-4f4e-85a8-a4bed89065e4"
                }
            }
        },
        {
            "id": "3",
            "briefcaseId": 3,
            "displayName": "#3 Device Name",
            "ownerId": "42101fba-847a-4f4e-85a8-a4bed89065e4",
            "acquiredDateTime": "2020-10-20T10:51:33.1700000Z",
            "fileSize": 2048,
            "deviceName": "Device Name",
            "_links": {
                "owner": {
                    "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/42101fba-847a-4f4e-85a8-a4bed89065e4"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/briefcases?$skip=0&$top=100"
        },
        "prev": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/briefcases?$skip=0&$top=100"
        },
        "next": {
            "href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/briefcases?skip=100&$top=100"
        }
    }
}

  2. 返回 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."
    }
}

  1. Response 422 (不可处理实体）

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

    {
    "error": {
        "code": "InvalidiModelsRequest",
        "message": "Cannot get Briefcases.",
        "details": [{
            "code": "InvalidValue",
            "message": "'-1' is not a valid '$skip' value. '$skip' must be a non-negative integer.",
            "target": "$skip"
        }]
    }
}

  2. Response 429 Too many requests：

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

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

响应头

名称 描述
retry-after 超过客户端订阅的速率限制的请求数
定义
  1. Briefcase（概述）：

briefcase 的概述

表：

名称 类型 描述
id String Briefcase 的 ID
displayName String Briefcase 的展示名称，对应 id 和 deviceName 属性

格式：

{
    "type": "object",
    "title": "Briefcase (summary)",
    "description": "Summarized representation of the Briefcase.",
    "properties": {
        "id": {
            "type": "string",
            "description": "Id of the Briefcase."
        },
        "displayName": {
            "type": "string",
            "description": "Display name of the Briefcase. Corresponds to id and deviceName properties."
        }
    }
}
  1. Briefcase：

Briefcase 是一个保存 iModel 副本的文件

表：

名称 类型 描述
id String briefcase 的 ID
briefcaseId Integer 整数形式的 briefcase 的 ID
displayName String Briefcase 的展示名称，对应 id 和 deviceName 属性
acquiredDateTime String 获得 briefcase 的时间
fileSize Integer briefcase 文件的大小，以字节表示
deviceName String 或 null 持有 briefcase 的设备名称
_links BriefcaseLinks 包含指向 briefcase 相关数据的超链接

格式：

{
    "type": "object",
    "description": "Briefcase is a file holding a copy of an iModel.",
    "properties": {
        "id": {
            "type": "string",
            "description": "Id of the Briefcase."
        },
        "briefcaseId": {
            "type": "integer",
            "description": "Id of the Briefcase as an integer."
        },
        "displayName": {
            "type": "string",
            "description": "Display name of the Briefcase. Corresponds to id and deviceName properties."
        },
        "acquiredDateTime": {
            "type": "string",
            "description": "Date when the Briefcase was acquired."
        },
        "fileSize": {
            "type": "integer",
            "description": "Size of the Briefcase in bytes."
        },
        "deviceName": {
            "type": [
                "string",
                "null"
            ],
            "description": "Name of the device which will hold the briefcase."
        },
        "_links": {
            "$ref": "#/components/schemas/BriefcaseLinks",
            "description": "Contains the hyperlinks to the related data of the Briefcase."
        }
    }
}

  1. Briefcase（首选项 prefer 设置为 return=minimal）：

    | 名称 | 类型 | 描述 | | ---------- | ------------------ | ------------------- | | Briefcases | BriefcaseSummary[] | iMpdel 的 briefcase |

    格式：

    {
    "type": "object",
    "title": "Briefcases (prefer return=minimal)",
    "description": "List of Briefcases in minimal representation.",
    "properties": {
        "Briefcases": {
            "type": "array",
            "description": "Briefcases of the iModel.",
            "items": {
                "$ref": "#/components/schemas/BriefcaseSummary"
            }
        }
    }
}

  2. Briefcase（首选项 prefer 设置为 return=representation）：

    | 名称 | 类型 | 描述 | | ---------- | ------------------ | ------------------- | | Briefcases | BriefcaseSummary[] | iMpdel 的 briefcase |

    {
    "type": "object",
    "title": "Briefcases (prefer return=representation)",
    "description": "List of Briefcases in full representation.",
    "properties": {
        "Briefcases": {
            "type": "array",
            "description": "Briefcases of the iModel.",
            "items": {
                "$ref": "#/components/schemas/Briefcase"
            }
        }
    }
}

  3. Briefcase 链接：

指向 briefcase 相关数据的超链接

表：

名称 类型 描述
owner Link briefcase 持有人的信息

格式：

{
    "type": "object",
    "title": "Briefcase Links",
    "description": "Hyperlinks to Briefcase related data.",
    "properties": {
        "owner": {
            "$ref": "#/components/schemas/Link",
            "description": "Information about the owner of the Briefcase."
        }
    }
}
  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 briefcase

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

删除指定的 briefcase。

Briefcase 是 iModel 的本地副本，用户可以获取这些副本来使用 iModel。用户可以对其 iModel 副本进行更改，然后将其作为单个变更集文件推送到 iModelHub 中。了解更多关于 briefcase 的信息请查看 https://www.itwinjs.org/learning/imodelhub/briefcases/ 。

认证

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

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

授权

要释放任意的 briefcase，用户必须在 iModel 级别上具备 imodels_manage 的权限。 如果在 iModel 级别上没有配置权限，那么用户必须在项目级别上有 imodels_manage 的权限。 要释放用户自己所拥有的 briefcase，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
briefcaseId template 是 Briefcase 的 ID
请求头
名称 是否必须 描述
Authorization 是 带有 imodels:modify 作用域的 OAuth 访问令牌
Accept 否 推荐设置为 application/vnd.bentley.itwin-platform.v1+json
请求 body

Briefcase（必须）

名称 类型 是否必须 描述
deviceName String 或 null 否 持有 briefcase 的设备的名称
例子
{
    "deviceName": "Device name"
}
响应

  1. 返回 204 No Content：

    No Content

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

（1）未找到指定的 iModel

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

（2）未找到指定的 briefcase：

{
    "error": {
        "code": "BriefcaseNotFound",
        "message": "Requested Briefcase 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 超过客户端订阅的速率限制的请求数
定义
  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"
    ]
}

results matching ""

    No results matching ""