解读报告并提取数据

28天前更新

1. 汇总页面

保存数据流配置后，会打开一个汇总页面，显示提取数据所需的全部信息。

编辑配置

点击 编辑数据流配置 (Edit the flow configuration) 选项卡，即可更改之前输入的信息。

数据流的汇总页面

您也可以在 数据流配置 (Flow configurations) 选项卡中，点击表格 操作 (Actions) 列中的眼睛图标进入此页面。

从操作列进入汇总页面

2. 提取要素

所选来源的提取条件以三个必须组合使用的必填要素显示。

方法

GET — 用于获取数据的请求协议。

授权

Bearer Token — 访问内容所需的安全密钥。

端点 URL

以下示例使用 gate01.teepchina.com；如果您使用 gate02.teepchina.com，请相应替换主机。

JSON 或 CSV 格式的 URL：

https://gate01.teepchina.com/api/....json
https://gate01.teepchina.com/api/....csv

3. 重要说明

分页和请求限制

数据分块返回，以确保最佳性能。

请求限制

最多：每个令牌每 2 秒 1 次请求
每小时配额：每个令牌每小时 500 次请求

如果超过此限制，API 会返回 429 Too Many Requests 错误。

**建议：**请求之间至少间隔 8 秒，以便轻松保持在两项限制之内。

每页结果数

每次请求每页最多返回 2,000 条结果（2,000 行）。因此，导出 5,000 条结果需要多次请求，结果按每块 2,000 行拆分。

*例外：*产品计数每页限制为 1,000 条结果。

4. 数据获取示例

使用 GET 方法、Bearer Token 授权以及提供的 URL，您可以以 JSON 和/或 CSV 格式导出数据。

使用 Postman 的操作步骤

在 Postman 的相应字段中输入 API 信息。
以 JSON 格式导出的数据显示在下方区域。

使用 Postman 获取数据

5. 可选参数和分页

可以对导出应用筛选器，以细化和优化您的提取需求。

在 Postman 中使用

点击 Params。
输入相应的键和值。
点击 Send 应用筛选器。

可用参数列表

#	参数	说明
1	`page`	设置 API 返回的页码
2	`created_at_gte`	设置“大于或等于”阈值（创建时间……）
3	`created_at_lte`	设置“小于或等于”阈值（创建时间……）
4	`updated_at_lte`	设置“小于或等于”阈值（更新时间……）
5	`with_custom_fields`	允许显示自定义字段
6	`machine_ids`	按一台或多台机器筛选请求

6. 原始数据 — 采用游标分页的 V2 替代方案

概述

对于原始数据 API，提供了一个可选的替代方案：Performance Logs V2 API。它提供 游标分页，比传统的页码分页更可靠：即使数据在两次请求之间发生变化，每条记录也只会被返回一次。

V2 端点：

GET /api/v1/external/performance_logs.json
GET /api/v1/external/performance_logs.csv
GET /api/v1/external/performance_logs/simplified_losses.json
GET /api/v1/external/performance_logs/simplified_losses.csv

传统 V1 端点（仍可使用）：

GET /api/v1/external/raw_data
GET /api/v1/external/simplified_losses

您可以根据需要继续使用传统的 page 分页，或采用游标分页。

何时使用 V2（游标）？

您需要进行 定期数据同步（每天、每小时等）。
您希望确保 数据零丢失、零重复。
您处理 大量数据，并希望通过一次请求导出 CSV。

何时继续使用 V1（页码）？

您只进行简单的 一次性导出。
您更喜欢 传统的页码分页。
您现有的集成在 V1 下运行良好。

游标分页：使用方法

V2 特有的参数：

参数	说明
`since`	首次请求使用的 ISO 8601 日期（例如 `2025-01-01T00:00:00Z`）。
`cursor`	后续请求使用的分页键。见下文。
`limit`	每页结果数（默认：2000，最大：2000）。

**概念。**游标是一种分页键，可确保即使数据在两次请求之间发生变化，每条记录也只会被返回一次。与简单的页码分页相比，它提供了更好的数据完整性。

首次请求（初始同步）

发送不带游标的首次请求，使用 since 参数或不使用任何参数：

GET /api/v1/external/performance_logs?since=2025-01-01T00:00:00Z

JSON 响应包含一个 meta 对象，其中含有 next_cursor：

{
  "data": [ ... ],
  "meta": {
    "next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9"
  },
  "links": {
    "next": "https://gate01.teepchina.com/api/v1/external/performance_logs?cursor=eyJ1cGRhdGVkX2F0Ij..."
  }
}

后续请求（增量同步）

**保存收到的最后一个 next_cursor。**在下一次请求中，将该游标作为参数使用：

GET /api/v1/external/performance_logs?cursor=eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9

响应会返回一个新的 next_cursor，供下一次请求使用。重复此循环，直到 next_cursor 为 null，这表示您已获取所有可用数据。

分页结束

当 meta.next_cursor 为 null，或结果数少于限制时，说明您已获取所有可用记录。

如需稍后继续请求以获取新数据，建议保留最后一个非 null 的游标。

错误情况：游标丢失

如果您丢失了最后保存的游标，请使用 since 参数和上次成功同步的大致日期发送新请求。随后，您将获取从该日期起的数据。

三次请求完成同步的完整示例

1. 初始同步

Request 1: GET /api/v1/external/performance_logs?since=2025-01-01T00:00:00Z
Response: 2000 records + next_cursor = "cursor_ABC"
Save "cursor_ABC"

2. 增量同步

Request 2: GET /api/v1/external/performance_logs?cursor=cursor_ABC
Response: 2000 records + next_cursor = "cursor_XYZ"
Save "cursor_XYZ"

3. 最后一次增量同步

Request 3: GET /api/v1/external/performance_logs?cursor=cursor_XYZ
Response: 1500 records + next_cursor = "cursor_qsd"
Save "cursor_qsd"
Synchronisation complete

7. 使用 Postman 管理游标（环境变量）

如需在 Postman 中自动处理游标，请使用环境变量。

初始设置

打开 Postman，进入 Manage Environments（齿轮图标）。
创建或编辑您的 Gate 环境。
添加两个变量：
- Key：cursor | Value：（留空）
- Key：token | **Value：**您的 Bearer Token

首次请求

在 Params 选项卡中，添加：

Key	Value
`since`	`2025-01-01T00:00:00Z`

在 Authorization 选项卡中，选择 Bearer Token 并输入您的令牌。点击 Send。

每次响应后更新游标

进入 Tests 选项卡。
添加以下脚本，自动保存 next_cursor：

if (pm.response.code === 200) {
  const responseData = pm.response.json();
  if (responseData.meta && responseData.meta.next_cursor) {
    pm.environment.set("cursor", responseData.meta.next_cursor);
    console.log("Cursor saved:", responseData.meta.next_cursor);
  } else {
    console.log("End of pagination: next_cursor is null");
  }
}

后续请求

在 Params 选项卡中，删除 since 参数。
添加值为 {{cursor}} 的 cursor 参数。
点击 Send。

Postman 会自动将 {{cursor}} 替换为最后保存的值。每次响应后，脚本都会用新的游标更新该变量。

重复直至结束

继续发送请求。每次调用后，游标都会自动更新。当 next_cursor 为 null 时，同步完成。

8. V2 响应的结构

JSON 响应

{
  "data": [
    {
      "id": 1,
      "duration": 300,
      "machine_id": 10,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T11:00:00Z",
      "custom_fields": {
        "Team": "Morning",
        "Line": "L3"
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9"
  },
  "links": {
    "next": "https://gate01.teepchina.com/api/v1/external/performance_logs?cursor=eyJ..."
  }
}

关键要素

要素	说明
`data`	包含绩效记录的数组
`meta.next_cursor`	下一次请求使用的游标。分页结束时为 `null`
`links.next`	预先构建好的下一次请求 URL（可选）
`data.custom_fields`	包含自定义字段的对象（如已启用）

日期格式

所有日期均以 ISO 8601 格式、UTC 时间返回（例如 2025-01-15T10:30:00Z）。

9. V2 集成示例

完整 CSV 导出

如需一次性以 CSV 格式导出所有数据：

GET /api/v1/external/performance_logs.csv?since=2025-01-01T00:00:00Z

这一次请求即可在一个 CSV 文件中返回所有结果，无需分页。非常适合一次性导出。

按机器筛选

如需提取特定机器的数据：

GET /api/v1/external/performance_logs?cursor=...&machine_ids=10,20,30

自定义字段

如需在响应中包含自定义字段：

GET /api/v1/external/performance_logs?cursor=...&with_custom_fields=true

它们会出现在每条记录的 custom_fields 对象中。