data-service

latest

false

开放式 API

重要 :

Data Service 正在向 Data Fabric 过渡。在此过程中，您可能会看到这两种名称被用于不同的交付选项。请注意，此内容已使用机器翻译进行了部分本地化。新发布内容的本地化可能需要 1-2 周的时间才能完成。

预览

Data Fabric API 指南

查询实体记录

查询实体记录。

API 端点

POST BaseURL/EntityService/<Entity>/query

根据您使用的云平台，使用关联的基本 URL 。

请求标头

页眉	值
授权	承载 `<access_token>`
Content-Type	application/json

备注：

将尖括号 <...> 之间的所有值替换为其相应的用例值。

<access_token> 是您在授权外部应用程序时收到的。它可用 1 小时，然后您需要生成新令牌，或请求刷新令牌。

查询参数

查询参数	数据类型	描述	默认值
ExpansionLevel （可选）	`int32`	指定要检索的相关记录的深度。此参数的值可以是 1、2 或 3。	2

请求正文 (必填)

{
  "selectedFields": [
    "string"
  ],
  "filterGroup": {
    "logicalOperator": 0,
    "queryFilters": [
      {
        "fieldName": "string",
        "operator": "string",
        "value": "string"
      }
    ],
    "filterGroups": [
    ]
  },
  "start": 0,
  "limit": 0,
  "sortOptions": [
    {
      "fieldName": "string",
      "isDescending": true
    }
  ]
}
{
  "selectedFields": [
    "string"
  ],
  "filterGroup": {
    "logicalOperator": 0,
    "queryFilters": [
      {
        "fieldName": "string",
        "operator": "string",
        "value": "string"
      }
    ],
    "filterGroups": [
    ]
  },
  "start": 0,
  "limit": 0,
  "sortOptions": [
    {
      "fieldName": "string",
      "isDescending": true
    }
  ]
}

请求正文架构

query 端点请求正文包含以下组件：

selectedFields

这是一个可选组件，类型为 string。它指定要为查询的每条记录返回的字段列表。如果留空，或查询列表为空，则返回所有记录字段。默认值为 null。

这是一个必需组件，可帮助您设置查询的筛选属性。它结合了以下属性：

逻辑运算符- 这是可选的筛选器组属性，类型为int32 。它指定是否所有筛选器和筛选器组都适用于该查询。使用0应用所有筛选器和筛选器组。使用1应用任何筛选器和筛选器组。默认值为0 。

查询筛选器- 这是必需的筛选器组属性，可帮助您定义筛选表达式。它具有以下属性：

查询筛选器属性	数据类型	描述
fieldName	`string`	指定要筛选的字段的名称。
operator	`string`	指定筛选器运算符。支持以下表达式： `contains` 、 `not contains` 、 `startswith` 、 `endswith` 、 `=` 、 `!=` 、 `>` 、 `<` 、 `>=` 、 `<=` 、 `in` 、 `not in`对相应的字段类型使用适当的运算符。
值	`string`	指定筛选值。

筛选器组- 这是一个可选的筛选器组属性，如果您需要为查询设置另一个筛选选项，则可使用该属性。它包含上面列出的所有filterGroup属性。

启动

这是一个可选组件，类型为int32 。指定在从查询中检索记录之前要跳过的记录数。可以与limit属性一起使用以实施分页。记录按其 ID 升序排列。要修改排序顺序，请使用sortOptions属性。默认值为0 。

limit

这是一个可选组件，类型为int32 。它指定要从实体读取的最大记录数。可以与开始属性一起使用以实施分页。默认值为100 ，最大值为1000 。

sortOptions

这是一个可选组件，可帮助您按字段列表对查询的记录进行排序。如果留空，则记录按 ID 升序排序。它结合了以下属性：

字段名称- 这是必填的sortOptions属性，类型为string 。它指定用于对记录进行排序的字段名称。名称必须与有效的字段对应，并且区分大小写。
是降序- 这是可选的sortOptions属性，类型为boolean 。如果要按降序对记录进行排序，请将其设置为true 。默认值为false 。

响应

200 OK

{
  "TotalRecordCount": 0,
  "Value": [
    {
      "ClosingDate": "2021-03-04",
      "CreatedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "CreateTime": "2021-03-04T10:21:22.771Z",
      "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "Logo": {
        "Name": "string",
        "Path": "string",
        "Size": 0,
        "Type": "string"
      },
      "Name": "string",
      "Nations": 0,
      "OlymipcsVersion": 0,
      "OpeningDate": "2021-03-04",
      "UpdatedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "UpdateTime": "2021-03-04T10:21:22.771Z"
    }
  ]
}
{
  "TotalRecordCount": 0,
  "Value": [
    {
      "ClosingDate": "2021-03-04",
      "CreatedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "CreateTime": "2021-03-04T10:21:22.771Z",
      "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "Logo": {
        "Name": "string",
        "Path": "string",
        "Size": 0,
        "Type": "string"
      },
      "Name": "string",
      "Nations": 0,
      "OlymipcsVersion": 0,
      "OpeningDate": "2021-03-04",
      "UpdatedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "UpdateTime": "2021-03-04T10:21:22.771Z"
    }
  ]
}

响应正文架构

query 端点响应正文包含以下组件：

总记录数- 与指定查询筛选器匹配的记录总数。
“值” - 与指定查询筛选器匹配的实体记录数组，受“限制”属性限制。

401 未经授权

您未通过身份验证，无法访问 Data Fabric/Data Service。确保您的 Assistant 或 Robot 已连接到您帐户中的新式文件夹。

403 Forbidden

您无权访问实体、字段或记录，或者您使用的机器人类型不受支持。请联系管理员以获取必要权限。

聚合函数

您可以通过将aggregates和groupBy属性添加到请求正文来对单个实体运行聚合计算。聚合单独返回计算值（例如总计或平均值），或与分组的字段值一起返回。

请求正文

{
  "selectedFields": [
    "Department"
  ],
  "aggregates": [
    {
      "function": "COUNT",
      "field": "Id",
      "alias": "EmployeeCount"
    }
  ],
  "groupBy": [
    "Department"
  ],
  "filterGroup": {
    "logicalOperator": 0,
    "queryFilters": [
      {
        "fieldName": "Status",
        "operator": "=",
        "value": "Active"
      }
    ]
  },
  "sortOptions": [
    {
      "fieldName": "EmployeeCount",
      "isDescending": true
    }
  ],
  "start": 0,
  "limit": 100
}
{
  "selectedFields": [
    "Department"
  ],
  "aggregates": [
    {
      "function": "COUNT",
      "field": "Id",
      "alias": "EmployeeCount"
    }
  ],
  "groupBy": [
    "Department"
  ],
  "filterGroup": {
    "logicalOperator": 0,
    "queryFilters": [
      {
        "fieldName": "Status",
        "operator": "=",
        "value": "Active"
      }
    ]
  },
  "sortOptions": [
    {
      "fieldName": "EmployeeCount",
      "isDescending": true
    }
  ],
  "start": 0,
  "limit": 100
}

聚合请求组件

除了基本查询属性外，聚合查询还使用以下组件：

聚合

这是可选组件，类型为数组。它指定要应用的聚合函数。每个查询最多可以包含 5 个聚合。每个项目都具有以下属性：

聚合属性	数据类型	必填	描述
function	`string`	是	要应用的聚合函数。支持的值： `COUNT` 、 `SUM` 、 `AVG` 、 `MIN` 、 `MAX` 。不区分大小写。
字段	`string`	是	要聚合的字段。必须是查询实体的字段。
别名	`string`	否	结果列的名称。如果省略，则系统会自动生成为`{FUNCTION}_{FIELD}` （例如`COUNT_Id` ）。别名在查询中必须唯一（不区分大小写），以字母开头，并且仅包含字母、数字和下划线。

分组依据

这是一个可选组件，类型为string的数组。它指定用于对结果进行分组的字段。您最多可以添加 5 个字段。

当您同时提供aggregates和非空selectedFields时， groupBy为必填项，并且selectedFields中的每个字段也必须显示在groupBy中。

备注：

对聚合查询进行排序时，请将sortOptions.fieldName设置为聚合alias或selectedFields / groupBy中属于一部分的字段。

字段类型支持

函数	支持的字段类型
计数、最小值、最大值	任何字段类型，但附件字段和多行文本字段（常规`MULTILINE`和大型`MULTILINE_MAX` ）。
SUM和平均值	仅限数字字段： `INT` 、 `BIGINT` 、 `DECIMAL` 、 `FLOAT` 、 `REAL` 。

限值和限制

每个查询最多使用 5 个聚合函数和 5 个groupBy字段。
聚合不能与扩展 ( expansionLevel ) 结合使用。
仅标准（基于表格）实体支持聚合。虚拟实体（外部数据源）、选项集或系统实体不支持它们。
聚合不能应用于附件字段或多行文本字段（常规MULTILINE和大型MULTILINE_MAX ）。这适用于每个函数，包括COUNT 。
记录级（行级）权限筛选器不适用于聚合结果：对实体中的所有记录计算聚合值，包括调用者无法单独读取的记录。仍强制执行实体级和字段级读取权限；您无法按您无权读取的字段进行聚合或分组。

示例：按字段分组的计数

统计每个部门的员工数量，按计数降序排序。

请求：

POST BaseURL/EntityService/Employees/query

{
  "selectedFields": ["Department"],
  "aggregates": [
    { "function": "COUNT", "field": "Id", "alias": "EmployeeCount" }
  ],
  "groupBy": ["Department"],
  "sortOptions": [
    { "fieldName": "EmployeeCount", "isDescending": true }
  ]
}
POST BaseURL/EntityService/Employees/query

{
  "selectedFields": ["Department"],
  "aggregates": [
    { "function": "COUNT", "field": "Id", "alias": "EmployeeCount" }
  ],
  "groupBy": ["Department"],
  "sortOptions": [
    { "fieldName": "EmployeeCount", "isDescending": true }
  ]
}

响应：

{
  "TotalRecordCount": 3,
  "Value": [
    { "Department": "Engineering", "EmployeeCount": 150 },
    { "Department": "Sales", "EmployeeCount": 80 },
    { "Department": "HR", "EmployeeCount": 20 }
  ]
}
{
  "TotalRecordCount": 3,
  "Value": [
    { "Department": "Engineering", "EmployeeCount": 150 },
    { "Department": "Sales", "EmployeeCount": 80 },
    { "Department": "HR", "EmployeeCount": 20 }
  ]
}

多实体查询（联接）

您可以通过将joins属性添加到请求正文，将来自相关实体的记录合并到单个查询中。联接可以单独使用，也可以与聚合和groupBy一起使用。

主实体（左侧）是请求 URL 中的实体 ( <Entity> )。每个联接都会向查询添加另一个实体。

请求正文

{
  "selectedFields": [
    "Employees.Name",
    "Departments.Name"
  ],
  "joins": [
    {
      "type": "INNER",
      "entity": "Departments",
      "on": {
        "left": "Employees.DepartmentId",
        "right": "Departments.Id"
      }
    }
  ],
  "sortOptions": [
    {
      "fieldName": "Employees.Name",
      "isDescending": false
    }
  ],
  "start": 0,
  "limit": 100
}
{
  "selectedFields": [
    "Employees.Name",
    "Departments.Name"
  ],
  "joins": [
    {
      "type": "INNER",
      "entity": "Departments",
      "on": {
        "left": "Employees.DepartmentId",
        "right": "Departments.Id"
      }
    }
  ],
  "sortOptions": [
    {
      "fieldName": "Employees.Name",
      "isDescending": false
    }
  ],
  "start": 0,
  "limit": 100
}

字段限定条件

当查询跨越多个实体时，请将字段引用为EntityName.fieldName 。仅当非限定性 fieldName 在查询中的所有实体中都是唯一的时，您才能使用非限定性；否则，系统会将其视为不明确而拒绝。实体名称不区分大小写。

这适用于selectedFields 、 groupBy 、 sortOptions.fieldName 、 filterGroup筛选器、 aggregates.field和联接on.left / on.right值。在响应中，字段始终返回EntityName.fieldName限定条件。

联接请求组件

联接

这是可选组件，类型为数组。它指定要联接的实体。您最多可以包含 3 个联接。每个项目都具有以下属性：

联接属性	数据类型	必填	描述
类型	`string`	是	联接类型。支持的值： `INNER` 、 `LEFT` 。不区分大小写。单个查询中的所有联接必须为相同类型；不支持混合使用`INNER`和`LEFT` 。
实体	`string`	是	要加入的实体的名称。每个实体只能出现一次，并且不能是主实体（不支持自联接）。
开启	`object`	是	联接条件。包含`left`和`right` 。
在.左侧	`string`	是	左侧的联接字段，如`fieldName` （如果明确）或`EntityName.fieldName` 。
在右侧	`string`	是	右侧的联接字段，如`fieldName` （如果明确）或`EntityName.fieldName` 。

限值和限制

每个查询最多有 3 个联接，且所有联接类型相同（ INNER或LEFT ）。
两边的联接键必须具有兼容的类型（数字与数字、文本与文本、日期与日期）。
您不能加入以下元素：系统生成的字段、加密字段、大型（多行上限）文本字段、选项集或多项选择集字段，或文件（附件）字段。关系字段可用作联接键。
不支持HAVING子句。
将联接与聚合相结合时，聚合函数部分中描述的聚合规则和groupBy规则也适用。

示例：带有聚合的左联接

列出客户及其订单数，包括没有订单的客户。

请求：

POST BaseURL/EntityService/Customers/query

{
  "selectedFields": ["Customers.Id", "Customers.Name"],
  "aggregates": [
    { "function": "COUNT", "field": "Orders.Id", "alias": "OrderCount" }
  ],
  "joins": [
    {
      "type": "LEFT",
      "entity": "Orders",
      "on": { "left": "Customers.Id", "right": "Orders.CustomerId" }
    }
  ],
  "groupBy": ["Customers.Id", "Customers.Name"],
  "sortOptions": [
    { "fieldName": "OrderCount", "isDescending": true }
  ]
}
POST BaseURL/EntityService/Customers/query

{
  "selectedFields": ["Customers.Id", "Customers.Name"],
  "aggregates": [
    { "function": "COUNT", "field": "Orders.Id", "alias": "OrderCount" }
  ],
  "joins": [
    {
      "type": "LEFT",
      "entity": "Orders",
      "on": { "left": "Customers.Id", "right": "Orders.CustomerId" }
    }
  ],
  "groupBy": ["Customers.Id", "Customers.Name"],
  "sortOptions": [
    { "fieldName": "OrderCount", "isDescending": true }
  ]
}

响应：

{
  "TotalRecordCount": 3,
  "Value": [
    { "Customers.Id": "C-001", "Customers.Name": "Acme Corp", "OrderCount": 12 },
    { "Customers.Id": "C-002", "Customers.Name": "Globex", "OrderCount": 3 },
    { "Customers.Id": "C-003", "Customers.Name": "Initech", "OrderCount": 0 }
  ]
}
{
  "TotalRecordCount": 3,
  "Value": [
    { "Customers.Id": "C-001", "Customers.Name": "Acme Corp", "OrderCount": 12 },
    { "Customers.Id": "C-002", "Customers.Name": "Globex", "OrderCount": 3 },
    { "Customers.Id": "C-003", "Customers.Name": "Initech", "OrderCount": 0 }
  ]
}

此页面有帮助吗？

前一个获取实体记录

下一个按 ID 删除实体记录

Data Fabric API 指南

API 端点​

请求标头​

查询参数​

请求正文 (必填)​

请求正文架构​

selectedFields​

筛选器组​

启动​

limit​

sortOptions​

响应​

200 OK​

响应正文架构​

401 未经授权​

403 Forbidden​

聚合函数​

请求正文​

聚合请求组件​

聚合​

分组依据​

字段类型支持​

限值和限制​

示例：按字段分组的计数​

多实体查询（联接）​

请求正文​

字段限定条件​

联接请求组件​

联接​

限值和限制​

示例：带有聚合的左联接​

此页面有帮助吗？

API 端点

请求标头

查询参数

请求正文 (必填)

请求正文架构

selectedFields

筛选器组

启动

limit

sortOptions

响应

200 OK

响应正文架构

401 未经授权

403 Forbidden

聚合函数

请求正文

聚合请求组件

聚合

分组依据

字段类型支持

限值和限制

示例：按字段分组的计数

多实体查询（联接）

请求正文

字段限定条件

联接请求组件

联接

限值和限制

示例：带有聚合的左联接