开放接口

本文档提供「A/B测试」应用中开放接口的说明。

可用范围包括：

• 实验信息：实验配置、实验过滤参数
• 报告信息：实验指标报告、实验留存报告
• 实验操作：创建实验、修改实验状态
• 其他：指标列表、互斥组列表

为了保证您和用户的数据安全，开放接口权限默认是关闭的。

在开始使用之前，您需要联系我们开通。（您可以通过服务对接的飞书/微信群或页面右下角的在线客服与我们取得联系）

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

SDK接入

实验数据的导出需要接入openapi的相关sdk，我们提供了Python SDK和Java SDK，SDK下载地址：

SDK下载。

Python SDK下载完成后在shell中执行命令完成安装

# 需要 python 2.7
easy_install rangersdk-0.0.1-py2.7.egg

调用示例

from rangersdk.client import RangersClient
import ujson

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

# Get Method Example
def test1():
    params = {'{key}': '{value}'} # 参数，选填
    resp = bc.data_tester('/openapi/v1/164287/details', params=params, method='get') # get请求方法
    print(resp.content) # 打印返回结果
    res = resp.json() # 将结果转化为json格式
    self.assertEqual(200, res['code'], 'err message: {}'.format(res['message']))

# Post Method Example
def test2():
    params = {'{key}': '{value}'} # 参数，选填
    resp = bc.data_tester('/openapi/v1/openapi-test', body=ujson.dumps(params), method='post') # post请求方法
    print(resp.content) # 打印返回结果
    res = resp.json() # 将结果转化为json格式
    self.assertEqual(200, res['code'], 'err message: {}'.format(res['message']))

获取实验配置

接口描述：获取实验相关配置的基础信息

请求路径：/openapi/v1/apps/<app_id>/experiment/<experiment_id>/details

请求方式：GET

请求所需参数：

接口返回值：

data信息：

接口返回示例：

{
  'code'：200
  "data": {
    "id": 3799, # 实验ID
    "name": "实时指标报告测试", # 实验名称
    "start_ts": "2020-07-08 11:39:02", # 实验开始时间
    "end_ts": "2021-07-08 11:39:02", # 实验结束时间
    "owner": "203870", # 创建者
    "description": "", # 实验描述
    "status": 1, # 实验状态，0:已结束 1:进行中 2: 待调度 3:测试中 4:草稿中
    "type": "client", # 实验类型，client:客户端 server:服务端
    "mode": 1, # 实验模式，1:编程实验 2:多链接实验 3:客户端实验
    "layer": { # 实验层
      "name": "互斥组1", # 互斥层名称
      "status": 1, # 互斥层状态，0:已关闭 1:已开启
       "description": "LS的测试场景五实验时创建时默认层", # 互斥层描述
       "type": "NULL" # 互斥层类型，default: mutex: NULL: 
    },
    "version_resource": 1.0, # 流量分配
    "versions": [
      {
        "id": 8572, # 版本ID
        "name": "对照版本", # 版本名称
        "type": 0, # 版本类型，0:对照版本 1:实验版本
        "config": { # 版本配置
          "hello12341": false
        },
        "description": "", # 版本描述
        "weight": 30 # 版本权重
      },
      ...
    ],
    "metrics": [
      {
        "id": 10065, # 指标ID
        "name": "测试指标", # 指标名称
        "metric_description": "测试指标描述", # 指标描述
        "type": "major", # 指标类型，major:核心 normal:普通
        "support_conf": true, # 是否可计算置信度
        "offline": false, # 是否离线指标
        "dsl": {
          "queries": [ # 事件详情
            {
              "show_label": "A",
              "event_type": "origin", # 事件类型
              "show_name": "活跃均次（pv/au）", # 事件属性
              "event_name": "predefine_pageview", # 事件名称
              "filters": [ # 事件过滤条件
                {
                  "property_operation": "!=", # 过滤操作符
                  "property_type": "event_param", # 过滤条件的类型
                  "property_name": "title", # 过滤条件的名称
                  "property_values": [ # 过滤条件的值
                    "这是一个title"
                  ]
                }
              ],
            },
            ...
          ]，
          "event_relation": "A*1" #  混合指标的关系
        },
        "composed": false # 是否是组合指标
      },
    ],
    "features": {
      "id": -1, # 关联feature的ID，无则-1
      "name": "",
      "key": ""
    },
    "filter": "", # 用户过滤条件
    "whitelist": [ # 各实验白名单
      {
        "对照版本": [
          {
            "ssids": ["bbc33321-4352-4b95-91d1-lishanlishanlishan"], # 用户ssid
            "id": 81, # 白名单ID
            "is_deleted": false,
            "name": "李珊", # 创建者
            "description": "", # 白名单描述
            "tags": [] # 白名单tag
          }，
        ]
      },
    ],
  }
  'message'：'success'
}

获取实验过滤参数

接口描述：获取过滤实验报告的参数，使用该接口返回的参数对实验报告与实验留存进行筛选

请求路径：/openapi/v1/apps/<app_id>/filters

请求方式：GET

请求所需参数：

接口返回值：

data信息：

filter_rule信息：

接口返回示例：

{
  "code": 200
  "data": {
    'filter_rule': [ # 过滤参数 
      {
        "key": "referrer", # 过滤参数key
        "label": "前向地址",  # 过滤参数名称
        "type": "string", # 参数类型
        "preset": 1, # 是否为默认参数
        "values": [
          {
            'value': 'https://www.sogou.com/web?query=xxxx' # value值
            'label': 'https://www.sogou.com/web?query=xxxx' # value名称
          },
          ...
        ],
        'mode': 'multiple', # 过滤参数的模式，填空:input 枚举:select 混合:multiple
        'operators': [ # 过滤参数操作方式
          {
            "label": "≠", # 操作符
            "value": "ne", # 操作代码
            "desc": null, # 操作描述
            "mode": "select" # 操作的输入方式，填空:input 枚举:select
          }
        ]
      },
      ...
    ]
  },
  'message': 'success'
}

过滤参数使用方式：

fliters = [
  {
    'type': 'string',
    'op': 'ne',
    'key': 'app_channel',
    'value': '23' / ['a', 'b'] # 单值/多值筛选
  },
  ...
]

计算实验指标

接口描述：计算并返回实验指标报告

请求路径：/openapi/v1/apps/<app_id>/experiment/<experiment_id>/metrics

请求方式：GET

请求所需参数：

接口返回值：

data信息：

接口返回示例：

{
  "code": 200,
  "data": {
    "report_type": "day", # 报告类型，day:天 hour:小时 five_minute:5分钟
    "versions": [
      {
        "id": 8572, # 版本ID
        "name": "对照版本", # 版本名称
        "config": {
          "hello12341": false
        },
        "type": 0, # 版本类型，0:对照版本 1:实验版本        
        "weight": 0  # 版本权重
      },
    ],
    "metrics": [
      {
        "id": 10065,
        "name": "测试指标",
        "metric_description": "测试指标描述",
        "type": "major", # 指标类型，major:核心 normal:普通
        "support_conf": true,
        "offline": false,
        "composed": false
      },
      ...
    ],
    "start_ts": 1594179542, # 实验开始时间
    "end_ts": 1597247999, # 实验结束时间
    "user_data": {
      "8572": 415248, # 实验总进组人数
      "8573": 415261
    },
    "calculation_results": {
      "10013": { # 指标ID
        "8572": { # 实验版本ID，以下类似数字代表该实验相对于另一实验计算得出的值
          "m": 1.367, # 
          "p": {
            "8573": -1 # -1为不存在，小于0.05则置信
          },
          "change": 0.09640731971910832, # 变化值
          "change_rate": {
            "8573": -0.00053 # 变化率
          },
          "conf_interval": {
            "8573": [0,0] # 置信区间
          },
          "half_interval": {
            "8573": 0 # 置信区间中点
          },
          "confidence": {
            "8573": 3 # 置信情况，1:正向 2:负向 3:不置信 4:新开实验 
                      # 5:数据待更新 6:置信度无法计算 7:没有用户进组 8:已暂停
          }，
          "mde": 0.012623757553642818 # 最小观测差值MDE(minimum detectable effect)
        },
        ...
      },
      ...    
    }
  },
  "message": "success"
}

计算实验留存

接口描述：计算并返回实验指标报告

请求路径：/openapi/v1/apps/<appid>/experiment/<experiment_id>/retention

请求方式：GET

请求所需参数：

接口返回值：

data信息：

接口返回示例：

{
  "code": 200
  "data": {
    "available_start_ts": 1594137600, # 实验开始时间
    "available_end_ts": 1597247999, # 实验结束时间
    "start_ts": 1594656000, # 开始时间
    "end_ts": 1597247999, # 结束时间
    "versions": [
      {
        "id": 8572, # 版本ID
        "name": "对照版本", # 版本名称
        "config": {
          "hello12341": false
        },
        "type": 0, # 版本类型
        "weight": 0 # 版本权重
      },
    ],
    "confidence_level": 90, # 置信度
    "calculation_details": { # 留存每日数据
      '当日进组用户': { # 
        '8672': [ # 实验ID
          [
            1597161600, # 日期（时间戳）
            5, # 留存率，-1表示不存在，“当日进组用户”时该值等于新进组人数
            5.0 # 新进组人数，-1表示不存在
          ],
          ...
        ],
        ...  
      },
      ...
    }，
    'calculation_results': { # 留存统计数据
      "次日留存": {
        "data": { # 留存率
          "8572": 0.0022,
          "8573": 0.0022
        },
        "confidence": { # 置信情况，1:正向 2:负向 3:不置信 4:新开实验 
                        # 5:数据待更新 6:置信度无法计算 7:没有用户进组 8:已暂停
          "8572": {
            "8573": 0
          },
          "8573": {
            "8572": 0
          }
        },
        "p": { # p值
          "8572": {
            "8573": 0.998318
          },
          "8573": {
            "8572": 0.998318
          }
        },
        "half_interval": { # 置信区间中点
          "8572": {
            "8573": 0.17499327964828007
          },
          "8573": {
            "8572": 0.17504366124523396
          }
        },
        "change_rate": { # 变化率
          "8572": {
            "8573": -0.000288
          },
          "8573": {
            "8572": 0.000288
          }
        },
        "conf_interval": { # 置信区间
          "8572": {
            "8573": [
              -0.175281,
              0.174705
            ]
          },
          "8573": {
            "8572": [
              -0.174756,
              0.175332
            ]
          }
        },
        "nums": { # 当日总计新进组人数
          "8572": 107,
          "8573": 107
        }
      },
    }
  },
  'message': 'success'
}

创建实验

接口描述：创建实验

请求路径：/openapi/v2/apps/<app_id>/experiments

方法: POST

请求所需参数：

version结构：

layer_info结构：

接口返回值：

接口请求参数示例：

{
    "name":"测试实验2022041901",
    "mode": 1,
    "endpoint_type": 1,
    "duration": 20,
    "major_metric": 29806,
    "metrics": [29806],
    "versions": [
        {
            "type": 0,
            "name": "实验组2022041901",
            "config": {"shiyu_key": "hello"}
        },
        {
            "type": 1,
            "name": "对照组2022041901",
            "config": {"shiyu_key": "world"}
        }
    ],
    "layer_info": {
        "layer_id": -1,
        "version_resource": 0.7
    }
}

修改实验状态

接口描述：实验开启、结束状态操作

请求路径:

• 开始实验：/openapi/v2/apps/<app_id>/experiments/<experiment_id>/launch/
• 结束实验：/openapi/v2/apps/<app_id>/experiments/<experiment_id>/stop/

请求方式: PUT

请求所需参数：

获取指标列表

接口描述：获取当前APP下所有指标信息

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

请求方式: GET

接口请求参数：

接口返回信息：

data信息：

page结构：

metric结构：

获取互斥组列表

接口描述：获取当前APP下所有层信息(互斥组)

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

请求方式: GET

接口请求参数：

接口返回值：

data信息：

HTTP状态码约束如下：

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