You need to enable JavaScript to run this app.
导航

开放接口V3

最近更新时间2023.09.06 10:37:10

首次发布时间2022.08.17 15:51:53

一. 概述

本文档提供「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

请求参数

参数名称参数类型是否必填描述备注
namestring实验名称不能与当前APP下已有实验重名,长度限制50字符
descriptionstring实验描述长度限制1000字符
endpoint_typeint实验类型0-客户端实验,1-服务端实验
durationint实验时长单位天,范围:[1, 365]
major_metricint核心指标ID必须在metrics中
metricsint[]关注的指标ID列表必须包含major_metric
versionsobject[]实验版本配置数组长度要大于等于2,详见version结构说明
layer_infoobject实验层配置详见layer_info说明

version结构说明

参数名称参数类型是否必填描述备注
typeint对照版本/实验版本0-对照版本,1-实验版本 versions数组中只能有一个对照版本
namestring版本名称长度50字符
descriptionstring版本描述长度1000字符
weightfloat实验版本的流量分配范围[0.001, 1] 0.1% ~ 100%
versions数组中不传,则默认均匀分配 如果传,则会校验所有weight的和是否为1
configobject版本配置version数组中所有config的key需要保持一致 { "key1": "value1", "key2": "value2" }
usersstring[]白名单用户不同版本的白名单用户不能有交集

layer_info结构说明

参数名称参数类型是否必填描述备注
layer_idint互斥组ID使用的实验层,使用默认层则传-1或不传
如果指定了layer_id,则会校验实验层上可用流量是否满足实验配置
version_resourcefloat实验流量占比范围[0.001, 1],最小精度千分之一

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataint新创建实验ID

获取实验详情

说明: 根据实验ID获取实验详情

请求路径:/openapi/v3/apps/{app_id}/experiments/{experiment_id}

请求方法:GET

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataobject接口返回的实验信息

data信息

参数名称类型说明
experimentobject实验信息

experiment结构说明

参数名称类型说明
idint实验的experiment_id
namestring实验名称
launch_start_timelong实验开始时间,Unix时间戳
end_timelong实验结束时间,Unix时间戳
create_timelong实验创建时间,Unix时间戳
modify_timelong实验修改时间,Unix时间戳
test_start_timelong实验调试开始时间,Unix时间戳
durationlong实验运行时间,单位秒
confidence_levelint置信度水平,95代表置信度水平为95%
version_resourcefloat实验所占流量,范围[0.001, 1],1为100%
layer_idint实验层id
freeze_statusint实验冻结状态 1-冻结,0-没冻结
freeze_timelong实验冻结时间,Unix时间戳(只有冻结状态为1时才有效)
version_freeze_statusint是否进组不出组 1-是 0-否
pause_statusint实验是否暂停 1-暂停 0-不暂停
endpoint_typeint0-客户端实验,1-服务端实验
versionsobject[]实验版本信息
metricsobject[]实验关注指标信息
statusint/enum实验状态, 0:已结束 1:运行中 2: 待调度 3:调试中
filtersstring实验受众目标,json字符串
descriptionstring实验描述

metric结构说明

参数名称类型说明
idint指标id
namestring指标名称
descriptionstring指标描述
is_primaryint是否核心指标:0-否 1-是
calculate_typestring指标计算类型
dslobject指标dsl
statusint指标状态 0: 已下线 1:没下线
is_composedboolean是否组合指标:true/false
data_typestring指标展现数值格式

version结构说明

参数名称类型说明
idint版本id
typeint版本类型:0-对照版本,1-实验版本
namestring版本名称
descriptionstring版本描述
configobject版本配置 { "key1": "value1", "key2": "value2" }
weightint版本权重,和为1000,1代表0.1% 为0则为均匀分配
user_liststring[]白名单列表

获取实验列表

说明: 分页获取APP下的实验列表

注意:如果搜索关键字keyword包含中文,则需要先进行url转义,再进行调用

请求路径:/openapi/v3/apps/<app_id>/experiments

请求方法:GET

URL查询参数

参数类型说明
statusint实验状态,0-已结束,1-运行中,3-测试中;不传则默认所有状态
pageint分页参数,1表示第一页,不传默认为1
page_sizeint每页数量,不传默认99
keywordstring搜索关键字,当前支持按照实验name和description模糊搜索
sort_bystring排序规则。当前仅支持 end_time结束时间、launch_start_time实验启动时间、test_start_time测试开始时间; 不传默认实验创建时间
sort_orderstring排序顺序。desc/asc。不传默认desc降序

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataobject{
"experiments": [],
"page": {
"current_page": 1, // 当前页
"total_pages": 0, // 总页数
"total_items": 0 // 总条目数
}
}

experiments结构说明

参数名称类型说明
idint实验ID
namestring实验名称
end_timelong实验结束时间,Unix时间戳
test_start_timelong实验调试开始时间,Unix时间戳
launch_start_timelong实验开始时间,Unix时间戳
durationlong实验运行时间,单位秒
version_resourcefloat实验所占流量,范围[0.001, 1],1为100%
layer_idint实验层id
freeze_statusint实验冻结状态 1-冻结,0-没冻结
freeze_timelong实验冻结时间,Unix时间戳(只有冻结状态为1时才有效)
version_freeze_statusint是否进组不出组 1-是 0-否
pause_statusint实验是否暂停 1-暂停 0-不暂停
endpoint_typeint0-客户端实验,1-服务端实验
descriptionstring实验描述
statusint/enum实验状态, 0:已结束 1:运行中 2: 待调度 3:调试中
owner字符串实验创建人
versionsobject[]实验版本信息

修改实验信息

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

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

注意:由于使用的网络库本身不支持不支持PATCH方法,因此Java SDK暂不支持PATCH方法

请求路径:/openapi/v3/apps/{app_id}/experiments/<experiment_id>

请求方法:PUT/PATCH

请求参数

参数名称参数类型是否必须描述备注
namestring实验名称不能与已有实验重名,长度50字符
descriptionstring实验描述长度1000字符
durationint实验时长单位天,[1, 365],整数
major_metricint核心指标 ID运行中不可修改 测试中可以修改
metricsint[]指标ID列表
versionsobject[]实验版本version数量不可变动,只可以修改version内容
layer_infoobject互斥组

version结构

参数名称参数类型是否必填描述备注
idint版本ID修改version信息必填
namestring版本名称长度50字符
descriptionstring版本描述长度1000字符
weightfloat流量分配范围[0.001, 1] 0.1% ~ 100%
versions数组中不传,则默认均匀分配
如果传,则会校验所有weight的和是否为1
configobject版本参数不同版本的 key
需要保持一致
version数组中所有config的key需要保持一致
{ "key1": "value1", "key2": "value2" }
usersstring[]白名单用户

layer_info结构

参数名称参数类型是否必填描述备注
layer_idint互斥组 ID
version_resourcefloat占用流量百分比范围[0.001, 1],最小精度千分之一

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataobject实验ID

开始实验

说明: 开始一个测试中的实验。使其状态变为运行中。

请求路径: /openapi/v3/apps/<app_id>/experiments/<experiment_id>/launch

请求方法: PUT

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataobject实验ID

结束实验

说明: 结束指定实验

请求路径 : /openapi/v3/apps/<app_id>/experiments/<experiment_id>/stop

请求方法: PUT

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataobject实验ID

创建指标

说明: 创建一个A/B测试指标

请求路径: /openapi/v3/apps/<app_id>/metrics

请求方法:POST

请求参数

参数名称类型是否必须描述备注
namestring指标名称长度限制 50,不可与相同APP下其他指标重复
descriptionstring指标描述长度限制 1000
dslobject指标DSLdsl详情可咨询对接人员
composedboolean是否是组合指标true/false
data_typestring数据展示类型枚举值
number_0, number_1, number_2, number_3, number_4, number_5,
percent_0, percent_1, percent_2, percent_3, percent_4, percent_5
默认为percent_4,即百分数四位小数

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataint指标ID

基于指标模板创建指标

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

参数名称类型是否必须描述备注
metricslist[metric]指标信息列表metric 见下表说明
propertieslist[property]需要修改的属性信息property 见下表说明

metric字段说明

参数名称类型是否必须描述备注
metric_idint模板指标id已存在的指标id
namestring根据模板指标,新建指标的名称长度限制 50,不可与相同APP下其他指标重复
descriptionstring根据模板指标,新建指标的指标信息长度限制 1000

property字段说明

参数名称类型是否必须描述备注
property_namestring属性名称模板中不存在的属性名会直接忽略,不报错
property_valuesstring/int/float数组属性值长度限制255,如果为空,则是[];属性值类型需要与模板指标的属性类型保持一致。具体字段说明可参考 V3 DSL 字段详细说明

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
datalist[object]新创建的指标信息

object字段说明

参数名称类型说明
idint新创建的指标ID
namestring新创建的指标名称

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

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataint指标ID

获取指标详情

说明: 获取指定指标的详情数据

请求路径: /openapi/v3/apps/<app_id>/metrics/<metric_id>

请求方法: GET

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataobject指标信息 {"metric_info": }

指标信息说明

参数名称类型说明
idint指标ID
namestring指标名
descriptionstring描述
dslobject指标dsl
composedboolean是否是组合指标
statusint状态 0-下线 1-上线
is_support_majorboolean是否支持设置为核心指标

获取指标列表

说明: 分页获取APP下的指标列表

请求路径:/openapi/v3/apps/<app_id>/metrics

请求方法:GET

URL查询参数

参数类型说明
statusint指标状态,0-下线 1-上线,不传则默认所有状态
pageint分页参数,1表示第一页,不传默认为1
page_sizeint每页数量,不传默认99
keywordstring搜索关键字,当前支持按照指标name和description模糊搜索

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataobject{
"metrics": [],
"page": {
"current_page": 1, // 当前页
"total_pages": 0, // 总页数
"total_items": 0 // 总条目数
}
}

指标信息说明

参数名称类型说明
idint指标ID
namestring指标名
descriptionstring描述
dslobject指标dsl
composedboolean是否是组合指标
statusint状态 0-下线 1-上线
is_support_majorboolean是否支持设置为核心指标

全量修改指标信息

说明: 全量修改指标的信息,DSL暂时无法修改,只可以修改名称、描述和数据类型

请求路径: /openapi/v3/apps/<app_id>/metrics/<metric_id>

请求方法: PUT

请求体

参数名称类型是否必须描述备注
namestring指标名称最大长度50,不可重复
descriptionstring指标描述最大长度1000
data_typestring指标数据类型枚举值
number_0, number_1, number_2, number_3, number_4, number_5,
percent_0, percent_1, percent_2, percent_3, percent_4, percent_5
默认为percent_4,即百分数四位小数

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataint指标ID

修改指标状态

说明: 修改指标的状态(上线、下线)。JAVA SDK暂不支持此接口

请求路径: /openapi/v3/apps/<app_id>/metrics/<metric_id>

请求方法: PATCH

请求体

参数名称类型是否必须描述备注
statusint指标状态0-下线 1-上线

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataint指标ID

获取互斥组列表

说明: 分页获取APP下互斥组的列表

请求路径: /openapi/v3/apps/<app_id>/layers

请求方法: GET

URL查询参数

参数类型说明
keywordstring查询关键字,可以根据name和description模糊查询
endpoint_typeint互斥组的端类型。0-客户端层,1-服务端层
pageint查询页码。默认为1
page_sizeint每页数量,默认为99

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataobject{
"layers": [],
"page": {
"current_page": 1, // 当前页
"total_pages": 0, // 总页数
"total_items": 0 // 总条目数
}
}

互斥组信息说明

参数名称类型说明
idint互斥组ID
namestring互斥组名
descriptionstring描述
endpoint_typeint端类型,0-客户端层,1-服务端层
available_trafficint剩余流量,1000代表100%

新建互斥组

说明: 创建一个新的互斥组

请求路径: /openapi/v3/apps/<app_id>/layers

请求方法: POST

请求参数

参数名称类型是否必须说明
namestring互斥组名,长度限制50
descriptionstring描述,长度限制1000
endpoint_typeint端类型,0-客户端层,1-服务端层

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataint互斥组ID

获取实验报告基础数据

说明: 同步获取实验报告的基础数据

请求路径: /openapi/v3/apps/<app_id>/experiments/<experiment_id>/metric_report

请求方法: POST

请求参数

参数名称类型是否必须描述备注
report_typestring查询类型默认天级。当前仅支持 day:天级
start_tsint查询开始时间默认实验开始时间,不可以早于实验开始时间
end_tsint查询结束时间默认当前时间,不可以晚于实验结束时间

返回值

参数名称类型说明
codeint接口返回状态,200为成功
messagestring接口返回信息,成功时默认为success
dataobject报告数据

报告数据说明

参数名称参数类型描述
report_typestring报告类型:day:天级
versionsobject[]实验版本信息
metricsobject[]实验指标信息
start_tsint查询开始时间,UNIX时间戳
end_tsint查询结束时间,UNIX时间戳
user_dataobject各版本进组人数
calculation_resultsobject指标数据

版本信息说明

参数名称参数类型描述
idint版本ID
namestring版本名称
configobject版本配置信息
typeint0:对照版本 1:实验版本
weightint版本权重,0为均分

指标信息说明

参数名称参数类型描述
idint指标ID
namestring指标名称
metric_descriptionstring指标描述
typestringmajor-核心指标,normal-普通指标
support_confboolean是否支持计算置信度
offlineboolean是否在线
composedboolean是否是组合指标

指标数据说明

{
    "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": {
            // ...
        }
    }
}
五. 业务错误码说明

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

错误码含义
200成功
403对请求的资源(app、实验等)无权限
404请求的资源不存在,如查询了不存在的实验ID或指标ID
410请求的资源已被删除
40000缺少必填参数
40001参数值错误
40003对请求的接口无访问权限
40010调用过于频繁(超过每秒调用次数限制)
40011超过每天调用次数限制
60001DSL格式错误
60002指标有已关联实验,无法删除
60010流量不足,无法创建实验
60011实验的endpoint_type与所属互斥组不一致
60012测试中实验无法被结束
60013草稿态实验不可被openAPI查询或修改