控制组 API

控制组是应用程序用户中的一部分排除用户，他们从不接收营销消息，因此可以衡量消息传递对其产生的影响。此 API 管理控制组并响应每个用户的成员资格。您可以使用它从自己的系统中镜像控制面板的 设置 > 控制组 操作，或在发送或导入之前检查特定用户 ID 是否被排除。

基础 URL

https://rpc-api.svc-nue.pushwoosh.com

所有端点都通过 HTTPS 提供服务。除非另有说明，否则请求和响应均使用 application/json。

身份验证

每个请求都必须包含一个 Authorization 标头，其中包含您的服务器 API 令牌：

Authorization: Api YOUR_API_TOKEN

约定

字段命名： 请求正文和查询/路径参数接受 lowerCamelCase（例如 controlGroupCode、userIds），服务器可以解组任何一种大小写形式。响应始终使用 proto 字段名以 snake_case（application_id、in_control_group 等）进行编组。下面的响应示例和控制组对象参考使用了这种大小写形式。
code： 每个控制组响应都带有自己的代码，该代码在 Create 时生成。将此代码作为 controlGroupCode 传递给 Get、UpdatePercentage、UpdateCountries、Rename、Disable、Reshuffle、ForceUpdateCalculation、GetCalculationStatus、GetAnalytics 和 CheckControlGroupMembership。
多个组： 一个应用程序可以有多个控制组。每个已启用的组都会在自己的国家/地区和标签范围内，独立于其他组，对每条营销消息排除用户，且各组可以重叠。发送时不会选择组。name 为空的组是应用程序的原始组，其工作方式相同。

错误响应

HTTP status	Meaning
`400 Bad Request`	无效参数，例如 `percentage` 超出 1–20 范围、`userIds` 为空或超过 1,000 个条目，无法识别的国家/地区代码、设置了 `scopeValues` 但未设置 `scopeTag`、`scopeTag` 指定了账户中不存在的标签，或 `UpdateSettings` 拒绝的 `scopeValues` 条目（见下文）。当对属于营销活动自身排除组的控制组执行 `UpdatePercentage`、`UpdateCountries`、`UpdateSettings`、`Disable`、`Reshuffle` 和 `Delete` 操作时，也会返回此错误（在线路上作为 `FailedPrecondition`），如下面的警告所述。`Reshuffle` 也会对已禁用（`percentage` 为 0）的组拒绝此操作。
`401 Unauthorized`	缺少或无效的 `Authorization` 标头。
`403 Forbidden`	应用程序或控制组不属于调用者的帐户。
`404 Not Found`	未找到控制组或应用程序。
`409 Conflict`	`Create` 使用了应用程序中已存在的 `name`。
`500 Internal Server Error`	意外的服务器端故障。

端点

Method	Path	Description
`GET`	`/api/applications/{code}/control_groups`	列出应用程序的控制组
`POST`	`/api/applications/{code}/control_groups`	创建控制组
`GET`	`/api/applications/{code}/control_groups/{control_group_code}`	获取单个控制组
`POST`	`/api/applications/{code}/control_groups/{control_group_code}`	调整控制组大小
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/countries`	将控制组范围重新限定为一组国家/地区
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/settings`	一次调用应用大小、国家/地区和标签范围以及生命周期模式
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/display_name`	重命名控制组
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/disable`	禁用控制组
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/reshuffle`	重新洗牌控制组
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/recalculate`	强制重新计算控制组的大小
`GET`	`/api/applications/{code}/control_groups/{control_group_code}/calculation_status`	轮询正在进行的大小计算
`GET`	`/api/applications/{code}/control_groups/{control_group_code}/analytics`	获取控制组与处理组的分析数据
`GET`	`/api/applications/{code}/control_groups/{control_group_code}/cycles`	列出该组已关闭的周期
`POST`	`/api/applications/{code}/control_groups/{control_group_code}/membership`	检查一批用户 ID 的成员资格
`DELETE`	`/api/applications/{code}/control_groups/{control_group_code}`	删除控制组

列出

列出为应用程序配置的每个控制组，未命名的原始组排在最前。

GET /api/applications/{code}/control_groups

路径参数

Parameter	Type	Description
`code`	string	要列出控制组的应用程序代码。

响应

Field	Type	Description
`control_groups`	array of Control group objects	为该应用程序配置的每个控制组。

创建

为应用程序创建一个命名的控制组，并返回其生成的代码。新组会在自己的国家/地区和标签范围内，与应用程序的其他已启用组并行，对每条营销消息排除用户。

POST /api/applications/{code}/control_groups

请求正文

Parameter	Type	Required	Description
`code`	string	是	要在其中创建组的应用程序代码。
`name`	string	是	组名，最多 64 个字符，不含冒号。在应用程序内必须唯一。属于成员资格密钥的一部分，因此永远不会更改。
`percentage`	integer	是	排除规模的百分比，范围为 1–20。
`segment`	string	否	用于衡量该组的 Seglang 表达式。省略则衡量整个基础用户。
`countries`	array of strings	否	用于限定排除范围的小写 ISO-3166-1 alpha-2 国家/地区代码。省略则适用于所有国家/地区。输入时代码不区分大小写。
`scopeTag`	string	否	用于限定排除范围的字符串或布尔标签，与 `countries` 取交集（AND）。省略则不限定标签范围。请参阅下面的标签范围。
`scopeValues`	array of strings	见备注	使用户进入范围的 `scopeTag` 值。设置了 `scopeTag` 时为必需，否则必须为空。
`displayName`	string	否	控制面板显示的名称，最多 64 个字符。省略则显示 `name`。

请求示例

{
  "code": "XXXXX-XXXXX",
  "name": "Q3 holdout",
  "percentage": 10
}

响应

返回 { "group": { ... } }，即新的控制组对象。

获取

根据其代码返回一个控制组，包括其排除规模、代数以及背后的用户计数。

GET /api/applications/{code}/control_groups/{control_group_code}

路径参数

Parameter	Type	Description
`code`	string	该组所属的应用程序代码。
`control_group_code`	string	控制组的代码。

响应

Field	Type	Description
`group`	Control group object	请求的控制组。
`total_users`	integer	应用程序中的所有用户。
`control_group_users`	integer	当前被排除的用户。
`calculation_status`	string	`TASK_STATUS_NOT_STARTED`、`TASK_STATUS_IN_PROGRESS` 或 `TASK_STATUS_COMPLETED`。
`has_data`	boolean	缓存的大小数据是否已可用。

UpdatePercentage

设置一个控制组的排除百分比 (1–20)。调整大小时会保留所有现有成员：排除组会在他们周围扩大或缩小，而不是重新抽取。已被 UpdateSettings 取代（后者一次调用即可应用大小、范围和生命周期模式），但仍受支持。

POST /api/applications/{code}/control_groups/{control_group_code}

请求正文

Parameter	Type	Required	Description
`percentage`	integer	是	新的排除规模百分比，范围为 1–20。

响应

成功时返回一个空对象：{}。

UpdateCountries

设置一个控制组所限定的国家/地区。更改范围会重新开始提升度量，因为被比较的人群发生了变化。排除组本身不会被重新抽取。已被 UpdateSettings 取代（后者还可设置标签范围），但仍受支持。

POST /api/applications/{code}/control_groups/{control_group_code}/countries

请求正文

Parameter	Type	Required	Description
`countries`	array of strings	是	小写 ISO-3166-1 alpha-2 国家/地区代码。空列表会将组的范围扩大回所有国家/地区。输入时代码不区分大小写。

请求示例

{
  "countries": ["us", "ca", "gb"]
}

响应

成功时返回一个空对象：{}。

UpdateSettings

一次调用即可应用控制组的大小、国家/地区和标签范围以及生命周期模式。会改变被排除的用户或排除时长的更改（大小、范围、模式、刷新周期或结束日期）会关闭当前运行的周期并开始新周期。发送当前值不会产生任何更改。对属于营销活动自身排除组的控制组会拒绝操作，与 UpdatePercentage 相同。

POST /api/applications/{code}/control_groups/{control_group_code}/settings

请求正文

Parameter	Type	Required	Description
`percentage`	integer	是	排除规模的百分比，范围为 1–20。
`countries`	array of strings	否	小写 ISO-3166-1 alpha-2 国家/地区代码。空列表会将组的范围扩大回所有国家/地区。
`scopeTag`	string	否	用于限定排除范围的字符串或布尔标签，与 `countries` 取交集（AND）。为空则移除标签范围。请参阅下面的标签范围。
`scopeValues`	array of strings	见备注	使用户进入范围的 `scopeTag` 值。设置了 `scopeTag` 时为必需，否则必须为空。
`mode`	string	否	成员资格的生命周期：`CONTROL_GROUP_MODE_PERMANENT`（默认）、`CONTROL_GROUP_MODE_AUTO_REFRESH` 或 `CONTROL_GROUP_MODE_EXPERIMENT`。
`refreshPeriodDays`	integer	见备注	两次重新抽取之间的天数，范围为 7–365。使用 `CONTROL_GROUP_MODE_AUTO_REFRESH` 时为必需，否则必须省略。
`endsAt`	string (RFC 3339)	见备注	实验关闭的时间，至少在 30 天之后。使用 `CONTROL_GROUP_MODE_EXPERIMENT` 时为必需，否则必须省略。

每个字段都按发送的值应用，与 UpdateCountries 相同：空的 countries 会将组的范围扩大回所有国家/地区，空的 scopeTag 会移除标签范围。

响应

返回 { "group": { ... } }，即更新后的控制组对象。

标签范围

控制组可以只排除某个字符串或布尔标签的值属于您所选集合的用户；如果同时设置了 countries，则两者取交集（AND）。可通过 Create 或 UpdateSettings 设置。

scopeTag 指定标签；为空表示没有标签范围。它不能是 Country：按国家/地区限定范围使用 countries，而不是标签。
scopeValues 列出 scopeTag 的哪些值在范围内。设置了 scopeTag 时至少需要一个，且不能重复。字符串标签的值不能是空字符串。布尔标签的值必须分别是 "true" 或 "false"。
对于没有 scopeTag 值的设备，视为在范围之外，与没有 Country 标签的设备相同。
成员资格本身不会改变：分配用户的公式不受范围影响。标签范围和国家/地区范围都是在其之上按设备进行的检查，用于缩小所选用户的哪些设备真正被排除，而不是公式选中谁。
用户级标签在设置时会被复制到该用户的每台设备上，因此上述设备级检查同样适用于用户级标签，而不仅仅是设备级标签。
更改 scopeTag，或将 scopeValues 作为集合更改（仅调整顺序不算），会以 CONTROL_GROUP_CYCLE_CLOSE_REASON_RESCOPED 关闭当前运行的周期，与更改 countries 相同。禁用组会保留其标签范围，就像保留 countries 一样。

重命名

设置控制面板为一个控制组显示的名称。name 是成员资格密钥的一部分，不会更改，因此该组保留相同的用户及其当前运行的周期。

POST /api/applications/{code}/control_groups/{control_group_code}/display_name

请求正文

Parameter	Type	Required	Description
`code`	string	是	该组所属的应用程序代码。
`controlGroupCode`	string	是	控制组的代码。
`displayName`	string	否	新名称，最多 64 个字符，且在应用程序内唯一。发送空字符串可重新显示 `name`。

响应

返回 { "group": { ... } }，即重命名后的控制组对象。

禁用

关闭一个控制组，但保留其本身及其代数，以便重新开启时恢复相同的排除组，而不是抽取一个新的。

POST /api/applications/{code}/control_groups/{control_group_code}/disable

响应

成功时返回一个空对象：{}。

重新洗牌

通过增加其代数来重新抽取一个控制组的排除样本。这是获得不同样本的唯一方法：成员资格是确定性的，因此禁用和重新启用会产生完全相同的样本。

POST /api/applications/{code}/control_groups/{control_group_code}/reshuffle

响应

Field	Type	Description
`generation`	integer	重新洗牌后该组的代数。

ForceUpdateCalculation

开始对一个控制组的大小进行新的计数。在新的计数完成之前，将继续提供先前缓存的数字。轮询 GetCalculationStatus 以获取进度。

POST /api/applications/{code}/control_groups/{control_group_code}/recalculate

响应

成功时返回一个空对象：{}。

GetCalculationStatus

在大小计算运行时，仅轮询一个控制组变化中的用户计数。

GET /api/applications/{code}/control_groups/{control_group_code}/calculation_status

响应

Field	Type	Description
`total_users`	integer	应用程序中的所有用户。
`control_group_users`	integer	在应用程序范围内计数的排除用户。
`calculation_status`	string	`TASK_STATUS_NOT_STARTED`、`TASK_STATUS_IN_PROGRESS` 或 `TASK_STATUS_COMPLETED`。
`has_data`	boolean	缓存的大小数据是否可用。

GetAnalytics

返回一个控制组的预计算控制组与处理组分析数据。

GET /api/applications/{code}/control_groups/{control_group_code}/analytics

查询参数

Parameter	Type	Required	Description
`windowDays`	string	否	回溯窗口预设：`WINDOW_DAYS_3`、`WINDOW_DAYS_7` 或 `WINDOW_DAYS_30`。

响应

Field	Type	Description
`events`	array of objects	每个跟踪事件一个条目，每个条目包含 `event`、`treatment` 和 `control`（`users`、`conversions`、`conversion_rate`、`events_per_user`）、`uplift_pct`、`incremental_events`、`percent_of_treatment`、`z_score`、`p_value`、`confidence_pct` 和 `significance`（`SIGNIFICANCE_NOT_ENOUGH_DATA`、`SIGNIFICANCE_NOT_SIGNIFICANT` 或 `SIGNIFICANCE_SIGNIFICANT`）。

ListControlGroupCycles

按从新到旧的顺序列出一个控制组已关闭的周期。每个周期是该组在两次设置更改之间所运行的成员资格，以及其抽取所依据的设置。当前运行的周期不在此列表中，其设置位于控制组对象本身。

GET /api/applications/{code}/control_groups/{control_group_code}/cycles

响应

Field	Type	Description
`cycles`	array of Control group cycle objects	从新到旧排列。

控制组周期对象

Field	Type	Description
`cycle_number`	integer	在组内按顺序编号；组自身的 `cycle_number` 是此处最后一个已关闭周期之后的编号。
`mode`	string	该组在此周期内运行的生命周期模式：`CONTROL_GROUP_MODE_PERMANENT`、`CONTROL_GROUP_MODE_AUTO_REFRESH` 或 `CONTROL_GROUP_MODE_EXPERIMENT`。
`generation`	integer	该组在此周期内的代数。
`percentage`	integer	此周期内的排除规模。
`countries`	array of strings	此周期内的国家/地区范围；空表示所有国家/地区。
`started_at` / `ended_at`	string (RFC 3339)	此周期的运行时间。
`close_reason`	string	周期结束的原因：`CONTROL_GROUP_CYCLE_CLOSE_REASON_ROLLOVER`、`_EXPIRED`、`_RESHUFFLED`、`_RESIZED`、`_RESCOPED`、`_MODE_CHANGED` 或 `_DISABLED`。
`scope_tag`	string	该周期的排除范围所限定的标签，与 `countries` 取交集（AND）。没有标签范围时为空，在标签范围出现之前关闭的每个周期也为空，即使该组之后设置了标签范围。
`scope_values`	array of strings	此周期内使用户进入范围的 `scope_tag` 值；仅与 `scope_tag` 一起设置。

CheckControlGroupMembership

报告每个用户 ID 当前是否被一个控制组排除。成员资格仅根据 ID 计算。不读取用户记录，因此即使是应用程序从未见过的 ID 也会得到响应，而对于禁用的组，每个 ID 都会返回 false 而不是错误。具有国家/地区或标签范围的组只有在用户至少有一台设备在该范围内时才会排除该用户，因此在这种情况下，未见过的 ID（没有任何设备）会返回 false，即使同一个 ID 在没有范围限制的组上会返回 true。使用此方法来检查特定发送或导入的用户，而不是导出整个组。

POST /api/applications/{code}/control_groups/{control_group_code}/membership

请求正文

Parameter	Type	Required	Description
`userIds`	array of strings	是	要检查的用户 ID，每次调用最多 1,000 个。

请求示例

{
  "userIds": ["user-1", "user-2", "user-3"]
}

响应

Field	Type	Description
`users`	array of objects	每个请求的 ID 一个条目，按给定的顺序排列（包括重复项）。每个条目都有 `user_id`（字符串）和 `in_control_group`（布尔值）。

响应示例

{
  "users": [
    { "user_id": "user-1", "in_control_group": false },
    { "user_id": "user-2", "in_control_group": true },
    { "user_id": "user-3", "in_control_group": false }
  ]
}

删除

完全移除一个控制组。它将不再排除用户，其统计数据也无法再打开。应用程序的其他组继续工作。

DELETE /api/applications/{code}/control_groups/{control_group_code}

响应

成功时返回一个空对象：{}。

控制组对象

Field	Type	Description
`code`	string	控制组代码（格式为 `XXXXX-XXXXX`），在组的生命周期内保持稳定。
`name`	string	组名，属于成员资格密钥的一部分。空表示应用程序的原始、未命名组。
`display_name`	string	控制面板显示的名称。为空则显示 `name`，未命名的组显示为 Global。
`segment`	string	衡量该组的 Seglang 表达式；空表示整个基础用户。
`percentage`	integer	排除规模的百分比，范围为 1–20。零表示该组已关闭。
`enabled`	boolean	该组当前是否正在排除用户。
`generation`	integer	每次重新洗牌时递增；`0` 表示从未重新洗牌。
`last_modified_at`	string (RFC 3339)	该组设置的最后更改时间。
`last_modified_by`	string	最后更改该组的用户的电子邮件。
`application_id`	integer	应用程序的数字 ID，是成员资格密钥 `<application_id>:<generation>:<name>:<user_id>` 的第一部分，CheckControlGroupMembership 会对此密钥进行哈希计算以决定用户是否被排除。
`countries`	array of strings	限定排除范围的小写 ISO-3166-1 alpha-2 国家/地区代码。空表示所有国家/地区。
`scope_tag`	string	排除范围所限定的标签，与 `countries` 取交集（AND）；为空表示没有标签范围。请参阅标签范围。
`scope_values`	array of strings	使用户进入范围的 `scope_tag` 值；布尔标签使用 `"true"` 和 `"false"`。

控制组 API

基础 URL

身份验证

约定

错误响应

端点

列出

路径参数

响应

创建

请求正文

请求示例

响应

获取

路径参数

响应

UpdatePercentage

请求正文

响应

UpdateCountries

请求正文

请求示例

响应

UpdateSettings

请求正文

响应

标签范围

重命名

请求正文

响应

禁用

响应

重新洗牌

响应

ForceUpdateCalculation

响应

GetCalculationStatus

响应

GetAnalytics

查询参数

响应

ListControlGroupCycles

响应

控制组周期对象

CheckControlGroupMembership

请求正文

请求示例

响应

响应示例

删除

响应

控制组对象

相关内容