上传组件到目录

简介

本教程将带您完成将组件上传到组织中目录的过程。

在本演练结束时，您将能够利用 API 端点将组件上传到目录，并将其他文档关联到上传的组件。

前提

本教程假设您已经有：

  • 可以用来执行 http 调用的工具，如 Postman。也可以使用 API 文档中的 TryIt 按钮进行这些调用。
  • 用户必须隶属于某个组织，并且应该是组织管理员，或者在组织级别具有 Upload 和 Read 权限，才能将组件上传到目录。
  • 有关用户管理的更多信息，请访问我们的 Bentley Communities Licensing、Cloud 和 Web Services wiki 页面。
  • 上传组件需要设计文件。设计文件是一种 CAD 文件，用于 CAD 应用程序，即 MicroStation、Revit 等。库 API 支持三种类型的文件来上传组件，即 rfa、dgn 和 cel。
  • 在本例中，我们将从 rfa 文件上传一个组件，尽管 dgn 和 cell 文件也可以用于上传组件，步骤相同。你应该有一个这样的文件来上传一个组件。

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-授予应用程序的访问列表。在应用程序详细信息页面上显示为作用域。

或者：按照注册和修改应用程序教程中的说明手动注册和配置应用程序。确保您的应用程序与 iModels, Library, RealityData and Storage APIs 关联，并且具有 realitydata:read imodels:read imodels:modify library:read library:modify storage:read storage:modify 作用域(scope)。

2. 获取令牌 (Token)

在向 API 发出请求之前，需要一个用户令牌。有几种方法可以得到它。

2.1 在应用程序中实现授权代码流

遵循本文在应用程序中实现授权代码工作流。

在这里，您可以使用之前注册步骤生成的客户端 ID。

2.2 从 API 参考“Try it”部分获取用户令牌

  1. 点击这里
  2. 点击 Try it 按钮。
  3. 在授权(Authorization)部分，从下拉列表中选择 authorizationCode。
  4. 登录弹出窗口关闭后，带有令牌值的授权(Authorization)标头应该在 HTTP 请求下拉列表下可见。
  5. 复制并粘贴本教程的授权值(Authorization)。

在接下来的步骤中，使用用户令牌替换 JWT 令牌动态参数。

3. 创建新的目录

库 API 用于创建和管理目录。发送 POST https://api.bentley.com/library/catalogsendpoint 将创建一个新目录。创建新目录只需要 displayName。它必须是唯一的，因此如果出现冲突错误，则需要将 displayName 替换为唯一值。有关不同属性的描述，请参阅库 API 文档。

POST 调用将返回一个新的目录实例。id 可用于将组件上传到目录。目录 Id 也用于其他库 API 端点。您可能希望保存此 Id 以在其他端点中使用。

如果您已经拥有现有目录的 id，则可以使用它上传组件，而不是创建新目录。

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

{
    "displayName": "Tutorial Sample Catalog",
    "description": "Tutorial Sample Description",
    "region": "US",
    "hashtags": ["SampleHashtag1", "SampleHashtag2"]
}

4. 引用实体

组件可以具有引用实体，即类别、应用和制造商。这些是要上传的组件的可选属性，如果请求正文中未提供此信息，则上传过程将尝试从设计文件中提取相同的属性，前提是设计文件包含此信息。

库 API 提供端点来创建和管理这些引用的实体。在本例中，我们不会在上传中使用引用的实体，而是使用设计文件中提供的信息。

您可以在库 API 文档中使用以下 TryIt 选项来创建这些实体。

5. 上传组件

可以使用 rfa、dgn 或 cel 文件上传组件。在本例中，我们将使用 rfa 文件将组件上传到目录。上传组件是一个多步骤的过程。使用 upload request body 发出上传请求，然后上传设计文件和/或 TypeCatalog 文件，然后可以选择向新上传的组件添加任何其他参考文档。TypeCatalog 文件仅可选地与 rfa 文件一起使用，因此在 dgn 或 cel 文件的情况下不需要这样做。

5.1 生成上传组件请求

在第一步中，创建 upload component 请求主体并 POST https://api.bentley.com/library/upload-component 到终端。通过将 isTypeCatalog 属性设置为 true，可以将组件设置为“TypeCatalog” 组件。TypeCatalog 组件需要上传文本文件（必须有 txt 扩展名）以及设计文件。

在本例中，我们将使用 TypeCatalog 组件。将组件上传到目录只需要文件名和 CatalogID，如果未提供 CatalogID，组件将上传到用户组织，并且不属于任何目录。向 CatalogID 字段提供 catalog Id（在前面的步骤中检索），此字段需要 CatalogID 的集合，如果一个组件应上传到多个目录，则可以在此字段中提供多个 catalog Id。

上传是一项长期运行的活动，响应包含位置标题值，这将用于跟踪进度。您可能希望保存此标题值，这将在接下来的步骤中使用。

有关不同属性的描述，请参阅库 API 文档。

POST https://api.bentley.com/library/upload-component HTTP/1.1

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

{
    "fileName": "TutorialSampleFile.rfa",
    "componentName": "Tutorial Sample Component",
    "description": "Tutorial Sample Description",
    "searchTags": [
        "SampleTag1",
        "SampleTag2"
    ],
    "catalogs": [
        "7f427c30-8dce-4803-81dc-e8681a3bd757"
    ],
    "category": null,
    "application": null,
    "manufacturer": null,
    "isTypeCatalog": true
}

5.2 上传文件

上传请求的响应包含用于在_links 属性值下上传文件的临时 URL。请注意，在本例中有两个 URL，_links->designFileUploadUrl 上传设计文件，由于这是一个 TypeCatalog 组件，因此还有另一个 url， _links->TypeCatalogploadUrl 上传 TypeCatalog 文本文件。如果在上传请求中 isTypeCatalog 属性设置为 false，响应将只有一个文件上传 url _links->designFileUploadUrl。在上传设计文件之前，必须上传 TypeCatalog 文本文件。

文件上传可以通过 Postman 等工具在提供的 url 上发出 Http PUT 请求，或者通过编程使用 Azure 库上传文件(https://docs.microsoft.com/en-us/rest/api/storageservices/put-blob).

PUT https://componentscenprodeussa01.blob.core.windows.net/private-temporary-type-catalog-files/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288.typecatalog?sv=2018-03-28&sr=b&sig=cpt24N23osjV3be6KmAHU2T%2FweVO0%2Fb%2FcRLFS3nQYW0%3D&se=2021-09-06T16%3A15%3A22Z&sp=rcw HTTP/1.1

x-ms-blob-type: BlockBlob

TypeCatalog File Binary Content

5.3 获取上传状态

上传组件是一个长期运行的活动，在后台运行，一旦设计文件上传完成，它就会启动。上传请求的响应包含位置标头，其中包含具有当前上传作业 id 的作业端点，用于跟踪后台上传活动的状态。对位置头值进行 GET 调用(https://api.bentley.com/library/jobs/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288) 获取上传作业状态。上传活动成功完成后，作业终结点“状态”属性值的响应将为“成功”。此时，上传组件已完成，并创建了一个新组件。Response 还在_links->component->href属性下提供指向这个新创建组件的链接，该属性可用于从存储库中检索组件。

GET https://api.bentley.com/library/jobs/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288 HTTP/1.1

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

5.4 获取组件

上一步作业响应中的属性_links->component->href 为上传活动期间创建的组件提供端点。调用此端点 ( https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7) 检索组件。响应包含组件，您可以注意到在响应中的_links 属性下，有关于组件引用实体的信息/链接，即应用程序、制造商和类别。这是在上传活动期间从设计文件中提取的。只有在上传过程中使用的设计文件包含有关引用实体的信息时，才能提取此信息。

GET https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7 HTTP/1.1

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

5.5 修改组件

上传组件后，下一步可以对组件进行更改。发送 PUT 给 https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7 端点更新组件。让我们更改组件的“state”属性。默认情况下，在上传时，组件“状态”属性设置为“草稿（Draft）”。此属性可以包含枚举值草稿、发布、检查、批准和存档。让我们将该值设置为“Published”。另请注意，更新组件请求正文必须包含所有所需的属性，因为这将用当前组件定义替换现有组件。

有关不同属性的描述，请参阅库 API 文档。

PUT https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7 HTTP/1.1

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

{
    "displayName": "Tutorial Sample Component",
    "description": "Tutorial Sample Description",
    "state": "Published",
    "catalogs": [
        "7f427c30-8dce-4803-81dc-e8681a3bd757"
    ],
    "category": "63b7d70a-a426-4530-8c0f-3efd6a6c0da7",
    "application": "1418693a-8f60-4719-af0b-ceee1ad41e33",
    "manufacturer": "d4485150-ad6d-4d76-a3e2-50a0f690afc9",
    "hashtags": ["SampleTag1", "SampleTag2"]
}

6. 添加文档

上传组件活动在过程中将少量文档关联到组件。在前面的步骤中上传的设计文件和类型目录文件分别作为组件设计和类型目录文档与组件关联。上传过程还从设计文件中获取缩略图，并将其关联为缩略图文档。还可以在创建组件后关联其他文档。可以将参考文档、图像甚至其他设计文件与零部件关联。在本例中，我们将引用文档与组件关联，其他文档也可以与相同的步骤关联，唯一的区别是在文档请求体中设置“purpose”属性的值。

有关不同属性的描述，请参阅库 API 文档。

添加文档是一个多步骤的过程，我们将在下一步完成这些步骤。

6.1 创建文档实例

发送 POST https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documentsendpoint 请求将为组件创建一个新的文档实例。displayName、purpose 和 extension 是必需的属性。purpose 可以有枚举值 Design、缩略图、Reference、GalleryImage 和 TypeCatalog，具体取决于要与组件关联的文档类型。当我们关联参考文件时，目的应设置为“参考”。POST 调用将返回一个新的文档实例。该 id 将在接下来的步骤中使用，您可能希望保存该 id。此时，一个文档实例已与该组件关联，但没有实际的文件附加到此文档。我们将在下一步中这样做。

POST https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents HTTP/1.1

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

{
    "displayName": "Tutorial Sample Document",
    "extension": "pdf",
    "purpose": "Reference",
    "available": false,
    "isActive": true,
    "version": null,
    "previousVersionId": null,
    "associatedDesignDocument": null
}

6.2 上传文档文件

上一步中的“创建文档”响应在_links->fileUrl->href 属性中包含一个 url。文件上传可以通过 Postman 等工具在提供的 url 上发出 Http PUT 请求，或者通过编程使用 Azure 库上传文件(https://docs.microsoft.com/en-us/rest/api/storageservices/put-blob).

PUT https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/bf15e508-3b59-49d5-a1b5-ea9ef9d66515.pdf?sv=2018-03-28&sr=b&sig=oft6xWrKourfRl5Nemd03duMS9pmi8zkiaPSE8Pynzw%3D&se=2021-09-08T10%3A51%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorial%2BSample%2BDocument.pdf HTTP/1.1

x-ms-blob-type: BlockBlob

File Binary Content

6.3 更新文档实例

将文档与组件关联的最后一步是通知系统文件已上传。这是通过将文档实例的“available”属性设置为 true 来实现的。发送 PUT https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/bf15e508-3b59-49d5-a1b5-ea9ef9d66515 请求端点来更新文档。更新请求正文必须包含所有所需的属性，因为这将用当前文档定义替换现有文档。

PUT https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/bf15e508-3b59-49d5-a1b5-ea9ef9d66515 HTTP/1.1

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

{
    "displayName": "Tutorial Sample Document",
    "extension": "pdf",
    "version": null,
    "previousVersionId": null,
    "purpose": "Reference",
    "available": true,
    "isActive": true
}

6.4 获取文档组件

发送 http PUT 请求到 https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents 端点以获取与组件关联的所有文档。在本例中，我们将从前面步骤中上传的组件中获取文档。请注意，回复包含四个文档实例。其中三个文档设计、缩略图和 TypeCatalog 是在上传活动期间创建并关联到组件的，而我们在创建组件后分别关联了参考文档。您可以从响应中每个文档实例的\_links->fileUrl-href 属性值中提供的 url 下载实际文件。您还可以使用以下 API 根据特定文档的 Id 获取该文档。

通过 id 获取文档

GET https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents HTTP/1.1

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

results matching ""

    No results matching ""