# 异步消息统计导出

`exportMessagesStatistics` 可将消息历史和统计数据导出到服务器上的 CSV 文件。当 [`messages:list`](/zh/developer/api-reference/statistics-api/message-statistics-api/#messageslist) 无法处理大型或全账户数据拉取时，请使用此方法。

## 何时使用 export 而非 messages:list

对于有界时间段的实时、分页查询，请使用 `messages:list`。当结果会超过 `messages:list` 的深度分页限制（`page × per_page > 100000`），或者目标是单个可下载文件而非分页 JSON 时，请使用 `exportMessagesStatistics`。导出对 `date_range` 或行数没有限制，因为它将结果流式传输到磁盘上的文件，而不是在单个响应中持有。

## 导出流程如何运作

1.  使用与 `messages:list` 相同的筛选器调用 [`export`](#export)。响应会立即返回一个 `uid` 任务标识符，此时文件尚未生成。
2.  使用该 `uid` 轮询 [`status`](#status)，直到其报告 `STATUS_SUCCESS`（或 `STATUS_FAILED`）。
3.  使用相同的 `uid` 调用 [`result`](#result) 以获取生成的文件名。
4.  按文件名 [下载](#download) 文件。

使用 [`lastTasks`](#lasttasks) 查询应用程序的近期导出任务，使用 [`delete`](#delete) 取消任务或提前删除其文件。

## 方法

导出生命周期有五个方法，外加一个普通的下载端点：

| 方法 | 描述 |
|--------|--------------|
| [`exportMessagesStatistics/export`](#export) | 将导出任务加入队列并返回一个任务 `uid`。 |
| [`exportMessagesStatistics/status`](#status) | 检查任务进度。 |
| [`exportMessagesStatistics/result`](#result) | 任务完成后返回生成的文件名。 |
| [`exportMessagesStatistics/lastTasks`](#lasttasks) | 列出应用程序的近期导出任务。 |
| [`exportMessagesStatistics/delete`](#delete) | 在保留期满前取消任务或删除其文件。 |
| [下载](#download) | 按名称下载生成的 CSV 文件。 |

### export

将消息历史导出任务加入队列，并立即返回一个任务标识符。

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export`

##### 标头

请求需要一个 Server API token：

| 名称 | 必需 | 描述 |
|------------------|----------|---------------------------------------------------------------------------------------------------------|
| `Authorization` | 是 | [Server API token](/zh/developer/api-reference/api-access-token/#server-api-token)。必须以下列格式提供：`Authorization: Api <Server Key>`。 |

##### 请求体参数

请求体接受以下字段：

| 名称 | 必需 | 类型 | 描述 |
|----------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------|
| `type` | 是 | String | 必须是 <code>"TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"</code>。 |
| <code>export_messages<wbr/>_v2</code> | 是 | Object | 导出参数，如下所述。 |
| <code>export_messages<wbr/>_v2.application<wbr/>_code</code> | 见备注 | String | [Pushwoosh application code](/zh/developer/api-reference/api-identifiers/#application-code)。如果未设置 `app_group_code`，则为必需。 |
| <code>export_messages<wbr/>_v2.app<wbr/>_group_code</code> | 见备注 | String | 应用程序组代码，跨组内所有应用导出。如果未设置 `application_code`，则为必需。 |
| <code>export_messages<wbr/>_v2.search</code> | 否 | String | 对消息标题和内容进行自由文本搜索。 |
| <code>export_messages<wbr/>_v2.filters</code> | 否 | Object | 消息筛选器，如下所述。省略则导出整个账户历史。 |
| <code>export_messages<wbr/>_v2.properties</code> | 否 | Array | 要包含在 CSV 中的列，如下所述。 |

`export_messages_v2.filters` 接受：

| 名称 <div style="width:150px"></div> | 类型 | 描述 |
|---------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `statuses` | Array | 要包含的消息状态。<details><summary>可能的值</summary><ul><li><code>"MESSAGE_STATUS_CANCELED"</code></li><li><code>"MESSAGE_STATUS_CREATING"</code></li><li><code>"MESSAGE_STATUS_DONE"</code></li><li><code>"MESSAGE_STATUS_FAIL"</code></li><li><code>"MESSAGE_STATUS_PENDING"</code></li><li><code>"MESSAGE_STATUS_PROCESSING"</code></li><li><code>"MESSAGE_STATUS_WAITING"</code></li></ul></details> |
| `platforms` | Array | [平台代码](/zh/developer/api-reference/messages-api/api-prerequisites/#platforms)（数字，例如 iOS 为 `1`），而不是 `messages:list` 使用的平台名称字符串。 |
| `sent_date` | Object | 按发送日期筛选的报告期：`{"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}`。 |
| `created_date` | Object | 按消息创建日期筛选的报告期，格式与 `sent_date` 相同。 |
| `created_via` | Array | 消息来源。<details><summary>可能的值</summary><ul><li><code>"AB_TEST"</code></li><li><code>"API"</code></li><li><code>"AUTO_PUSH"</code></li><li><code>"CP"</code></li><li><code>"CSV"</code></li><li><code>"CUSTOMER_JOURNEY"</code></li><li><code>"EMAIL_API"</code></li><li><code>"EMAIL_CP"</code></li><li><code>"GEO_ZONE"</code></li><li><code>"PUSH_ON_EVENT"</code></li><li><code>"RSS"</code></li><li><code>"SYSTEM"</code></li></ul></details> |
| `segments` | Array | 消息发送到的[筛选器代码](/zh/developer/api-reference/api-identifiers/#segment--filter-code)。 |
| `campaigns` | Array | [营销活动代码](/zh/developer/api-reference/api-identifiers/#campaign-code)。与 `messages:list` 不同，这里接受一个列表，而不是单个代码。 |
| `message_id` | String (uint64) | 单个数字消息 ID，带引号。与 `messages:list` 不同，导出只接受一个 ID，而不是数组。 |
| `message_code` | String | 单个[消息代码](/zh/developer/api-reference/api-identifiers/#message-code)。 |

`export_messages_v2.properties` 选择 CSV 包含哪些列。

<details>
<summary>可能的值</summary>

- `"EXPORT_MESSAGE_PROPERTY_ID"`
- `"EXPORT_MESSAGE_PROPERTY_TIMESTAMP"`
- `"EXPORT_MESSAGE_PROPERTY_CONTENT"`
- `"EXPORT_MESSAGE_PROPERTY_TITLE"`
- `"EXPORT_MESSAGE_PROPERTY_APPLICATIONS"`
- `"EXPORT_MESSAGE_PROPERTY_STATUS"`
- `"EXPORT_MESSAGE_PROPERTY_PLATFORMS"`
- `"EXPORT_MESSAGE_PROPERTY_SOURCE"`
- `"EXPORT_MESSAGE_PROPERTY_FILTER"`
- `"EXPORT_MESSAGE_PROPERTY_SUBSCRIPTION_SEGMENTS"`
- `"EXPORT_MESSAGE_PROPERTY_SENT"`
- `"EXPORT_MESSAGE_PROPERTY_OPENED"`
- `"EXPORT_MESSAGE_PROPERTY_ERRORS"`
- `"EXPORT_MESSAGE_PROPERTY_RECIPIENTS"`
- `"EXPORT_MESSAGE_PROPERTY_DELIVERED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_DELIVERED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_OPENED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_CLICKS"`
- `"EXPORT_MESSAGE_PROPERTY_CLICKS"`
- `"EXPORT_MESSAGE_PROPERTY_UNSUBSCRIBED"`

</details>

<Aside type="caution" title="properties 不仅仅是筛选器">
未在 `properties` 中列出的属性将完全不会出现在文件中，包括基本列（ID、发送日期、内容、状态）。将 `properties` 留空会生成一个没有列的 CSV。请列出导出应包含的每一列，而不仅仅是您想在默认集基础上添加的指标。
</Aside>

##### 请求示例

```json
{
  "type": "TASK_TYPE_EXPORT_MESSAGES_V2",
  "export_messages_v2": {
    "application_code": "XXXXX-XXXXX",
    "filters": {
      "created_date": {
        "date_from": "2026-01-01",
        "date_to": "2026-06-30"
      },
      "statuses": ["MESSAGE_STATUS_DONE"],
      "platforms": [1, 3]
    },
    "properties": [
      "EXPORT_MESSAGE_PROPERTY_ID",
      "EXPORT_MESSAGE_PROPERTY_TIMESTAMP",
      "EXPORT_MESSAGE_PROPERTY_STATUS",
      "EXPORT_MESSAGE_PROPERTY_PLATFORMS",
      "EXPORT_MESSAGE_PROPERTY_SENT",
      "EXPORT_MESSAGE_PROPERTY_OPENED"
    ]
  }
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "uid": "177458"
}
```
</TabItem>
<TabItem label="401: API 访问令牌不正确">
```json
{
  "error": "account not found"
}
```
</TabItem>
</Tabs>

### status

返回导出任务的进度。

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/status`

##### 请求体参数

传递由 `export` 返回的任务标识符：

| 名称 | 必需 | 类型 | 描述 |
|-------|----------|---------|--------------------------------------------------|
| `uid` | 是 | String (int64) | 来自 `export` 响应的任务标识符，例如 `"177458"`。 |

##### 请求示例

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "status": "STATUS_SUCCESS",
  "progress": 1
}
```
</TabItem>
</Tabs>

`status` 是 `"STATUS_PENDING"`、`"STATUS_SUCCESS"` 或 `"STATUS_FAILED"` 之一。`progress` 是一个介于 `0` 和 `1` 之间的小数；请轮询 `status` 直到其达到 `"STATUS_SUCCESS"`，然后再调用 `result`。

### result

任务完成后返回生成的文件名。

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/result`

##### 请求体参数

传递由 `export` 返回的相同任务标识符：

| 名称 | 必需 | 类型 | 描述 |
|-------|----------|---------|--------------------------------------------------|
| `uid` | 是 | String (int64) | 来自 `export` 响应的任务标识符，例如 `"177458"`。 |

##### 请求示例

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}
```
</TabItem>
</Tabs>

在 `status` 报告 `"STATUS_SUCCESS"` 之前调用 `result` 会返回一个空结果。请将 `file` 的值原样传递给[下载端点](#download)。

### lastTasks

列出应用程序的近期导出任务，最新的在前。

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/lastTasks`

##### 请求体参数

每个参数都是可选的筛选器；全部省略则列出该令牌有权访问的所有任务：

| 名称 | 必需 | 类型 | 描述 |
|------------------|----------|---------|---------------------------------------------------------------------------------------|
| `application` | 否 | String | [Pushwoosh application code](/zh/developer/api-reference/api-identifiers/#application-code)。省略则列出该令牌有权访问的所有应用程序的任务。 |
| `types` | 否 | Array | 限制为特定的任务类型。使用 <code>["TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"]</code> 只查看消息导出。 |
| `campaign` | 否 | String | 按[营销活动代码](/zh/developer/api-reference/api-identifiers/#campaign-code)筛选。 |
| `message_id` | 否 | String (uint64) | 按单个数字消息 ID 筛选，带引号。 |
| `message_code` | 否 | String | 按单个[消息代码](/zh/developer/api-reference/api-identifiers/#message-code)筛选。 |
| `limit` | 否 | Integer | 返回的最大任务数。 |
| `timestamp_from` | 否 | String | 仅返回在此时间戳 (RFC 3339) 之后创建的任务。 |

<Aside type="note">
任务会保留 30 天，无论其文件是否已在 7 天的文件保留期后被删除。`lastTasks` 仍可能显示一个其 `result` 不再解析为可下载文件的任务。
</Aside>

##### 请求示例

```json
{
  "application": "XXXXX-XXXXX",
  "types": ["TASK_TYPE_EXPORT_MESSAGES_V2"],
  "limit": 10
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "tasks": [
    {
      "id": "177458",
      "timestamp": "2026-08-13T12:00:00Z",
      "status": "STATUS_SUCCESS",
      "requested_by_user": "user@example.com",
      "export_messages_v2": {
        "application_code": "XXXXX-XXXXX"
      },
      "export_messages_v2_result": {
        "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
      }
    }
  ]
}
```
</TabItem>
</Tabs>

### delete

在 7 天保留期满前删除任务及其文件。

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/delete`

##### 请求体参数

传递由 `export` 返回的任务标识符：

| 名称 | 必需 | 类型 | 描述 |
|-------|----------|---------|--------------------------------------------------|
| `uid` | 是 | String (int64) | 来自 `export` 响应的任务标识符，例如 `"177458"`。 |

##### 请求示例

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{}
```
</TabItem>
</Tabs>

### 下载

按名称下载由 `result` 生成的 CSV 文件。

`GET` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/<file>`

##### 标头

认证方式与其他方法相同，或依赖于一个有效的 Control Panel 会话：

| 名称 | 必需 | 描述 |
|------------------|----------|-----------------------------------------------------------------------------------------------------|
| `Authorization`| 是 | [Server API token](/zh/developer/api-reference/api-access-token/#server-api-token)，格式与其他 `exportMessagesStatistics` 方法相同：`Authorization: Api <Server Key>`（`Api` 方案不区分大小写）。没有 `Authorization` 标头且没有登录 Control Panel 会话的请求会收到 `401 Unauthorized`。 |

将 `<file>` 替换为 `result` 响应中确切的 `file` 值，例如：

```
https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv
```

该文件是一个 CSV，包含在 `properties` 中选择的列。它在导出完成后会保留 7 天，之后清理作业会将其删除，URL 将不再可用。