# Audience API

## bulkSetTags

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

为设备列表设置标签值。

<Aside type="caution" title="重要">
  使用 `bulkSetTags` 方法时，请确保为至少 50 台设备设置标签值。要为单个设备设置标签，请使用 [`setTags`](/zh/developer/api-reference/device-api/#settags) 方法。
</Aside>

#### 请求正文

| 名称                                           | 类型    | 描述                                                                 |
| ---------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| application\*  | String  | [Pushwoosh application code](/zh/developer/api-reference/api-identifiers/#application-code)                                                     |
| auth\*         | String  | 来自 Pushwoosh 控制面板的 [API access token](/zh/developer/api-reference/api-identifiers/#api-access-token)。                              |
| create\_missing\_tags                          | Boolean | 如果为 true，则会自动创建缺失的标签。                            |
| devices\*      | Object  | 设备数组。                                                           |
| devices.hwid                                   | String  | 可用于识别设备，替代 user\_id 或 push\_token。[了解更多](/zh/developer/api-reference/api-identifiers/#hardware-id)         |
| devices.user\_id                               | String  | 可用于识别用户，替代 hwid 或 push\_token。[了解更多](/zh/developer/api-reference/api-identifiers/#user-id)               |
| devices.push\_token                            | String  | 可用于识别设备，替代 hwid 或 user\_id。[了解更多](/zh/developer/api-reference/api-identifiers/#push-token)                |
| devices.list\_operator                         | String  | 定义如何为列表类型的 [tags](/zh/developer/api-reference/api-identifiers/#tag) 设置值：set、append 或 remove |
| devices.tags\* | Object  | 为指定标签设置的值。                                       |

<Tabs>
  <TabItem label="成功">
    ```json
    {
      "request_id": "用于在 GET 方法中获取作业状态的 request_id",
      "status": "Pending"
    }
    ```
  </TabItem>

  <TabItem label="错误">
    ```json
    {
      "message": "invalid request"
    }
    ```
  </TabItem>
</Tabs>


```json title="请求："
{
  "application": "application code",   // 必需。Pushwoosh 应用代码
  "auth": "Pushwoosh auth token",      // 必需。来自 Pushwoosh 控制面板的 API access token
  "create_missing_tags": false,        // 可选。是否应自动创建缺失的标签
  "devices": [{                        // 必需。设备数组
    "hwid": "device hwid",             // 可选。可用于识别设备，替代
                                       //           "user_id" 或 "push_token"。
    "user_id": "user ID",              // 可选。可用于识别用户，替代 "hwid" 或 "push_token"。
    "push_token": "device push token", // 可选。可用于识别设备，替代 "hwid" 或 "user_id"。
    "list_operator": "set",            // 必需。对于列表标签。定义如何为
                                       //           列表类型的标签设置值：set、append 或 remove
    "tags": {                          // 必需。为指定标签设置的值。
      "tag_name": "tagvalue",          //           使用正确的值类型
      "tag_name2": "tagvalue2"
    }
  }]
}

```

```json title="响应："
{
  "request_id": "用于在 GET 方法中获取作业状态的 request_id",
  "status": "Pending"
}
```

## bulkSetTags status

`GET` `https://api.pushwoosh.com/api/v2/audience/bulkSetTags/{request_id}?detailed=false`

返回 `/bulkSetTags` 操作的状态

#### 路径参数

| 名称        | 类型   | 描述                                |
| ----------- | ------ | ------------------------------------------ |
| request\_id | String | 来自前一个 `/bulkSetTags` 调用的请求 ID |

#### 查询参数

| 名称     | 类型    | 描述                                             |
| -------- | ------- | ------------------------------------------------------- |
| detailed | Boolean | (true/false) 是否返回每个设备的详细信息 |

```json title="响应："
{
  "request_id": "请求的 ID",
  "status": "Completed",          // 也可为 "Pending", "Failed"
  "progress": 100,                // 作业进度 0-100
  "devices_success": 100,         // 成功的设备
  "devices_not_found": 0,         // 在 Pushwoosh 中未找到的设备
  "devices_failed": 0,            // 出错的设备
  "devices": [{                   // 设备报告（仅在 detailed = true 时）
    "hwid": "device hwid",
    "status": "done",             // 也可为 "failed", "not found"
    "tags": {
      "tagName": "ok",
      "tagName2": "tag not found",
      "tagName3": "wrong value. expect :string"
    }
  }]
}

```

## bulkRegisterDevice

在一个请求中向 Pushwoosh 注册多个设备。它还允许为每个设备指定各种标签。

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

### 请求正文参数

| 参数 | 类型 | 必需 | 描述 |
| :---- | ----- | ----- | ----- |
| application | string | 是 | [Pushwoosh application code](/zh/developer/api-reference/api-identifiers/#application-code) |
| auth | string | 是 | [API access token](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| devices | array | 是 | 设备对象数组。每个对象代表一个设备及其相关数据。详情请参见下方的 **设备对象参数** 表。 |

#### 设备对象参数

| 参数       | 类型     | 必需 | 描述                                                                                     |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid          | string | 是      | 设备的 [硬件 ID](/zh/developer/api-reference/api-identifiers/#hardware-id) 或唯一标识符。                                           |
| push_token    | string | 是      | 设备的 [Push token](/zh/developer/api-reference/api-identifiers/#push-token)。                                                                     |
| platform      | integer| 是      | 平台标识符。[了解更多](/zh/developer/api-reference/messages-api/api-prerequisites/#platforms) |
| list_operator | string | 否       | 确定列表类型标签的操作：<br/> - **"append"**: 将指定的值添加到标签列表。<br/> - **"remove"**: 从标签列表中删除指定的值。<br/> **注意**：如果未指定 `list_operator` 参数，标签列表中的所有现有值都将被提供的值替换。 |
| tags          | object | 否       | 分配给设备的自定义 [tags](/zh/developer/api-reference/api-identifiers/#tag)。标签是用于分段的键值对。            |



#### 请求示例

```json
{
  "application": "application code",   // 必需。Pushwoosh 应用代码
  "auth": "Pushwoosh auth token",      // 必需。来自 Pushwoosh 控制面板的 API access token
  "devices": [{                        // 必需。设备数组
    "hwid": "device hwid",             // 必需。设备的唯一标识符（可以是电子邮件）。
    "push_token": "device push token", // 必需。设备的推送通知令牌。
    "platform": 14,                    // 必需。设备平台（例如，14 代表电子邮件）。
    "list_operator": "append",         // 可选。对于列表标签。从列表类型的标签中添加或删除指定的值。
    "tags": {                          // 可选。为指定标签设置的值。
      "language": "en",                //           使用正确的值类型。
      "CSV_Import": "summer_camp"
    }
  },
  {
    "hwid": "device hwid 2",           // 必需。第二个设备的唯一标识符。
    "push_token": "device push token 2", // 必需。设备的推送通知令牌。
    "platform": 14,                    // 必需。设备平台。
    "list_operator": "remove",         // 可选。从列表类型的标签中添加或删除值。
    "tags": {                          // 可选。要从指定标签中删除的值。
      "language": "en",
      "CSV_Import": "summer_camp2"
    }
  },
  {
    "hwid": "device hwid 3",           // 必需。第三个设备的唯一标识符。
    "push_token": "device push token 3", // 必需。设备的推送通知令牌。
    "platform": 14,                    // 必需。设备平台。
    "tags": {                          // 可选。为指定标签设置的值。
      "language": "en",
      "CSV_Import": "summer_camp3"
    }
  }]
}

```

### 响应

该方法会返回一个操作 ID，可用于跟踪批量注册过程的状态和结果。

```json
{
  "request_id": "用于在 GET 方法中获取作业状态的 request_id",
  "status": "Pending"
}

```

## bulkRegisterDevice status

您可以通过发出以下 **GET** 请求来检查批量注册过程的状态：

`GET` `https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice/{request_id}?detailed=true`

| 参数 | 类型 | 必需 | 描述 |
| ----- | ----- | ----- | ----- |
| request_id | string | 是 | POST 请求返回的请求 ID。 |
| detailed | boolean | 否 | 如果设置为 `true`，响应将包含每个已注册设备的详细结果。 |


#### 响应示例

```json
{
  "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782",
  "status": "Completed",
  "progress": 100,
  "devices_success": 4,
  "devices": [
    {
      "hwid": "user1@example.com",
      "status": "done"
    },
    {
      "hwid": "user2@example.com",
      "status": "done"
    },
    {
      "hwid": "user3@example.com",
      "status": "done"
    },
    {
      "hwid": "invalid_email@example.com",
      "status": "failed"
    }
  ]
}

```

## bulkUnregisterDevice

在一个请求中从 Pushwoosh 注销多个设备。

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

### 请求正文参数

| 参数 | 类型 | 必需 | 描述 |
| :---- | ----- | ----- | ----- |
| application | string | 是 | [Pushwoosh application code](/zh/developer/api-reference/api-identifiers/#application-code) |
| auth | string | 是 | [API access token](/zh/developer/api-reference/api-identifiers/#api-access-token) |
| devices | array | 是 | 设备对象数组。每个对象代表一个设备及其相关数据。详情请参见下方的 **设备对象参数** 表。 |

#### 设备对象参数

| 参数       | 类型     | 必需 | 描述                                                                                     |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid          | string | 是      | 设备的硬件 ID 或唯一标识符。[了解更多](/zh/developer/api-reference/api-identifiers/#hardware-id)                                          |



#### 请求示例

```json
{
  "application": "application code",   // 必需。Pushwoosh 应用代码
  "auth": "Pushwoosh auth token",      // 必需。来自 Pushwoosh 控制面板的 API access token
  "devices": [{                        // 必需。设备数组
    "hwid": "device hwid",             // 必需。设备的唯一标识符（可以是电子邮件）。
  },
  {
    "hwid": "device hwid 2",           // 必需。第二个设备的唯一标识符。
  },
  {
    "hwid": "device hwid 3",           // 必需。第三个设备的唯一标识符。
  }]
}

```

### 响应

该方法会返回一个操作 ID，可用于跟踪批量处理过程的状态和结果。

```json
{
  "request_id": "用于在 GET 方法中获取作业状态的 request_id",
  "status": "Pending"
}

```

## bulkUnregisterDevice status

您可以通过发出以下 **GET** 请求来检查批量注销过程的状态：

`GET` `https://api.pushwoosh.com/api/v2/audience/bulkUnregisterDevice/{request_id}?detailed=true`

| 参数 | 类型 | 必需 | 描述 |
| ----- | ----- | ----- | ----- |
| request_id | string | 是 | POST 请求返回的请求 ID。 |
| detailed | boolean | 否 | 如果设置为 `true`，响应将包含每个已注销设备的详细结果。 |


#### 响应示例

```json
{
  "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782",
  "status": "Completed",
  "progress": 100,
  "devices_success": 4,
  "devices": [
    {
      "hwid": "user1@example.com",
      "status": "done"
    },
    {
      "hwid": "user2@example.com",
      "status": "done"
    },
    {
      "hwid": "user3@example.com",
      "status": "done"
    },
    {
      "hwid": "invalid_email@example.com",
      "status": "failed"
    }
  ]
}

```