实景数据 API 使用

• 实景数据 API 使用
  • 简介
  • 前提
    • 建议使用调试工具
  • 1. 注册应用程序
  • 2. 获取令牌 (Token)
  • 3. 创建实景数据
    • 3.1 上传实景模型
  • 4. 获取实景数据
    • 4.1 定制化实景数据请求
    • 4.2 查看您的实景数据
  • 5. 修改实景数据
    • 5.1 修改您的数据实景模型
  • 6. 管理实景数据关联到多个项目
    • 6.1 关接实景数据到项目
    • 6.2 从项目分离实景数据
  • 7. 删除实景数据
  • 8. 实景的属性信息
    • 8.1 访问控制
    • 8.2 授权
    • 8.3 分类及类型
      • 8.3.1 分类
      • 8.3.2 类型
    • 8.4 数据中心位置
    • 8.5 采集
    • 8.6 范围
    • 8.7 大小

简介

RealityData API 为您提供了管理和共享现实模型的能力。本教程将帮助您开始使用 RealityData API。 本教程将指导您完成：

• 创建、修改和删除 RealityData
• 将 RealityData 与项目关联和分离
• 上传和下载现实模型到 RealityData

前提

• 一个实景模型，如 .3mx 文件
• 已创建项目
  • 如需创建项目，可点击此连接

创建的项目必须有一个包含分配给您自己的RDS_ASSIGN, RDS_CREATE, RDS_MANAGE and RDS_USE权限的角色。通过 Projects API 创建的项目应自动授予您必要的权限。有关管理项目的更多信息，请参阅projects API。

建议使用调试工具

• Postman 如果想直接测试 REST API 调用，可以使用 Postman 或任何其他能够发送 HTTP 请求的解决方案。如果这样做，则需要一个授权令牌才能使请求生效。这将在下面的“获取令牌”部分介绍。

1. 注册应用程序

您需要注册一个应用程序才能使用 iTwin 平台 API。您可以使用按钮(Register)自动创建第一个单页应用程序（SPA）。这将允许您为 SPA 应用程序配置授权代码流，并获得正确的访问令牌。

生成后，按钮下会显示几行代码。

• IMJS_AUTH_CLIENT_CLIENT_ID-这是应用程序的唯一标识符。在应用程序详细信息页面上显示为客户端 ID。
• IMJS_AUTH_CLIENT_REDIRECT_URI-指定用户选择是否验证应用程序后重定向到的位置。在应用程序详细信息页面上显示为重定向 URI 之一。
• IMJS_AUTH_CLIENT_LOGOUT_URI-指定用户注销后可以返回的位置。在应用程序详细信息页面上显示为注销后重定向 URI 之一。
• IMJS_AUTH_CLIENT_SCOPES-授予应用程序的访问列表。在应用程序详细信息页面上显示为作用域。

或者：按照注册和修改应用程序教程中的说明手动注册和配置应用程序。确保您的应用程序与 RealityData、iModels、Synchronization、Digital Twin Management 和 Administration 关联，并且具有synchronization:modify realitydata:modify export:read projects:read users:read projects:modify library:read realitydata:read imodels:modify storage:read export:modify synchronization:read imodels:read storage:modify 作用域(scope)。

2. 获取令牌 (Token)

要向 API 发出请求，需要一个用户令牌。有几种方法可以得到它。您可以在此处查阅授权 API 文档，也可以在此处使用示例 powershell 脚本在应用程序中使用。

3. 创建实景数据

在使用 RealityData API 时，您将主要使用 RealityData 对象。该类定义了描述真实数据内容的属性，并使用 Microsoft Azure 存储技术提供了对 blob 容器中存储的数据的访问点。

RealityData 属性表示与现实数据相关的描述性数据。除此之外，真实数据内容还存储为与该真实数据唯一关联的 blob 容器中的文件和文件夹。从真实数据的根开始，单个文件和文件夹遵循一种正常的文件树结构。

使用 https://api.bentley.com/realitydata HTTP POST 请求创建 RealityData。 目前，创建 RealityData 所需的属性包括：

• DisplayName：实景数据的名称
• Classification: 例如“Model”
• Type: 例如“3mx”

成功创建 RealityData 后，将生成 id 属性，并将其用作其唯一标识符。

POST https://api.bentley.com/realitydata HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

 {
    "projectId": "d8414d06-560e-49da-81a5-f7204fa4457b",
    "realityData": {
        "displayName": "Name of the reality data to create",
        "classification": "Model",
        "type": "3mx",
        "description": "Description of the reality data",
        "dataset": "Dataset",
        "group": "GroupId",
        "rootDocument": "Models/Scene/myModel.3mx",
        "acquisition": {
            "startDateTime": "2021-05-12T20:03:12Z",
            "endDateTime": "2021-05-15T05:07:18Z",
            "acquirer": "Data Acquisition Inc."
        },
        "extent": {
            "southWest": {
                "latitude": 40.0206,
                "longitude": -75.6355
            },
            "northEast": {
                "latitude": 40.0356,
                "longitude": -75.6059
            }
        },
        "authoring": false
    }
  }

更多 API 字段可参考： https://developer.bentley.com/apis/reality-data/operations/create-reality-data/

3.1 上传实景模型

创建真实数据后，可以将实景模型附加到它。通过 https://api.bentley.com/realitydata/{id}/container/？projectId={projectId}access=Write HTTP GET 请求将为您提供具有写访问权限的 SAS URL。

要使用此资源，您可以查阅 Microsoft 文档。

或者，如果您还没有实景模型，并且希望生成自己的实景模型，那么您可能对 ContextCapture 感兴趣。

GET https://api.bentley.com//realitydata/69401bde-6200-4c6c-b783-046f1935e825/container/?projectId=615f57e7-876e-46fc-ab11-79af30cae299&access=Write HTTP/1.1

Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

4. 获取实景数据

有几种方法可以查询您的真实数据。取决于你正在开发的应用程序，其中一个可能比另一个更有用。您可能需要获取一个或多个 RealityData。

一旦创建了 RealityData，就可以 GET https://api.bentley.com/realitydata 请求将是获取您创建的 RealityData 的路径。按原样使用此调用将返回您有权访问的前 100 个 RealityData（相对于您组织的访问权限）。

GET https://api.bentley.com/realitydata/?projectId={projectId} 请求将返回给定项目下相对于项目访问权限的前 100 个 RealityData。只要你有权限。为进一步查询提供了延续令牌。

GET https://api.bentley.com/realitydata/{id} 请求只会返回带有给定标识符的 RealityData，前提是您有权访问它。

GET https://api.bentley.com/realitydata?projectId=ec002f93-f0c1-4ab3-a407-351848eba233&$top=2 HTTP/1.1

Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Prefer: return=representation
Content-Type: application/json

更多 API 字段可参考： https://developer.bentley.com/apis/reality-data/operations/get-all-reality-data/

4.1 定制化实景数据请求

可选参数可用于自定义 RealityData 请求：

• projectId：项目标识符
• continuationToken： 可获取当前查询的更多真实数据
• $top： 查询每个页面中要获取的大量 realityData
• extent：在要搜索的特定区域中查询 RealityData 的范围

有关上述参数的更多信息，请参阅 RealityData API 文档。

查询多个 RealiyData 时，prefere:return=representation 标头将指示 API 返回每个 RealiyData 上的所有属性。否则，只返回最少的信息，例如 id、displayName 和 type。

4.2 查看您的实景数据

GET https://api.bentley.com/realitydata/{id}/container/？projectId={projectId}permissions=Read 请求将为您提供具有读取权限的 SAS URL。这将允许您下载 RealityData 的内容。

您可能需要参考这个iTwinjs 示例，以获得一个显示现实模型的快速示例。

GET https://api.bentley.com//realitydata/69401bde-6200-4c6c-b783-046f1935e825/container/?projectId=615f57e7-876e-46fc-ab11-79af30cae299&access=Write HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

5. 修改实景数据

如果您在正在使用的项目中拥有足够的权限，或者您是 RealityData 的所有者，则可以随意修改 RealityData 属性。使用https://api.bentley.com/realitydata/{id} 修改现有 RealityData 的 PATCH HTTP 请求。

有关可以使用和修改的属性的详细列表，请参阅文档的 RealityData 属性页。

PATCH https://api.bentley.com/realitydata/69401bde-6200-4c6c-b783-046f1935e825 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

{
    "projectId" : "615f57e7-876e-46fc-ab11-79af30cae299",
    "realityData":
    {
        "id": "69401bde-6200-4c6c-b783-046f1935e825",
        "displayName": "Modified displayname",
        "dataset": "Dataset",
        "group": "xxx",
        "description": "Lorem ipsum 2...",
        "classification": "Model",
        "type": "3mx"
    }
}

5.1 修改您的数据实景模型

您可以参考本指南的第 3.1 节，因为它与 GET 操作相同 https://api.bentley.com/realitydata/{id}/container/?projectId={projectId}access=Write 请求将为您提供具有写访问权限的 SAS URL。从那里，你可以改变现实模型的内容。

6. 管理实景数据关联到多个项目

根据你的现实模型的用途，你可能会发现让你的现实模型在多个项目中可用是有用的，因此它是真实的数据。RealityData API 利用 Projects API 的优势，将您的模型提供给其他人。

可以采取一下两种方法：

• 将 RealityData 与项目关联
• 将 RealityData 与项目分离

6.1 关接实景数据到项目

PUT https://api.bentley.com/realitydata/{id}/projects/{projectId} http 请求将向所需项目添加关联，如 projectAssociation 所示。

PUT https://api.bentley.com/realitydata/69401bde-6200-4c6c-b783-046f1935e825/projects/615f57e7-876e-46fc-ab11-79af30cae299 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

6.2 从项目分离实景数据

DELETE https://api.bentley.com/realitydata/{id}/projects/{projectId} http 请求将从所需项目中删除关联。

DELETE https://api.bentley.com/realitydata/69401bde-6200-4c6c-b783-046f1935e825/projects/615f57e7-876e-46fc-ab11-79af30cae299 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

7. 删除实景数据

一旦不再需要 RealityData，您可以使用 DELETE HTTP 请求将其删除 https://api.bentley.com/realitydata/{id} 。收到 204 No Content 响应（表示删除成功）后，RealityData 资源及其实景模型将被删除。无需使用具有写入权限的 GET http 请求手动删除实景模型。

DELETE https://api.bentley.com/realitydata/69401bde-6200-4c6c-b783-046f1935e825 HTTP/1.1
Authorization: Bearer JWT_TOKEN
Accept: application/vnd.bentley.v1+json
Content-Type: application/json

更多 API 字段可参考： https://developer.bentley.com/apis/reality-data/operations/delete-reality-data/

如果您的 RealityData 与多个项目关联，则必须首先将其与每个项目分离，但一个项目除外。见第 6.2 节。请注意，您必须在项目中拥有足够的权限才能删除 RealityData。

注意：RealityData API 不支持“回收站”功能。删除 RealityData 会立即删除实景模型，并且无法恢复。

8. 实景的属性信息

本页详细介绍 RealityData 属性。下面是一个属性列表，它们的类型，以及它们的描述。更重要的是，下面的一些属性有关于它们的附加信息。

RealityData 必须使用下面列出的必需属性：

• displayName
• classification
• type

8.1 访问控制

每个实景数据都关联一个 AccessControl 属性，该属性可以采用四个值中的一个，这四个值指示谁可以使用数据，如下所述。

• Public：表示任何人，甚至组织外部的用户都可以使用数据
• Organization：表示该数据所属组织的任何成员都可以使用该数据
• Project：表示数据只能作为项目的一部分使用
• Private：只有所有者才能使用数据

8.2 授权

Authoring 属性值不受 RealityData API 控制，由应用程序管理。该值也不会更改 API 的行为。此属性的目的是显示是否正在将新模型数据上传到 RealityData。当 RealityData 由多个用户共享或管理时，这一点尤其有用。由应用程序的创建者在使用 Authoring 属性值的应用程序中实现行为。

8.3 分类及类型

8.3.1 分类

虽然分类定义了 RealityData 的性质，但它与 Type 属性相关。

当前支持以下值：

• Terrain：数据是地形的表示
• Imagery：数据是垂直、卫星或正射影像
• Pinned：任何可能固定在地球上某个位置的非地理数据
• Model：最常见的分类。数据是真实世界对象或特征的模型化
• Undefined：用于非实景数据，用作实景数据创建的输入

8.3.2 类型

Reality Data 的 Type 属性表示 Reality Data 中包含的数据的格式。虽然 Type 字段是一个自由字符串，但保留了一些特定的值。

以下是保留的关键字：

通常使用其他类型来清楚地指示类型。例如，可以使用 tif、jpg、pdf，并且预期格式清晰。在大多数情况下，这种格式明确规定了分类。点云、3MX 必然是模型数据，因为它们是对现实世界的建模。另一方面，某些格式可以有不同的分类。例如，当像素是高程数据或卫星数据的图像时，tif 格式支持地形数据的存储。同样地，jpg 文件可以表示正射影像（图像）或特征的倾斜图片（邻里、人等），然后这些将被分类为固定数据。类似地，pdf 文档可以是书面文档（固定）或地图（模型）。

8.4 数据中心位置

DataCenterLocation 表示数据中心位置。RealityData API 支持许多地理位置不同的数据位置。通常，数据中心的位置与创建真实数据的 CONNECT 项目相同。 RealityData API 使用的数据中心位置包括：

• 美国东部
• 北欧
• 东南亚
• 日本东部
• 英国南部
• 澳大利亚东部

8.5 采集

采集对象包括符合 ISO-8601 标准的数据采集开始时间和结束时间（UTC）以及收单机构。采集信息是一个文本，表明数据是由谁或什么实例或过程获取的。见下面的例子：

"acquisition": {
          "startDateTime": "2021-05-12T20:03:12Z",
          "endDateTime": "2021-05-15T05:07:18Z",
          "acquirer": "Data Acquisition Inc."
      },

8.6 范围

范围包含地球上包含真实数据的矩形区域。由最西南点和最东北点定义。纬度和经度类型是 double。见下面的例子：

"extent": {
              "southWest": {
                  "latitude": 50.1171,
                  "longitude": -122.9543
              },
              "northEast": {
                  "latitude": 50.1172,
                  "longitude": -122.9543
              }
          },

8.7 大小

在模型数据成功上传到 RealityData 后，无论是由于 RealityData 的创建还是修改，都会计划重新计算 Size 属性。此过程可能需要几分钟，因此上载完成后，大小值可能不会立即准确。对于大型型号的上传，这意味着几 GB 或更多，这个过程可能需要更长的时间。