创建一个组件

创建一个组件

简介

本教程将带您完成在组织中创建组件的过程。

在本演练结束时，您将能够利用 API 端点来创建组件及其变体、文档和 Web 链接。

前提

本教程假设您已经有：

可以用来执行 http 调用的工具，如 Postman。也可以使用 API 文档中的 TryIt 按钮进行这些调用。
用户必须隶属于某个组织，并且应该是组织管理员，或者在组织级别具有 Upload 和 Read 权限，才能将组件上传到目录。
有关用户管理的更多信息，请访问我们的 Bentley Communities Licensing、Cloud 和 Web Services wiki 页面。
大多数情况下，组件应该有一个与组件关联的设计文件，作为设计文档的一部分。设计文件是一种 CAD 文件，用于 CAD 应用程序，如 MicroStation、Revit 等。库 API 支持所有类型的设计文件来创建组件。您应该有一个设计文件作为设计文档与组件相关联。从理论上讲，一个组件可以不带任何文件而存在，但这可能并不有益。在本例中，我们将使用 rfa 设计文件。

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”部分获取用户令牌

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

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

3. 上传组件和创建组件的区别

库 API 提供了两个选项来在组织存储库中添加组件，即上传组件和创建组件。

上传组件要求在系统中上传设计文件，后台上传作业从设计文件中提取信息，即缩略图、变体、制造商、类别和应用程序等。上传活动使用所有这些信息创建组件，并将所有这些元数据与组件关联。这节省了多次请求将信息添加到组件的工作量。目前，上传组件仅支持三种类型的设计文件，即 rfa、dgn 和 cel 文件。

可以在此处找到将组件上传到目录的说明。

我们可以在不使用上面解释的上传工作流的情况下添加组件，但这需要在调用 API 端点方面付出更多努力，因为我们必须发出额外的请求，以添加缩略图文档、创建制造商、应用程序、类别（如果需要），以及在组件中添加变体。因此，如果设计文件是 rfa、dgn 或 cel，建议使用上传工作流。在本教程中，我们将创建不带上传工作流的组件。

POST https://api.bentley.com/library/catalogs HTTP/1.1

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. 引用实体

组件可以有参考实体，即目录、类别、应用和制造商。这些是要创建的组件的可选属性，但提供了有用的信息。制造商，顾名思义，是部件的制造商。应用程序指定 CAD 应用程序，一个组件可以用于不同的目的。类似地，类别和目录用于对组件进行分组。您需要有每个实体的 id 属性值才能用于组件创建。如果还没有，库 API 将提供端点来创建和管理这些引用的实体。如果适用于组件，可以创建这些实体，并且可以保存每个实体的 id 属性，以便在接下来的步骤中使用。

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

5. 创建组件

要创建组件，请准备 htpp POST 请求 https://api.bentley.com/library/create-component。`displayName` 和 state是必需的属性。提供适当的 displayName 值，我们有一个门的 rfa 文件，所以让我们将 displayName 设置为“教程示例门”。状态属性可以具有枚举值草稿、发布、检查、批准和存档，这些值在组件生命周期的不同阶段使用。目前，我们将 “Draft” 赋值。我们已经有了引用实体的 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

{
    "displayName": "Tutorial Sample Door",
    "description": "Tutorial Sample Door",
    "state": "Draft",
    "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": [
        "samplehashtag1",
        "samplehashtag2"
    ]
}

6. 添加文档

在这个阶段，创建了一个组件，但它没有任何文档。可以将设计、参考、缩略图和 GalleryImage 文档与组件关联。在本例中，我们将一个设计文档与组件相关联，其他文档也可以与相同的步骤相关联，唯一的区别是在文档请求体中设置“purpose”属性的值。您应该在文档创建过程中上传相应的图像和参考文件，具体取决于您正在创建的文档。

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

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

6.1 创建文档实例

发送 http POST https://api.bentley.com/library/components/afd712cf-db65-46fa-a05d-9c6bc8be0d1f/documents 请求，将为组件创建一个新的文档实例。displayName、purpose 和 extension 是必需的属性。purpose 可以有枚举值 Design、缩略图、Reference、GalleryImage 和 TypeCatalog，具体取决于要与组件关联的文档类型。在关联设计文档时，应将目的设置为 “Design” 。

POST 调用将返回一个新的文档实例。该 id 将在接下来的步骤中使用，您可能希望保存该 id。此时，一个文档实例已与该组件关联，但没有实际的文件附加到此文档。我们将在下一步中这样做。

POST https://api.bentley.com/library/components/afd712cf-db65-46fa-a05d-9c6bc8be0d1f/documents HTTP/1.1

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

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

6.2 上传文档文件

上一步中的“创建文档”响应在_links->fileUrl->href 属性中包含一个 url。文件上传可以通过 Postman 等工具在提供的 url 上发出 Http PUT 请求，或者通过编程使用 Azure 库上传文件。

PUT https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/afd712cf-db65-46fa-a05d-9c6bc8be0d1f/648486bf-6f04-4750-aa67-7fe521d01896.rfa?sv=2018-03-28&sr=b&sig=03LfBtIfpFgpOnQPp4YaEj%2BbSsNBXQE1XOd83J6tXrA%3D&se=2021-09-09T16%3A29%3A08Z&sp=rcw&rscd=attachment%3B%20filename%3DTutorial%2BSample%2BDesign%2BDocument.rfa HTTP/1.1

x-ms-blob-type: BlockBlob

File Binary Content

根据 Response 返回的 "typeCatalogUploadUrl" 或 "designFileUploadUrl" 将组件上传至该路径内。此 uploadUrl 为 Azure SAS Token, 可采用 AzCopy 等工具上传。

6.3 更新文档实例

将文档与组件关联的最后一步是通知系统文件已上传。这是通过将文档实例的“available”属性设置为 true 来实现的。发送 http PUT https://api.bentley.com/library/components/afd712cf-db65-46fa-a05d-9c6bc8be0d1f/documents/648486bf-6f04-4750-aa67-7fe521d01896 请求端点来更新文档。更新请求正文必须包含所有所需的属性，因为这将用当前文档定义替换现有文档。

PUT https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/afd712cf-db65-46fa-a05d-9c6bc8be0d1f HTTP/1.1

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

{
    "displayName": "Tutorial Sample Design Document",
    "extension": "rfa",
    "version": "1",
    "previousVersionId": null,
    "purpose": "Design",
    "available": true,
    "isActive": true
}

Response Body

{
  "document": {
    "id": "648486bf-6f04-4750-aa67-7fe521d01896",
    "displayName": "Tutorial Sample Design Document",
    "extension": "rfa",
    "version": "1",
    "previousVersionId": null,
    "purpose": "Design",
    "size": 0,
    "available": true,
    "isActive": true,
    "createdDateTime": "2021-09-09T15:29:08.3172685Z",
    "lastModifiedDateTime": "2021-09-10T05:28:03.4442503Z",
    "_links": {
      "fileUrl": {
        "href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/afd712cf-db65-46fa-a05d-9c6bc8be0d1f/648486bf-6f04-4750-aa67-7fe521d01896.rfa?sv=2018-03-28&sr=b&sig=lTnFsfrQmEqIdEMqLD%2FQ%2FjEQTAjL5T5Y8mFsR8idPQ4%3D&se=2021-09-10T06%3A28%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorial%2BSample%2BDesign%2BDocument.rfa"
      }
    }
  }
}

7. 添加变体

一个组件可以有不同的变体，变体本质上是同一组件的不同型号、尺寸和类型。由于组件本身有固定的模式，所以也可以使用变体来添加与组件相关的其他元数据。即使没有多个变体可用，也可以创建一个默认变体，以添加无法直接添加到组件中的任何其他特性。组件的核心是设计文件，因为组件可以有多个设计文件，每个设计文件可以有自己的变体。associatedDesignDocument 属性用于设置相应的设计文件 id，以便将变体连接到组件中的设计文件。

发送 http POST https://api.bentley.com/library/components/afd712cf-db65-46fa-a05d-9c6bc8be0d1f/variations 请求将创建一个新的变体。让我们为本例中创建的组件添加一个变体，我们将在前面的步骤中创建的设计文档的 id 分配给请求正文中的 associatedDesignDocument。为变体添加适当的显示名称。变体具有包含 displayName、value、type 和 unitOfMeasure 的临时属性列表。type 是枚举，可以有 StringType、IntegerType、DoubleType、FloatType 和 BooleanType。临时属性使您能够更好地控制向组件添加任何类型的元数据/属性。在我们的示例中，我们可以通过添加门尺寸及其材质来添加特殊属性。对于物料而言，计量单位不适用，所以我们可以在这种情况下将该字段留空。

有关不同属性的描述，请参阅库 API 文档以创建变体。

请参阅库 API 文档以获取变体。

POST https://api.bentley.com/library/components/afd712cf-db65-46fa-a05d-9c6bc8be0d1f/variations HTTP/1.1

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

{
    "associatedDesignDocument": "648486bf-6f04-4750-aa67-7fe521d01896",
    "displayName": "Sample Variation for Door",
    "adHocProperties": [{
        "displayName": "Width",
        "value": "50",
        "type": "DoubleType",
        "unitOfMeasure": "Millimeters"
    }, {
        "displayName": "Height",
        "value": "2200",
        "type": "DoubleType",
        "unitOfMeasure": "Millimeters"
    }, {
        "displayName": "Length",
        "value": "900",
        "type": "DoubleType",
        "unitOfMeasure": "Millimeters"
    }, {
        "displayName": "Material",
        "value": "Wood",
        "type": "StringType",
        "unitOfMeasure": ""
    }]
}

8. 增加 Web 链接

您可以在组件中添加的另一个可选相关实体是 Web 链接。组件可以在 web 上有一些相关材料、一些规范文档、描述或任何相关信息。您可以将 web url 作为 web 链接添加到组件中。发送 http POST https://api.bentley.com/library/components/afd712cf-db65-46fa-a05d-9c6bc8be0d1f/weblinks 请求将创建一个新的 Web 链接。

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

请参阅库 API 文档以获取 Web 链接。

POST https://api.bentley.com/library/components/afd712cf-db65-46fa-a05d-9c6bc8be0d1f/weblinks HTTP/1.1

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

{
    "displayName": "Tutorial sample webLink",
    "uri": "https://www.sampleweblink.com/sampleweblink"
}

创建一个组件

创建一个组件

简介

前提

1. 注册应用程序

2. 获取令牌 (Token)

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

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

3. 上传组件和创建组件的区别

4. 引用实体

5. 创建组件

6. 添加文档

6.1 创建文档实例

6.2 上传文档文件

6.3 更新文档实例

7. 添加变体

8. 增加 Web 链接

results matching ""

No results matching ""