开放接口V3

本文档提供「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("中文关键字");

创建实验

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

version结构说明

layer_info结构说明

mab_info结构说明

返回值

获取实验详情

说明： 根据实验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>/experiments/<experiment_id>/launch
请求方法： PUT
返回值

结束实验

说明： 结束指定实验
请求路径 : /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
返回值

指标信息说明

获取指标列表

说明： 分页获取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>/metric_report
请求方法: POST
请求参数

返回值

报告数据说明

版本信息说明

指标信息说明

指标数据说明

{
    "calculation_results": {
        "100001": { // 指标ID
            "8000": { // 版本ID
                "8001": { // 以8000为对照版本， 8001版本的数据
                    "m": 1.001, // 8001指标值
                    "change": 0.05, // 变化值，即8001版本比8000版本指标值高了0.05
                    "change_rate": 0.01, // 变化率，即8001版本比8000版本指标值高了 1%
                    "conf_interval": [0.012, 0.541], // 置信区间
                    "details": { // 指标值的分子和分母值
                        "numerator": 302,
                        "denominator": 1567
                    },
                    "half_interval": 0.355, // 置信区间中点
                    "mde": 0.1234, // MDE值
                    "p": 0.00214, // P值
                    "sample_size": { // 样本量
                        "8000": 521,
                        "8001": 421
                    },
                    "variance": { // 方差
                        "8000": 0.0001,
                        "8001": 0.0234
                    },
                    "mean": { // 均值
                        "8000": 124,
                        "8001": 123
                    }
                }
            }
        },
        "100002": {
            // ...
        }
    }
}

用户信息查询

**说明：**用于查询用户信息（用户ID、用户名）。
路径: /datatester/openapi/v3/orgs/{org_id}/users
请求方法: GET
请求参数

返回值

data信息

用户信息字段

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