本文档提供「A/B测试」应用中开放接口V3版本的说明。
可用范围包括

• 实验信息：创建实验、获取实验详情、获取实验列表、修改实验、开始实验、结束实验
• 指标信息：创建指标、删除指标、获取指标详情、获取指标列表、全量修改指标信息、修改指标状态
• 互斥组信息：获取互斥组列表、新建互斥组
• 报告页信息：获取实验报告基础数据

如需使用老版本开放接口，请参考：A/B测试开放接口

为了保证您和用户的数据安全，开放接口权限默认是关闭的。
在开始使用之前，您需要联系我们开通。（您可以通过服务对接的飞书/微信群或页面右下角的在线客服与我们取得联系）

• 开通后，我们会为您提供导出所需的AK/SK，收到后请务必妥善保管和使用。
• 开通时请和对接人员确认需要开放的接口范围以及接口使用额度，不在开放范围内的接口以及超出限额的接口请求将被拒绝。

为了方便集成和使用OpenAPI，我们提供了SDK。其主要功能是提供了对签名过程和复杂查询参数的包装。
SDK已经在 Github 上开源，建议使用Github 源码的方式进行集成。
基本使用流程为：

1. 根据ak, sk, API 服务地址初始化一个RangersClient
2. 使用RangersClient的request接口或者data_tester来调用具体API（具体的方法名称在不同的语言上会有命名格式的区别）

由于中国区和非中国区是隔离不互通的，OpenAPI 的服务地址需要根据所在地区进行设置：

• 中国区：https://analytics.volcengineapi.com
• 非中国区： https://analytics.byteplusapi.com
• 私有化部署：根据私有化部署的环境来获取，即产品的域名地址。

SDK使用说明 #

Java #

• 源码：https://github.com/volcengine/datafinder-sdk-openapi-java
• 软件包：https://github.com/volcengine/datafinder-sdk-openapi-java/raw/main/release/javasdk.zip
• 初始化示例：

String ak = "{使用AK替换}";
String sk = "{使用SK替换}";

// SDK 的默认url地址是指向中国区 SAAS 的
RangersClient bc = new RangersClient(ak, sk);

// 海外和私有化需要指定url地址, 可以参考上文
String url="{使用非中国区或者Tester服务域名替换}";
RangersClient bc = new RangersClient(ak, sk, url);

String result = bc.dataTester("/openapi/v1/openapi-test", "GET");
System.out.println(result);

Python #

• 源码：https://github.com/volcengine/datafinder-sdk-openapi-py
• 软件包：https://github.com/volcengine/datafinder-sdk-openapi-py/raw/main/release/rangersdk-1.2.0.tar.gz

Python SDK 软件包的形式下载后在shell执行以下命令完成安装：

# python需要3.7及以上版本
pip install rangersdk-${version}.tar.gz

• 初始化示例：

from rangersdk import RangersClient

ak = '{使用AK替换}'
sk = '{使用SK替换}'
bc = RangersClient(ak, sk)

# 海外和私有化需要指定url地址, 可以参考上文,
url = '{使用非中国区或者Tester服务域名替换}'
# 注意这里传参数，一定要写成 url=url
bc = RangersClient(ak, sk, url=url)

re = bc.data_tester("/openapi/v1/openapi-test", method="GET")
print(re.json())

Golang #

• 源码：https://github.com/volcengine/datafinder-sdk-openapi-go
• 软件包：https://github.com/volcengine/datafinder-sdk-openapi-go/raw/main/release/gosdk.zip
• 初始化示例：

var (
   ak = "{使用AK替换}"
   sk = "{使用SK替换}"
)
bc := dslcontent.NewRangersClient(ak, sk)

// 海外和私有化需要指定url地址, 可以参考上文
url = '{使用非中国区或者Tester服务域名替换}'
bc := dslcontent.NewRangersClientWithUrl(ak, sk, url)

res, _ := bc.DataTester("/openapi/v1/openapi-test", "GET")
data, err := ioutil.ReadAll(res.Body)
fmt.Println(err, string(data))

JS #

• 源码：https://github.com/volcengine/datafinder-sdk-openapi-js
• 软件包：https://github.com/volcengine/datafinder-sdk-openapi-js/raw/main/release/nodejssdk.zip
• 初始化示例：

ak = "{使用AK替换}"
sk = "{使用SK替换}"
bc = new RangersClient(ak, sk)

// 海外和私有化需要指定url地址, 可以参考上文
url = '{使用非中国区或者Tester服务域名替换}'
bc = RangersClient(ak, sk, url=url)

bc.dataTester("/openapi/v1/openapi-test", {method: "GET"})
    .then(res => res.json())
    .then(response => {
        if (200 !== response['code']) {
            throw " result is not ok, code: " + response['code'] + ", message: " + response['message'];
        }
        console.log(response)
        console.log('success.')
    })
    .catch(error => console.error('error:', error));

PHP #

• 源码：https://github.com/volcengine/datafinder-sdk-openapi-php
• 软件包：https://github.com/volcengine/datafinder-sdk-openapi-php/raw/main/release/phpsdk.zip
• 初始化示例：

$ak = "{使用AK替换}";
$sk = "{使用SK替换}";
$bc = new RangersClient($ak, $sk);

// 海外和私有化需要指定url地址, 可以参考上文
$url = '{使用非中国区或者Tester服务域名替换}'
$bc = new RangersClient($ak, $sk, $url);

echo $bc->dataTester("/openapi/v1/openapi-test", "GET");

SDK使用注意 #

中文编码 #

获取列表的相关接口（实验、指标、互斥组）支持根据关键字查询，如需查询中文，Java、Python、PHP需要调用前自行进行url转码，转码方法如下
golang SDK和nodeJs SDK不需要自行转码
Java

import java.net.URLEncoder;

String keyword = URLEncoder.encode("中文关键字", "UTF-8")

Python

import urllib.parse

keyword = urllib.parse.quote("中文关键字", encoding="UTF-8")

PHP

$keyword = urlencode("中文关键字");

创建实验 #

接口描述： 创建一个编程实验或MAB实验。
请求路径：/openapi/v3/apps/{app_id}/experiments
请求方法：POST
请求参数

version结构说明

layer_info结构说明

mab_info结构说明

返回值

示例
编程实验，两个评估组，两个智能调优组，一共4个组，调优间隔30分钟，评估流量6%。

{
    "name": "test-mab",
    "duration": 14,
    "versions": [
        {
            "name": "对照组",
            "label": "对照组",
            "weight": 0.47,
            "is_mab": 1,
            "type": 0,
            "config": {
                "HcCVhO": "_Lf5XM"
            },
            "users": []
        },
        {
            "name": "实验组1",
            "label": "实验组1",
            "weight": 0.47,
            "is_mab": 1,
            "type": 1,
            "config": {
                "HcCVhO": "TAqqd4"
            },
            "users": []
        },
        {
            "name": "对照组-Besfw",
            "label": "对照组",
            "weight": 0.03,
            "is_mab": 0,
            "type": 1,
            "config": {
                "HcCVhO": "ij45wC"
            },
            "users": []
        },
        {
            "name": "实验组1-fL17k",
            "label": "实验组1",
            "weight": 0.03,
            "is_mab": 0,
            "type": 1,
            "config": {
                "HcCVhO": "WRDoSW"
            },
            "users": []
        }
    ],
    "major_metric": 100942,
    "metrics": [
        100940,
        100941,
        100942,
        100943,
        100944,
        100945,
        100946
    ],
    "mode": 1,
    "mab_info": {
        "interval_time": 1800,
        "non_mab_traffic": 6
    },
    "endpoint_type": 0,
    "layer_info": {
        "layer_id": -1,
        "version_resource": 1
    }
}

获取实验详情 #

说明： 根据实验ID获取实验详情
请求路径：/openapi/v3/apps/{app_id}/experiments/{experiment_id}
请求方法：GET
返回值

data信息

experiment结构说明

metric结构说明

version结构说明

获取实验列表 #

说明： 分页获取APP下的实验列表
注意：如果搜索关键字keyword包含中文，则需要先进行url转义，再进行调用
请求路径：/openapi/v3/apps/<app_id>/experiments
请求方法：GET
URL查询参数

返回值

experiments结构说明

修改实验信息 #

说明： 修改实验的配置信息。通过Method来区分是全量修改还是部分修改。

• 全量修改：Method=PUT。请求参数中的所有必填参数必须包含。
• 部分修改：Method=PATCH。可以任意传递支持的配置参数，请求体中有的参数，才会进行校验与修改，请求体中没有的参数，则会保持现状。

注意：由于使用的网络库本身不支持不支持PATCH方法，因此Java SDK暂不支持PATCH方法
请求路径：/openapi/v3/apps/{app_id}/experiments/<experiment_id>
请求方法：PUT/PATCH
请求参数

version结构

layer_info结构

返回值

修改实验关联指标组 #

说明： 修改实验关联的指标组，设置结果会直接覆盖实验关联指标的配置。
请求路径： /openapi/v3/apps/<app_id>/metric_groups/experiments/{experiment_id}/update_watching_metric_groups
请求方法: PUT

• 请求体请求参数如下。

  参数名称		类型	是否必须	描述
  relation_metric_groups		[object]	是	修改后实验关联的指标组列表。指标组列表中的每个指标对象包含：metric_group_id、metric_ids、type三个字段，详细说明可参见表格下方的参数说明。 注意 调用此接口修改实验关联指标组时，会将本次设置结果直接覆盖实验的指标配置，而非基于此前实验的指标配置基础上进行新增、删除的操作。因此建议在进行修改前，您可调用“获取实验详情”接口先了解当前实验的指标有哪些，需要保留的指标组需同时添加在本次的修改指标中。
  	metric_ids	[int]	是	指标ID列表，配置为修改后实验的指标ID列表。您可以通过“获取指标列表”接口获取指标ID。 注意 此处配置的指标需要为当前实验所在应用下创建的指标。
  	metric_group_id	int	是	指标组ID，您可以通过“获取指标详情”接口，基于指标ID获取指标组ID。
  	type	string	是	修改后实验的指标类型，支持设置为： core：实验核心指标，仅支持设置一个实验核心指标。 watching：实验关注指标，支持设置多个实验关注指标。

• 请求示例

  {
      "relation_metric_groups": [
          {
              "metric_group_id": 1679062,
              "metric_ids": [
                  114314
              ],
              "type": "core"
          },
          {
              "metric_group_id": 158338,
              "metric_ids": [
                  83731
              ],
              "type": "watching"
          }
      ]
  }
  

返回参数

开始实验 #

说明： 开始一个测试中的实验。使其状态变为运行中。
请求路径： /openapi/v3/apps/<app_id>/experiments/<experiment_id>/launch
请求方法： PUT
返回值

暂停实验 #

说明： 暂停指定实验
请求路径 : /openapi/v3/apps/<app_id>/experiments/<experiment_id>/pause
请求方法: POST
请求参数

返回值

恢复实验 #

说明： 恢复指定实验
请求路径 : /openapi/v3/apps/<app_id>/experiments/<experiment_id>/restore
请求方法: POST
请求参数

返回值

结束实验 #

说明： 结束指定实验
请求路径 : /openapi/v3/apps/<app_id>/experiments/<experiment_id>/stop
请求方法: PUT
返回值

创建指标 #

说明： 创建一个A/B测试指标
请求路径： /openapi/v3/apps/<app_id>/metrics
请求方法：POST
请求参数

返回值

基于指标模板创建指标 #

说明： 基于现存的A/B测试指标，通过修改其中的属性过滤信息，创建新的A/B测试指标。只会替换模板指标中同名的属性值，模板指标中不存在的属性会忽略。如果传入多个 metrics，要修改的属性信息会分别应用于每个 metric。
可以简单理解为把每个模板指标都复制一份，然后修改其已存在的 property 信息。
请求路径： /openapi/v3/apps/<app_id>/metrics/create-from-templates
请求方法： POST
请求参数

metric字段说明

property字段说明

返回值

object字段说明

curl --location --request POST '{host}/datatester/openapi/v3/apps/253047/metrics/create-from-template' \
--header 'Content-Type: application/json' \
--data-raw '{
    "metrics": [
        {
            "metric_id": 33487,
            "name": "测试一下事件指标5",
            "description": "这是一个description"
        },
        {
            "metric_id": 33488,
            "name": "测试一下事件指标6",
            "description": "这是一个description"
        }
    ],
    "properties": [
        {
            "property_name": "app_channel",
            "property_values": [
                "channel3",
                "channel4"
            ]
        },
        {
            "property_name": "account_id",
            "property_values": [
                "1234556",
                "7654321"
            ]
        }
    ]
}'

删除指标 #

说明： 删除指定的指标。如果指标有已经关联的实验，则无法删除
请求路径: /openapi/v3/apps/<app_id>/metrics/<metric_id>
请求方法: DELETE
返回值

获取指标详情 #

说明： 获取指定指标的详情数据
请求路径： /openapi/v3/apps/<app_id>/metrics/<metric_id>
请求方法: GET
返回值

指标信息说明

metric_group结构说明

获取指标列表 #

说明： 分页获取APP下的指标列表
请求路径：/openapi/v3/apps/<app_id>/metrics
请求方法：GET
URL查询参数

返回值

指标信息说明

全量修改指标信息 #

说明： 全量修改指标的信息，DSL暂时无法修改，只可以修改名称、描述和数据类型
请求路径： /openapi/v3/apps/<app_id>/metrics/<metric_id>
请求方法: PUT
请求体

返回值

修改指标状态 #

说明： 修改指标的状态（上线、下线）。JAVA SDK暂不支持此接口
请求路径： /openapi/v3/apps/<app_id>/metrics/<metric_id>
请求方法: PATCH
请求体

返回值

获取互斥组列表 #

说明： 分页获取APP下互斥组的列表
请求路径： /openapi/v3/apps/<app_id>/layers
请求方法: GET
URL查询参数

返回值

互斥组信息说明

新建互斥组 #

说明： 创建一个新的互斥组
请求路径： /openapi/v3/apps/<app_id>/layers
请求方法: POST
请求参数

返回值

获取实验报告-分组结论概览 #

说明：用于获取实验报告分组结论概览。
请求路径 : /openapi/v3/apps/<app_id>/experiments/<experiment_id>/summary-data
请求方法: GET
返回值

报告数据结构说明

summary_infos结构说明

返回示例

{
    "code": 200,
    "data": {
        "summary_infos": [
            {
                "major_metric_name": "any转化率",
                "summary": [
                    {
                        "vid": 339601,
                        "version_name": "8b4b2cfdbd73941123bce96f9ce541e2",
                        "confidence": 3,
                        "conf_interval": [
                            -0.08904,
                            0.08904
                        ],
                        "p": 1.0
                    }
                ]
            }
        ],
        "user_data": {
            "339600": 799,
            "339601": 799
        },
        "start_ts": 1708822800,
        "end_ts": 1713801599,
        "report_type": "day"
    },
    "message": "success"
}

获取实验报告-核心指标概览 #

说明：用于获取实验报告分组结论概览
请求路径 : /openapi/v3/apps/<app_id>/experiments/<experiment_id>/metric-data
请求方法: POST
请求参数

返回值

报告数据结构说明

版本信息结构说明

返回示例

{
    "code": 200,
    "data": {
        "available_start_ts": 1708822800,
        "available_end_ts": 1713801599,
        "start_ts": 1708822800,
        "end_ts": 1713801599,
        "versions": [
            {
                "id": "339600",
                "name": "版本1",
                "config": {
                    "0304": "111"
                },
                "type": 0,
                "weight": 0,
                "disabled": false
            },
            {
                "id": "339601",
                "name": "版本2",
                "config": {
                    "0304": "222"
                },
                "type": 1,
                "weight": 0,
                "disabled": false
            }
        ],
        "confidence_level": 80,
        "metric_id": 99196,
        "distribution": {
            "339600": {
                "339601": {
                    "p": 1.0,
                    "m": 0.3416771,
                    "change": 0.0,
                    "change_rate": 0.0,
                    "conf_interval": [
                        -0.08904,
                        0.08904
                    ],
                    "half_interval": 0.0890367,
                    "confidence": 3,
                    "mean": {
                        "339600": 0.3416771,
                        "339601": 0.3416771
                    },
                    "variance": {
                        "339600": 0.00028152,
                        "339601": 0.00028152
                    },
                    "mde": 0.14750037,
                    "sample_size": {
                        "339600": 799,
                        "339601": 799
                    },
                    "details": {
                        "numerator": 273,
                        "denominator": 799
                    }
                }
            },
            "339601": {
                "339600": {
                    "p": 0,
                    "m": 0.3416771,
                    "change": 0,
                    "change_rate": 0,
                    "conf_interval": [
                        0,
                        0
                    ],
                    "half_interval": 0,
                    "confidence": 3,
                    "mean": {
                        "339601": 0,
                        "339600": 0
                    },
                    "variance": {
                        "339601": 0,
                        "339600": 0
                    },
                    "details": {
                        "numerator": 273,
                        "denominator": 799
                    }
                }
            }
        },
        "daily_data": {
            "2024-03-04": {
                "339600": {
                    "339601": {
                        "p": 1.0,
                        "m": 0.3416771,
                        "change": 0.0,
                        "change_rate": 0.0,
                        "conf_interval": [
                            -0.08904,
                            0.08904
                        ],
                        "half_interval": 0.0890367,
                        "confidence": 3,
                        "mean": {
                            "339600": 0,
                            "339601": 0
                        },
                        "variance": {
                            "339600": 0,
                            "339601": 0
                        },
                        "mde": 0.14750037,
                        "details": {
                            "numerator": 273,
                            "denominator": 799
                        }
                    }
                },
                "339601": {
                    "339600": {
                        "p": 0,
                        "m": 0.3416771,
                        "change": 0,
                        "change_rate": 0,
                        "conf_interval": [
                            0,
                            0
                        ],
                        "half_interval": 0,
                        "confidence": 3,
                        "mean": {
                            "339601": 0,
                            "339600": 0
                        },
                        "variance": {
                            "339601": 0,
                            "339600": 0
                        },
                        "details": {
                            "numerator": 273,
                            "denominator": 799
                        }
                    }
                }
            }
        },
        "boxplot": "The current indicator does not support box plots. Please refer to the explanation below for the specific reason.",
        "user_data": {
            "339600": 799,
            "339601": 799
        }
    },
    "message": "success"
}

五. 业务错误码说明 #

返回消息体里的code详细的定义