# 세분화(필터) API

## createFilter

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

새로운 필터를 생성합니다.

**요청 본문**

| 이름 | 필수 | 유형 | 설명 |
| ---------------------------------------------------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| auth\* | 예 | string | Pushwoosh 제어판의 [API 액세스 토큰](/ko/developer/api-reference/api-identifiers/#api-access-token). |
| name\* | 예 | string | [필터 이름](/ko/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 애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code). 이 매개변수는 고속 설정에서만 사용할 수 있으며, 그렇지 않은 경우 생략합니다. |
| 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 액세스 토큰
    "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 액세스 토큰](/ko/developer/api-reference/api-identifiers/#api-access-token). |
| application\* | 예 | string | [Pushwoosh 애플리케이션 코드](/ko/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 액세스 토큰](/ko/developer/api-reference/api-identifiers/#api-access-token). |
| name\* | string | [필터 이름](/ko/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 액세스 토큰
    "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 액세스 토큰](/ko/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 | 미리 만들어진 [필터 코드](/ko/developer/api-reference/api-identifiers/#segment--filter-code)로, `filterExpression` 대신 사용할 수 있습니다. `/listFilters` API 또는 제어판에서 필터를 볼 때 브라우저 주소 표시줄에서 얻을 수 있습니다. |
| applicationCode | `filterExpression` 또는 `filterCode`를 사용하는 경우 필수입니다. | string | [Pushwoosh 애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code) |
| generateExport | 아니요 | boolean | 기본적으로 `true`로 설정되며, 응답에는 파일을 다운로드할 수 있는 링크가 포함됩니다. false인 경우, 장치 수만 응답으로 전송됩니다. |
| format | 아니요 | string | 내보낸 파일의 형식을 설정합니다: "csv" 또는 "json_each_line". 생략하면 CSV 파일이 생성됩니다. |
| tagsList | 아니요 | array | 내보낼 [태그](/ko/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 액세스 토큰
  "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">
필터 표현식 작성을 위한 세분화 언어 참조는 [여기](/ko/developer/api-reference/segmentation-filters-api/segmentation-language/)에서 찾을 수 있습니다.
</Aside>

예를 들어, 특정 앱의 모든 구독자를 내보내려면 다음 필터 조건을 사용하세요:

```json
{
  "auth": "yxoPUlwqm…………pIyEX4H",            // Pushwoosh 제어판의 API 액세스 토큰
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // 앱 세그먼트를 참조하는 필터 표현식
  "applicationCode": "AAAAA-BBBBB"           // 필수 Pushwoosh 앱 코드
}
```

<Aside type="caution">
응답에서 결과 파일을 얻기 위한 **`task_id`**를 받게 됩니다. 그런 다음, 요청 본문에 해당 `task_id`를 사용하여 [/exportSegment/result](./#exportsegment-results)를 호출하여 결과 파일을 검색하세요.
</Aside>

## exportSegment 결과

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

**/exportSegment 결과가 포함된 CSV 파일 링크를 검색합니다.**

**요청 본문**

| 이름 | 유형 | 설명 |
| ------------------------------------------ | ------ | -------------------------------------------------------- |
| auth\* | String | Pushwoosh 제어판의 [API 액세스 토큰](/ko/developer/api-reference/api-identifiers/#api-access-token). |
| task\_id\* | String | `/exportSegment` 응답에서 받은 식별자. |

<Tabs>
<TabItem label="200: 확인">
```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 | [장치의 하드웨어 ID](/ko/developer/api-reference/api-identifiers/#hardware-id) | 01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8 |
| User ID | 장치를 특정 사용자와 연결하는 [사용자 ID](/ko/developer/api-reference/api-identifiers/#user-id). 사용자 ID가 할당되지 않은 경우 HWID가 사용됩니다. | user8192 |
| Push Token | 클라우드 메시징 게이트웨이가 장치에 할당한 고유 식별자. [자세히 알아보기](/ko/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 |