从目录中查询或下载组件
简介
本教程将带您了解从组织中的目录查询组件的过程。
在本演练结束时,您将能够利用 API 端点从目录中查询组件,并从组件下载相关文件。
前提
本教程假设您已经有:
- 可以用来执行 http 调用的工具,如
Postman
。也可以使用 API 文档中的 TryIt 按钮进行这些调用。 - 用户必须隶属于某个组织,并且应该是组织管理员,或者在组织级别具有 Upload 和 Read 权限,才能将组件上传到目录。
- 有关用户管理的更多信息,请访问我们的 Bentley Communities Licensing、Cloud 和 Web Services wiki 页面。
- 包含少数组件的目录已经存在,并且用户具有该目录的 id。
- 可以在此处找到将组件上传到目录的说明
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 提供 https://api.bentley.com/library/components 查询组件的端点。当请求中没有提供查询参数时,将返回组织中的所有组件。您可以设置 $top
和 $skip
查询参数,以指定响应中的特定页面和组件数。查询参数 projectId
用于对项目上下文进行查询的情况,但我们不会使用它,因为在本教程中我们讨论的是组织上下文。在接下来的步骤中,我们将使用此端点目录的两个查询参数和$search
从目录中查询组件。
有关更多详细信息,请参阅库 API 文档以获取组件。
3.1 从目录中查询所有的组件
我们已经有一个 id
为 7f427c30–8dce-4803–81dc-e8681a3bd757 的目录,它有三个组件。通过向目录查询参数提供目录 Id,可以获取目录中的所有零部件。catalogs query 参数可以接受由多个目录 Id 组成的逗号分隔字符串,以从多个目录返回组件,但在本教程中,我们将使用单个目录 Id。让我们通过 http GET 调用 https://api.bentley.com/library/components?catalogs=7f427c30-8dce-4803-81dc-e8681a3bd757 终点。Response 包含此目录中的所有组件,在本例中有三个组件。
默认情况下,preference header 设置为“return=minimal”以仅返回响应中组件的 id
和 displayName
,我们已将此值更改为“return=representation”,以获取响应中组件的所有属性。
GET https://api.bentley.com/library/components?catalogs=7f427c30-8dce-4803-81dc-e8681a3bd757 HTTP/1.1
Prefer: return=representation
Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN
3.2 从目录中使用显示名称搜索组件
除了 query 参数外,我们还可以通过应用$search
查询参数从目录中搜索特定组件,实现从 displayName
和 hashtags
属性值中搜索字符串。我们在前面的步骤中从目录中检索到的其中一个组件有一个 displayName 值为“Sample Door”。我们可以使用这个 displayName
值“Door”中的子字符串来搜索这个特定组件。发送 http GET https://api.bentley.com/library/components?$search=Door&catalogs=7f427c30-8dce-4803-81dc-e8681a3bd757
请求端点,这一次响应只包含在 displayName 属性中具有$search
查询参数值的单个组件。
GET https://api.bentley.com/library/components?$search=Door&catalogs=7f427c30-8dce-4803-81dc-e8681a3bd757 HTTP/1.1
Prefer: return=representation
Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN
3.3 从目录中使用哈希标签搜索组件
在上一步中,我们通过应用 displayName 中的字符串值来搜索组件。我们将再次使用$search
查询参数,但这一次,我们将使用 hashtags 属性值中的字符串。我们在前面的步骤中从目录中检索到的两个组件中,有一个标签的值为'woody'。我们可以使用这个值来搜索具有这个标签值的组件。发送 http GET https://api.bentley.com/library/components?$search=woody&catalogs=7f427c30-8dce-4803-81dc-e8681a3bd757 请求到端点,这次响应包含 hashtags 属性中包含“woody”的两个组件。
GET https://api.bentley.com/library/components?$search=wooden&catalogs=7f427c30-8dce-4803-81dc-e8681a3bd757 HTTP/1.1
Prefer: return=representation
Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN
4. 获取组件文档和下载文件
到目前为止,我们已经学会了如何从目录中搜索组件。一旦我们有了这个组件,我们就可以使用 id 并调用 GET https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents 端点以获取与组件关联的所有文档_响应中每个文档实例中的 links->fileUrl-href
属性值提供与文档关联的文件的 url。文件下载可以通过邮递员等工具在提供的 url 上发出 Http GET 请求,或者通过编程使用 Azure 库下载文件 (https://docs.microsoft.com/en-us/rest/api/storageservices/get-blob).
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
Response Body
{
"documents": [
{
"id": "3938de7f-ebf2-470f-b41a-d314fdb90ec7",
"displayName": "TutorialSampleFile",
"extension": "rfa",
"version": "1",
"previousVersionId": null,
"purpose": "Design",
"size": 749568,
"available": true,
"isActive": true,
"createdDateTime": "2021-09-06T15:17:46.0180736Z",
"lastModifiedDateTime": "2021-09-06T15:17:46.1465969Z",
"_links": {
"associatedDesignDocument": {
"href": null
},
"fileUrl": {
"href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/3938de7f-ebf2-470f-b41a-d314fdb90ec7.rfa?sv=2018-03-28&sr=b&sig=Smec6HJrZCKZGXYARrGkU1RWJuaO3jqmXKs3%2B5irnak%3D&se=2021-09-08T10%3A51%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorialSampleFile.rfa"
}
}
},
{
"id": "4f618030-ba8c-4144-872e-c61842c3d90e",
"displayName": "TutorialSampleFile.png",
"extension": "png",
"version": null,
"previousVersionId": null,
"purpose": "Thumbnail",
"size": 0,
"available": true,
"isActive": true,
"createdDateTime": "2021-09-06T15:17:46.2226747Z",
"lastModifiedDateTime": "2021-09-06T15:17:46.3093526Z",
"_links": {
"associatedDesignDocument": {
"href": "https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/3938de7f-ebf2-470f-b41a-d314fdb90ec7"
},
"fileUrl": {
"href": "https://componentscenprodeussa01.blob.core.windows.net/public-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/4f618030-ba8c-4144-872e-c61842c3d90e.png"
}
}
},
{
"id": "f9d9f7ce-a014-4b54-b0a6-e351482ec3a5",
"displayName": "TutorialSampleFile",
"extension": "txt",
"version": null,
"previousVersionId": null,
"purpose": "TypeCatalog",
"size": 760,
"available": true,
"isActive": true,
"createdDateTime": "2021-09-06T15:17:46.4256707Z",
"lastModifiedDateTime": "2021-09-06T15:17:46.510613Z",
"_links": {
"associatedDesignDocument": {
"href": "https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/3938de7f-ebf2-470f-b41a-d314fdb90ec7"
},
"fileUrl": {
"href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/f9d9f7ce-a014-4b54-b0a6-e351482ec3a5.txt?sv=2018-03-28&sr=b&sig=1yb19XFDPtuEl6rYiFDLuCjz%2FO8a3r7h89KAHdFwvw8%3D&se=2021-09-08T10%3A51%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorialSampleFile.txt"
}
}
},
{
"id": "bf15e508-3b59-49d5-a1b5-ea9ef9d66515",
"displayName": "Tutorial Sample Document",
"extension": "pdf",
"version": "1",
"previousVersionId": null,
"purpose": "Reference",
"size": 388077,
"available": true,
"isActive": true,
"createdDateTime": "2021-09-06T15:46:51.5524663Z",
"lastModifiedDateTime": "2021-09-06T15:54:47.206787Z",
"_links": {
"associatedDesignDocument": {
"href": null
},
"fileUrl": {
"href": "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"
}
}
}
]
}