# 细分 (筛选器) API

## createFilter

`POST` `https://api.pushwoosh.com/json/1.3/createFilter`

创建一个新的筛选器。

**请求正文**

| 名称 | 必需 | 类型 | 描述 |
| ---------------------------------------------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| auth\* | 是 | string | 来自 Pushwoosh 控制面板的 [API access token (API 访问令牌)](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| name\* | 是 | string | [Filter name (筛选器名称)](/zh/developer/api-reference/api-identifiers/#segment--filter-name)。 |
| filter\_expression\* | 是 | string | <p>根据<a href="/developer/api-reference/segmentation-filters-api/segmentation-language/">细分语言</a>规则构建的表达式。<br /><strong>示例：</strong> <code>T("City", eq, "Madrid")</code> 用于细分城市为马德里的用户。</p> |
| application | 否 | string | [Pushwoosh application code (Pushwoosh 应用程序代码)](/zh/developer/api-reference/api-identifiers/#application-code)。此参数仅适用于高速设置 (High-Speed Setup)；否则请省略。 |
| expiration\_date | 否 | string | 筛选器到期时间。除非在预设 (Preset) 或 RSS 源中使用，否则筛选器将在指定日期自动删除。 |

**200**
```json
{
  "status_code": 200, 
  "status_message": "OK", 
  "response": {
    "name": "filter name"
  }
}
```



**示例**
```json
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "name": "City = Madrid",
    "filter_expression": "T(\"City\", eq, \"Madrid\")",
    "application": "B18XX-XXXXX",
    "expiration_date": "2025-01-01"
  }
}

// 为时区创建筛选器
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // 来自 Pushwoosh 控制面板的 API access token
    "name": "Timezone Filter",
    "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])"
  }
}
```


## listFilters

`POST` `https://api.pushwoosh.com/json/1.3/listFilters`

返回可用细分 (筛选器) 及其条件的列表。

**请求正文**

| 名称 | 必需 | 类型 | 描述 |
| --------------------------------------------- | -------- | ------ | ---------------------------------------------- |
| auth\* | 是 | string | 来自 Pushwoosh 控制面板的 [API access token (API 访问令牌)](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| application\* | 是 | string | [Pushwoosh application code (Pushwoosh 应用程序代码)](/zh/developer/api-reference/api-identifiers/#application-code) |


**200**
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "filters": [{
      "code": "52551-F2F42",
      "name": "City = Madrid",
      "filter_expression": "T(\"City\", eq, \"madrid\")",
      "expiration_date": "2025-01-01",
      "application": "B18XX-XXXXX"
    }]
  }
}

```


**示例**
```json
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "application": "B18XX-XXXXX"
  }
}
```

## deleteFilter

`POST` `https://api.pushwoosh.com/json/1.3/deleteFilter`

删除一个现有的筛选器。

**请求正文**

| 名称 | 类型 | 描述 |
| -------------------------------------- | ------ | ---------------------------------------------- |
| auth\* | string | 来自 Pushwoosh 控制面板的 [API access token (API 访问令牌)](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| name\* | string | [Filter name (筛选器名称)](/zh/developer/api-reference/api-identifiers/#segment--filter-name)。 |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
</Tabs>



```json title="示例"
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // 来自 Pushwoosh 控制面板的 API access token
    "name": "filter name"
  }
}
```

## exportSegment

`POST` `https://api.pushwoosh.com/api/v2/audience/exportSegment`

一个计划性请求。导出符合指定筛选器条件的订阅者列表。

**请求正文**
| 名称 <div style="width:100px"></div> | 必需 <div style="width:100px"></div> | 类型 | 描述 |
|----------------------------|------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| auth\* | 是 | string | 来自 Pushwoosh 控制面板的 [API access token (API 访问令牌)](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| filterExpression\* | 是 | string | 筛选器条件 |
| exportData | 否 | array | 要导出的数据。可能的值：`"hwids"`、`"push_tokens"`、`"users"`、`"tags"`、`"location"`。包含 `"location"` 会在导出的 CSV 中添加 `Latitude` 和 `Longitude` 列。如果省略 `exportData`，则默认导出中会包含 `Latitude` 和 `Longitude`。 |
| filterCode | 否 | string | 预制的 [filter code (筛选器代码)](/zh/developer/api-reference/api-identifiers/#segment--filter-code)，可替代 `filterExpression` 使用。可以从 `/listFilters` API 或在控制面板中查看筛选器时从浏览器地址栏获取。 |
| applicationCode | 如果您使用 `filterExpression` 或 `filterCode`，则此项为必需。 | string | [Pushwoosh application code (Pushwoosh 应用程序代码)](/zh/developer/api-reference/api-identifiers/#application-code) |
| generateExport | 否 | boolean | 默认设置为 `true`，响应中会包含一个下载文件的链接。如果为 `false`，响应中将只发送设备数量。 |
| format | 否 | string | 设置导出文件的格式：`"csv"` 或 `"json_each_line"`。如果省略，则生成 CSV 文件。 |
| tagsList | 否 | array | 指定要导出的 [tags (标签)](/zh/developer/api-reference/api-identifiers/#tag)。要仅获取特定标签，`"exportData"` 数组应包含 `"tags"` 值。 |
| includeWithoutTokens | 否 | boolean | 设置为 `true` 可在导出文件中包含没有推送令牌的用户。默认为 `false`。 |


<Tabs>
<TabItem label="200 成功">
```json
{
  "task_id": "177458"
}
```
</TabItem>
</Tabs>



```json title="示例"
{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // 必需。来自 Pushwoosh 控制面板的 API access token
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // 筛选器条件，语法请参考细分语言指南
  "filterCode": "12345-67890",                              // 预制筛选器代码，可替代 filterExpression 使用
  "applicationCode": "00000-AAAAA",                         // 如果您使用 `filterExpression` 或 `filterCode`，则此项为必需。Pushwoosh 应用程序代码。可以从 /listFilters API 请求或在控制面板中查看筛选器时从浏览器地址栏获取。
  "generateExport": true,                                   // 如果为 false，响应中将只发送设备数量；默认情况下，响应包含下载 CSV 文件的链接
  "format": "json_each_line",                               // 用于呈现数据的文件格式："csv" – 下载 .csv 文件；"json" – 包含所有导出设备的 JSON 文件；或 "json_each_line" – 每个设备的 JSON 行。如果未指定，默认为 CSV 格式。
  "exportData": ["hwids", "tags"],                          // 可选。要导出的数据。可能的值："hwids"、"push_tokens"、"users"、"tags"、"location"、"fcm_keys"、"web keys"
  "tagsList": ["Name", "Level"],                            // 可选。指定要导出的标签。要仅获取特定标签，应在 "exportData" 数组中发送 "tags" 值，或者 "exportData" 为空。
  "includeWithoutTokens": true                              // 可选。设置为 true 可在导出文件中包含没有推送令牌的用户。默认为 false。
}
```

<Aside type="note">
有关编写筛选器表达式的细分语言参考，请参阅[此处](/zh/developer/api-reference/segmentation-filters-api/segmentation-language/)。
</Aside>

例如，要导出特定应用的所有订阅者，请使用以下筛选器条件：

```json
{
  "auth": "yxoPUlwqm…………pIyEX4H",            // 来自 Pushwoosh 控制面板的 API access token
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // 引用应用细分的筛选器表达式
  "applicationCode": "AAAAA-BBBBB"           // 必需的 Pushwoosh 应用程序代码
}
```

<Aside type="caution">
在响应中，您将获得用于获取结果文件的 **`task_id`**。然后，在请求正文中调用 [/exportSegment/result](./#exportsegment-results) 并附上该 `task_id` 以检索结果文件。
</Aside>

## exportSegment 结果

`POST` `https://api.pushwoosh.com/api/v2/audience/exportSegment/result`

**检索包含 /exportSegment 结果的 CSV 文件的链接。**

**请求正文**

| 名称 | 类型 | 描述 |
| ------------------------------------------ | ------ | -------------------------------------------------------- |
| auth\* | String | 来自 Pushwoosh 控制面板的 [API access token (API 访问令牌)](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| task\_id\* | String | 在您的 `/exportSegment` 响应中收到的标识符。 |

<Tabs>
<TabItem label="200：OK">
```json
{
  "devicesCount": "24735",
  "filename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip",
  "status": "completed"
}
```
</TabItem>
</Tabs>

将在您的 `/exportSegment` 响应中收到的 "**task\_id**" 传递到 `/exportSegment/result` 请求正文中。

在 `/exportSegment/result` 响应中，您将收到 `"filename"` 参数。点击该参数值中提供的链接可自动下载一个 ZIP 压缩包。
解压该压缩包以检索包含设备数据的 CSV 或 JSON 文件 (取决于您请求中指定的 `"format"`)。

从 2025 年 4 月 3 日起，下载文件需要授权：

- 如果通过浏览器下载，只需登录 **Pushwoosh 控制面板**即可获得访问权限。
- 如果通过服务器软件下载，请在您的请求中包含以下标头：
`Authorization: Token YOUR_API_TOKEN`

如果您在 `/exportSegment` 请求中指定了 `"exportData"`，下载的文件将仅包含请求的数据。默认情况下，文件包含以下用户数据：

| **字段** | 描述 | **值示例** |
| ------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------ |
| Hwid | 设备的 [Hardware ID (硬件 ID)](/zh/developer/api-reference/api-identifiers/#hardware-id) | 01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8 |
| User ID | 将设备与特定用户关联的 [User ID (用户 ID)](/zh/developer/api-reference/api-identifiers/#user-id)。如果未分配 User ID，则使用 HWID。 | user8192 |
| Push Token | 由云消息网关分配给设备的唯一标识符。[了解更多](/zh/developer/api-reference/api-identifiers/#push-token) | eeeb2fd7....0fc3547 |
| Type | 平台类型 (整数)。 | 1 |
| Type (humanized) | 平台类型 (字符串)。 | iOS |
| Age | 默认 Age 标签的值。 | 29 |
| ApplicationVersion | 默认 Application Version 标签的值。 | 1.12.0.0 |
| City | 默认 City 标签的值。 | us, boston |
| TagName | 在您的账户中创建的标签的值。 | TagValue |