从目录中查询或下载组件

简介

本教程将带您了解从组织中的目录查询组件的过程。

在本演练结束时，您将能够利用 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”部分获取用户令牌

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

results matching ""

    No results matching ""