跳至主要内容

Cognite OData 服务

Cognite 提供 OData 服务，可使用 OData 客户端（例如 Microsoft Power BI、Microsoft Excel 和 TIBCO Spotfire）从 Cognite Data Fusion (CDF) 获取数据。

Open Data Protocol (OData) 是一种开放标准，定义了构建和使用 RESTful API 的最佳实践。OData 提供：

  • 标准化查询语法：在不同的数据源之间实现一致的筛选、排序、分页和投影。

  • 元数据支持：客户端可以通过元数据文档发现数据结构和类型。

  • 互操作性：任何支持 HTTP 并理解 OData 的客户端都可以使用 OData 服务。

Cognite 提供 asset-centric OData 服务 和 数据建模 OData 服务。这两项服务都封装了标准 Cognite API，实现了用于只读目的的 OData Version 4 API。它们将 OData 请求转换为相应的 Cognite API 调用，使你可以使用与 OData 兼容的客户端和工具与 CDF 数据进行交互。

使用 OData 服务​

要与 Cognite OData 服务进行交互，需要向特定端点发出 HTTP GET 请求。

身份验证​

要使用 OData 服务进行身份验证，必须在 HTTP 请求的授权标头中包含持有者令牌。

例如：

Authorization: Bearer {YourAccessToken}

可以使用适合于设置的身份验证流程（例如 OAuth 2.0、OpenID Connect）获取访问令牌。有关详细信息，请参阅身份验证文档。

发出请求​

GET 请求示例​

要检索项目中的所有资产：

GET https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/Assets

其中：

  • {cluster}：CDF 群集名称（例如 westeurope-1）。
  • {apiVersion}：OData 服务 API 版本（例如 v1）。
  • {project}：你的 CDF 项目名称。
查询参数​

使用查询参数对数据进行筛选、排序、选择和分页等操作。

  • 筛选 - 使用 $filter 查询参数筛选数据。

    示例：检索 Name 等于 'Pump 1' 的资产：GET .../Assets?$filter=Name eq 'Pump 1'

  • 选择字段 - 使用 $select 查询参数检索特定字段。

    示例：仅检索资产的 Id 和 Name：GET .../Assets?$select=Id,Name

  • 排序 - 使用 $orderby 查询参数对结果进行排序。

    示例：按 Name 升序排列资产：GET .../Assets?$orderby=Name asc

  • 扩展相关实体 - 使用 $expand 查询参数以包含相关实体。 示例：检索资产及其父级：GET .../Assets(702630644612)/Parent?$expand=Parent

    注意：并非所有实体和关系都支持扩展。有关详细信息，请参阅单独的服务文档。

  • 组合查询参数 - 可以组合多个查询参数来优化请求。

    示例：检索 Name 以 'Pump' 开头的资产的 Id 和 Name，按 Name 排序，并检索前 10 个结果： GET .../Assets?$filter=startswith(Name,'Pump')&$select=Id,Name&$orderby=Name asc&$top=10

响应格式​

OData 服务以 JSON 格式返回响应，遵循 OData V4 标准。

响应示例：

{
  "@odata.context": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/$metadata#Assets/",
  "value": [
    {
      "Id": "12345",
      "DataSetId": null,
      "ExternalId": "WMT:VAL",
      "Name": "Pump 1",
      "Description": "Main pump"
      // other properties
    }
  ]
}
响应分页​

对于大型结果集，OData 服务可能会对响应进行分页。响应包括 @odata.nextLink 属性，其中包含用于检索下一页结果的 URL。

示例：

{
  "@odata.context": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/$metadata#Assets",
  "value": [ // records ],
  "@odata.nextLink": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/Assets?$skipToken=123"
}

限制和支持的功能​

OData 服务旨在符合 OData V4 标准，但由于 Cognite API 的基本限制，某些功能可能会受到限制或不支持。

有关支持的功能和限制的详细信息，请参阅单独的服务文档。

上次更新