saasapi/cmd.proto

syntax = "proto3";

package saasapi;

option go_package = "git.algo.com.cn/public/saasapi";

// SaasReq 命令请求
message SaasReq {
    oneof cmd {
        Info info                                = 5;   // 获取账号设置

        Read read                                = 10;  // 批量读取
        Write write                              = 11;  // 批量写入
        ColumnWrite column_write                 = 12;  // 全量列式写入

        Task task_create                         = 20;  // 任务创建
        TaskList task_list                       = 21;  // 列出任务
        TaskRun task_run                         = 22;  // 执行任务
        TaskDelete task_delete                   = 23;  // 删除任务
        TaskInfo task_info                       = 24;  // 任务详情

        TargetList target_list                   = 50;  // 列出策略及绑定
        TargetCreate target_create               = 51;  // 创建策略
        TargetDelete target_delete               = 52;  // 删除策略

        BindSet bind_set                         = 61;  // 设置绑定
        BindDelete bind_delete                   = 62;  // 解除绑定

        ScriptRun script_run                     = 90;  // 运行脚本
        ScriptCreate script_create               = 91;  // 脚本创建
        ScriptList script_list                   = 92;  // 列出脚本
        ScriptDelete script_delete               = 93;  // 删除脚本
        ScriptGet script_get                     = 94;  // 获取脚本内容
        ScriptUse script_use                     = 95;  // 使用脚本

        ExpList exp_list                         = 100; // 列出实验
        ExpGet exp_get                           = 101; // 获取实验报表
    }
}

// Info 获取账号信息
message Info {

}

// Read 批量读取命令
message Read {
    string dataspace_id                          = 1;   // 数据空间ID
    string appid                                 = 2;   // 小程序/小游戏/公众号/视频号的appid
    repeated ReadItem read_items                 = 3;   // 批量获取命令
}

// ReadItem 读取命令
message ReadItem {
    string userid                                = 1;   // 用户ID
}

// Write 批量写入命令
message Write {
    string dataspace_id                          = 1;   // 数据空间ID
    string appid                                 = 2;   // 小程序/小游戏/公众号/视频号的appid
    bool is_clear_all_first                      = 3;   // 是否先清空该用户所有数据
    repeated WriteItem write_items               = 4;   // 批量写入命令
}

// WriteItem 写入命令
message WriteItem {
    string userid                                = 1;   // 用户ID
    Bytes write_bytes                            = 2;   // byte区域
    Uint32s write_uint32s                        = 3;   // uint32区域
    FlagsWithExpire write_flags_with_expire      = 4;   // 标志位区域
}

// Bytes 写入byte区域
message Bytes {
    bytes bytes                                  = 1;   // 写入的byte
    uint64 index_1                               = 2;   // 写入byte的索引值(0..63)
}

// Uint32s 写入uint32区域
message Uint32s {
    repeated uint32 uint32s                      = 1;   // 写入的uint32
    uint64 index_1                               = 2;   // 写入uint32的索引值(0..7) 最多 8 个
}

// FlagsWithExpire 写入标志位区域
message FlagsWithExpire {
    repeated FlagWithExpire flags_with_expire    = 1;   // 写入的标志位
    uint64 index_1                               = 2;   // 写入标志位的索引值(0..3) 最多 4 个
}

// FlagWithExpire 标志位
message FlagWithExpire {
    bool flag                                    = 1;   // 标志位
    bool default_flag                            = 2;   // 默认值。超时后则回到默认值。
    uint32 expire                                = 3;   // 过期时间，为 0 则永不过期
}

// ColumnWrite 全量列式写入命令
message ColumnWrite {
    string dataspace_id                          = 1;   // 数据空间ID
    bool is_clear_all_first                      = 2;   // 是否先执行清空
    Bytes write_bytes                            = 3;   // byte区域
    Uint32s write_uint32s                        = 4;   // uint32区域
    FlagsWithExpire write_flags_with_expire      = 5;   // 标志位区域
}

message Task {
    string dataspace_id                          = 1;   // 数据空间ID
    string appid                                 = 2;   // 小程序/小游戏/公众号/视频号的appid
    string task_sha256                           = 3;   // 任务sha256
    string task_description                      = 4;   // 任务描述
    repeated FileInfo task_file_infos            = 5;   // 文件列表
    uint64 task_block_size                       = 6;   // 文件块字节大小（推荐50M）
    string source_path                           = 7;   // 任务数据源路径
    uint64 task_size                             = 8;   // 任务所有文件的总大小

    // 以下字段只在返回时填写，用于提供服务端的任务状态。在请求时填写会被忽略
    string create_time                           = 10;   // 创建时间
    string run_time                              = 11;   // 运行时间
    string finish_time                           = 12;   // 完成时间
    uint32 running_block                         = 13;   // 正在运行的块编号
    uint32 total_block                           = 14;   // 总块数

    TaskStatus status                            = 15;   // 任务状态
}

// TaskList 任务列表
message TaskList {
    TaskStatus status_filter                     = 1;   // 只显示指定状态的任务
}

// TaskRun 任务运行
message TaskRun {
    string task_sha256                           = 1;   // 任务sha256
}

// TaskDelete 取消任务
message TaskDelete {
    string task_sha256                           = 1;   // 任务sha256
}

// TaskInfo 任务详情
message TaskInfo {
    string task_sha256                           = 1;   // 任务sha256
}

// FileInfo 任务文件信息
message FileInfo {
    string file_name                             = 1;   // 文件名
    uint64 file_size                             = 2;   // 文件大小
    repeated FileBlock file_blocks               = 3;   // 文件块列表
}

// FileBlock 文件块信息
message FileBlock {
    string block_sha256                          = 1;   // 块的sha256
    uint64 block_length                          = 2;   // 块的字节长度
    bool uploaded                                = 3;   // 是否已上传（在TaskCreate/TaskInfo请求返回）
}

// TargetList 列出策略
message TargetList {
    repeated string targets                      = 1;   // 指定要列出的绑定的策略列表，如不指定则返回全部
    bool list_bind                               = 2;   // 是否同时列出绑定信息
}

// TargetCreate 创建策略
message TargetCreate {
    string target_id                             = 1;   // 策略ID
    string target_description                    = 2;   // 策略描述
}

// TargetDelete 删除策略
message TargetDelete {
    string target_id                             = 1;   // 策略ID
}

// BindSet 设置绑定
message BindSet {
    repeated Bind binds                          = 2;   // 设置绑定内容
}

// BindDelete 删除绑定
message BindDelete {
    repeated Bind binds                          = 2;   // 解除绑定内容
}

// ScriptRun 运行脚本
message ScriptRun {
    string lua_script                            = 1;   // 要调试的lua脚本
    string server_did                            = 2;   // 将从服务端读取该DID下的数据
    string appid                                 = 3;   // 小程序/小游戏/公众号/视频号的appid
    string server_openid                         = 4;   // 将从服务端读取该openid下的数据，需与appid配对使用
    OS os                                        = 5;   // 操作系统
}

// ScriptCreate 创建脚本
message ScriptCreate {
    string lua_name                              = 2;   // 要上传的脚本名称
    string lua_script                            = 1;   // 要调试的lua脚本
}

// ScriptList 列出脚本
message ScriptList {

}

// ScriptDelete 删除脚本
message ScriptDelete {
    string lua_name                              = 1;   // 要删除的脚本名称
}

// ScriptGet 获取脚本
message ScriptGet {
    string lua_name                              = 1;   // 要获取的脚本名称
}

// ScriptUse 使用脚本
message ScriptUse {
    string lua_name                              = 1;   // 要使用的脚本名称
}

// ExpList 列出实验
message ExpList {

}

// ExpGet 获取实验报表
// select base_fields, {EXT_FIELDS} 
// where day between {WHERE_BEGIN_DAY} and {WHERE_END_DAY} 
//    and expid in {WHERE_EXP_ID}
//    and target = {WHERE_TARGET}
//    and advertiser_id in {WHERE_ADVERTISER_ID}
// group by {GROUP_BY}
message ExpGet {
    repeated string ext_fields                   = 1;   // 扩展字段（除基础字段必然输出外，其余字段需在这里填写，也可以使用*输出全部扩展字段）
    uint64 where_begin_day                       = 10;  // 起始日期
    uint64 where_end_day                         = 11;  // 结束日期
    repeated uint32 where_bucket_id              = 12;  // 实验ID(1-10)
    string where_target                          = 13;  // 策略ID
    repeated uint64 where_advertiser_id          = 14;  // 广告主ID
    repeated string group_by                     = 20;  // 当前支持广告主ID(advertiser_id)
    uint32 total_flag                            = 30;  // 是否汇总，0=不汇总，1=汇总
}

// SaasRes 命令返回
message SaasRes {
    ErrorCode code                               = 1;  // 返回码
    string status                                = 2;  // 返回信息的文本提示
    oneof res {
        InfoRes info_res                         = 5;  // 账号信息返回

        ReadRes read_res                         = 10;  // 读取命令返回
        WriteRes write_res                       = 11;  // 写入命令返回

        Task task_create_res                     = 20;  // 创建任务返回状态
        TaskListRes task_list_res                = 21;  // 任务列表返回状态
        Task task_run_res                        = 22;  // 运行任务返回状态
        Task task_delete_res                     = 23;  // 删除任务返回状态
        Task task_info_res                       = 24;  // 任务详情返回状态

        TargetListRes target_list_res            = 50;  // 列出策略及绑定返回状态
        TargetCreateRes target_create_res        = 51;  // 创建策略返回状态
        TargetDeleteRes target_delete_res        = 52;  // 删除策略返回状态
    
        BindSetRes bind_set_res                  = 61;  // 设置绑定返回状态
        BindDeleteRes bind_delete_res            = 62;  // 删除绑定返回状态

        ScriptRunRes script_run_res              = 90;  // 运行脚本返回
        ScriptCreateRes script_create_res        = 91;  // 创建脚本返回
        ScriptListRes script_list_res            = 92;  // 列出脚本返回
        ScriptDeleteRes script_delete_res        = 93;  // 删除脚本返回
        ScriptGetRes script_get_res              = 94;  // 获取脚本返回
        ScriptUseRes script_use_res              = 95;  // 使用脚本返回

        ExpListRes exp_list_res                  = 100; // 实验列表返回
        ExpGetRes exp_get_res                    = 101; // 实验报表返回
    }
}

message DataSpace {
    repeated string did                          = 1;   // 设备ID区
    repeated string wuid                         = 2;   // OpenID区
}

// InfoRes 账号信息返回
message InfoRes {
    DataSpace dataspace                          = 1;  // 可用数据区列表
    repeated string target_id                    = 2;  // 策略ID列表

}

// ReadRes 读记录返回
message ReadRes {
    uint32 succ_cmd_count                        = 1;  // 成功的命令数量
    uint32 fail_cmd_count                        = 2;  // 失败的命令数量
    repeated ValueItem cmd_res                   = 3;  // 返回的命令
}

// WriteRes 写记录返回
message WriteRes {
    //uint32 succ_cmd_count                      = 1;  // 成功的命令数量
    //uint32 fail_cmd_count                      = 2;  // 失败的命令数量
    repeated string failed_userid                = 3;  // 返回的失败的用户ID
}

// ValueItem 读取命令返回内容
message ValueItem {
    uint32 cmd_index                             = 1;  // 命令索引
    CmdErrorCode cmd_code                        = 2;  // 状态
    bytes bytes                                  = 3;  // byte区域
    repeated uint32 uint32s                      = 4;  // uint32区域
    repeated FlagWithExpire flags_with_expire    = 5;  // 标志位区域
    uint32 last_modify_time                      = 6;  // 最后修改时间
    uint32 version                               = 7;  // 存储版本
}

// TaskListRes 任务列表返回
message TaskListRes {
    repeated Task tasks                          = 1;  // 任务列表
}

// TargetListRes 策略列表返回
message TargetListRes {
    map<string, Binds> target_list               = 1;  // 绑定列表
}

// TargetCreateRes 策略创建返回
message TargetCreateRes {
    string target_id                             = 1;  // 策略ID
    string target_description                    = 2;  // 策略描述
}

// TargetDeleteRes 策略创建返回
message TargetDeleteRes {
    string target_id                             = 1;  // 策略ID
    string target_description                    = 2;  // 策略描述
}

message Binds {
    repeated Bind binds                          = 1;  // 绑定列表
}

// Bind 绑定信息
message Bind {
    int64 bind_id                                = 1;  // 绑定的ID
    BindType bind_type                           = 2;  // 绑定类型
    string target_id                             = 3;  // 策略ID
    int64 account_id                             = 4;  // 广告主ID
    BindSourceType bind_source                   = 5;  // 绑定操作来源
}


// BindType 绑定类型
enum BindType {
    UnknownBindType                              = 0;
    AdgroupId                                    = 1;  // 广告
    AccountId                                    = 3;  // 广告主
}

// BindSourceType 绑定操作来源
enum BindSourceType {
    DefaultBindSourceType                        = 0;  // 广告主或未填写
    ThirdPartyApi                                = 1;  // 第三方API
    ADQ                                          = 2;  // ADQ平台
    MP                                           = 3;  // MP平台
    MktApi                                       = 4;  // MarketingAPI
}

// BindSetRes 设置绑定返回
message BindSetRes {
    int32 success_num                            = 1;  // 成功数
    int32 error_num                              = 2;  // 错误数
    repeated BindError errors                    = 3;  // 绑定错误的记录
}

// BindDeleteRes 删除绑定返回
message BindDeleteRes {
    int32 success_num                            = 1;  // 成功数
    int32 error_num                              = 2;  // 错误数
    repeated BindError errors                    = 3;  // 绑定错误的记录
}

// BindError 绑定错误信息
message BindError {
    int64 bind_id                                = 1;  // 错误绑定的绑定ID
    int32 bind_type                              = 2;  // 绑定类型
    string reason                                = 3;  // 错误绑定原因
}


// ScriptRunRes 运行脚本返回
message ScriptRunRes {
    string print_output                           = 1;  // print输出
    string error_output                           = 2;  // 错误信息
    string targets_output                         = 3;  // 策略输出
    string dataspace_out                          = 4;  // 数据区输出
}

message ScriptInfo {
    string lua_name                              = 1;  // 脚本名称
    string lua_script                            = 2;  // 脚本内容
    bool lua_checked                             = 3;  // 脚本校验结果
    bool lua_used                                = 4;  // 脚本是否被使用
}

// ScriptCreateRes 创建脚本返回
message ScriptCreateRes {
    ScriptInfo script_info                        = 1;  // 脚本信息
}

// ScriptListRes 脚本列表返回
message ScriptListRes {
    repeated ScriptInfo script_info              = 1;  // 脚本信息
}

// ScriptGetRes 获取脚本返回
message ScriptGetRes {
    ScriptInfo script_info                      = 1;  // 脚本信息
}

// ScriptDeleteRes 删除脚本返回
message ScriptDeleteRes {
    ScriptInfo script_info                      = 1;  // 脚本信息
}

// ScriptUseRes 使用脚本返回
message ScriptUseRes {
    ScriptInfo script_info                      = 1;  // 脚本信息
}

// ExpListRes 实验列表返回
message ExpListRes {
    repeated ExpBucket buckets                    = 1;  // 实验桶
}

message ExpBucket {
    uint32 bucket_id                              = 1;  // 分桶号
    uint32 pt_exp_id                              = 2;  // 平台实验ID
    uint32 percent                                = 3;  // 流量百分比
}

// ExpGetRes 实验报表返回
message ExpGetRes {
    repeated ExpData exp_data                      = 1;  // 实验数据
}

message ExpData {
    uint64 time                                    = 1;  // 日期
    uint32 bucket_id                               = 2;  // 分桶ID
    ExpBaseFields base_fields                      = 3;  // 基础字段
    map <string, double> ext_fields                = 4;  // 扩展字段
    map<string, uint64> group                      = 5;  // 分组
}

message ExpBaseFields {
    double cost                                   = 1;  // 花费
    int64 exposure                                = 2;  // 曝光量
    int64 click                                   = 3;  // 点击量
    double cpm                                    = 4;  // 千次曝光价格
    double cpc                                    = 5;  // 单次点击价格
    double cpa                                    = 6;  // 单次转化成本
    double ctr                                    = 7;  // 点击率
    double cvr                                    = 8;  // 浅层转化率
    double cvr_second                             = 9;  // 深层转化率
    int64 conversion                              = 10; // 浅层转化量
    int64 conversion_second                       = 11; // 深层转化量
}

// ErrorCode 返回码
enum ErrorCode {
    SUCC                                         = 0;   // 成功
    INVALID_ACCOUNT                              = 101; // Account不合法
    INVALID_TIMESTAMP                            = 102; // 头信息缺少时间戳或不正确
    INVALID_SIGNATURE                            = 103; // 头信息缺少签名
    AUTH_FAIL                                    = 104; // 签名校验失败
    DISABLED_ACCOUNT                             = 105; // 账号已禁用
    INVALID_CONTENT_TYPE                         = 110; // 非法的Content-Type
    READ_BODY                                    = 111; // 读取 http body 失败
    DECODE_BODY                                  = 112; // 解码 body 失败
    QPS_LIMIT                                    = 113; // 并发请求量超限
    CMDS_LIMIT                                   = 114; // 命令数量超限
    CMDS_NULL                                    = 115; // 命令为空
    DATASPACE_NOT_EXISTS                         = 116; // 数据空间不存在

    TASK_EXISTS                                  = 120; // 任务已存在
    TASK_IS_NOT_EXISTS                           = 121; // 任务不存在
    TASK_NUM_LIMIT                               = 122; // 任务数达到上限
    TASK_BLOCK_SIZE                              = 123; // 块大小超限
    TASK_TOTAL_SIZE                              = 124; // 总文件大小超限
    TASK_MARSHAL                                 = 125; // 序列化

    TASK_IS_WATING                               = 130; // 任务未上传完毕
    TASK_IS_RUNNING                              = 131; // 任务已经在运行
    TASK_FAILED                                  = 132; // 任务已失败
    TASK_FINISHED                                = 133; // 任务已完成
 

    DATA_ERROR                                   = 201; // 数据错误
    CMD_ERROR                                    = 202; // 命令行执行错误

    API_ERROR                                    = 301; // 调用内部API错误

    TARGET_ERROR                                 = 401; // Target参数错误
}

enum CmdErrorCode {
    OK                                           = 0;   // 成功
}

// TaskStatus 任务状态
enum TaskStatus {
    ALL                                          = 0;   // 全部
    WAITING                                      = 1;   // 等待中
    READY                                        = 2;   // 上传完毕
    RUNNING                                      = 3;   // 运行中
    SUCCESS                                      = 4;   // 成功
    FAIL                                         = 5;   // 失败

    DELETED                                      = 10;  // 已删除，仅在执行删除成功时返回
}

enum OS {
    OS_UNKNOWN                                   = 0;
    IOS                                          = 1; 
    ANDROID                                      = 2;
    HARMONY                                      = 7;  //纯血鸿蒙
}

// MAX 最大限定
enum MAX {
    MAX_UNKNOWN                                  = 0;
    U8                                           = 64;
    U32                                          = 8;
    FLAG                                         = 4;
}