4 saastool工具

saastool 是提供给客户的便捷命令行工具，使客户在不开发或少开发的情况下即可实现【数据管理】【策略管理】的对应功能。

开发者也可以参考该工具的功能源码(golang)，实现贴合自身业务的处理逻辑。

源码：saastool

4.1 命令行模式

saastool help

Usage:  saastool COMMAND [OPTIONS]

Commands:
    info               Saas Info
    write              Write user's 'bytes / uint32s / flags'
    read               Read user's 'bytes / uint32s / flags'
    columnclear        Clear columns for data space
    resetds            Reset data space

    convert            Convert data to write format
    
    task               Task commands    
    target             Target commands
    bind               Bind commands
    grant              Grant commands
    script             Script commands
    exp                Exp commands
    rtexp              Realtime exp commands
    admincode          Admin code commands

    daemon             Run in daemon mode
    web                Run web management console

"help" is the default command.

Use "saastool COMMAND -help" for more information about a command.

4.1.1 cfg.toml配置文件

saastool需要一个配置文件，其中可填写自己的Account、Token。使用配置文件可实现多账号多环境的区分。

该配置文件默认名称为 cfg.toml，请置于saastool 同目录下。也可以通过 -cfg 参数指定别的配置文件，例如 saastool -config my.toml。

# 样例
[auth]
account = "2000"
token = "test"

[apiurls]
baseurl = "https://api.rta.qq.com" # 正式环境
#baseurl = "https://srta.algo.com.cn" # 演示环境

4.1.2 info（获取Saas信息）

获取sRTA服务的基本信息，包括数据空间、策略ID等配置信息。

saastool info -help

Usage of info:
  -config string
        Config file. (default "cfg.toml")

参数说明

参数	必填	含义	样例
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool info

4.1.3 read（读取用户数据）

读取指定用户在数据空间中的数据（包括字节、uint32和标志位）。

saastool read -help

Usage of read:
  -accountid int
        Account ID (advertiser ID), required when appid is not empty
  -appid string
        Wechat appid
  -config string
        Config file. (default "cfg.toml")
  -ds string
        Data space ID (required)
  -hashtype int
        Hash Type. 0=HASH_TYPE_DEFAULT, 1=PHONE_MD5, 2=PHONE_SHA256
  -userids string
        Device ID or Wechat UserID, separated by comma (required)

参数说明

参数	必填	含义	样例
-userids	是	用户ID列表，多个ID用逗号分隔；设备号MD5值（小写）或微信openid	cfcd208495d565ef66e7dff9f98764da
-ds	是	数据空间ID	did、wuid、geo、geoip 或 geofac
-appid	否	小程序ID，当ds为wuid时必填	wx1111111111111111
-accountid	否	广告主ID，当appid不为空时必填	12345
-hashtype	否	哈希类型：0=默认，1=PHONE_MD5，2=PHONE_SHA256；当ds为wuid且appid为空时必填	1
-config	否	配置文件路径	cfg.toml（默认）

wuid数据空间约束

当 ds 为 wuid 时，需要满足以下条件之一：

• 提供 -appid 且同时提供 -accountid（按openid读取）
• 不提供 -appid，但必须设置 -hashtype 为 1 或 2（按手机号哈希读取）

使用示例

# 读取did数据空间的用户数据
saastool read -ds did -userids cfcd208495d565ef66e7dff9f98764da

# 读取多个用户数据
saastool read -ds did -userids cfcd208495d565ef66e7dff9f98764da,a87ff679a2f3e71d9181a67b7542122c

# 读取wuid数据空间的用户数据（openid方式）
saastool read -ds wuid -userids o_e3j4ggVPO2CP8iCPBLunzKL79n -appid wx1111111111111111 -accountid 12345

# 读取wuid数据空间的用户数据（手机号MD5方式）
saastool read -ds wuid -userids e10adc3949ba59abbe56e057f20f883e -hashtype 1

4.1.4 write（写入用户数据

向指定数据空间写入用户数据。支持批量写入和清空操作。

saastool write -help

Usage of write:
  -accountid int
        Account ID (advertiser ID), required when appid is not empty
  -appid string
        Wechat appid
  -batchsize uint
        Batch size to sync (default 10000)
  -clear
        Clear all data before write
  -config string
        Config file. (default "cfg.toml")
  -ds string
        Data space ID (required)
  -hashtype int
        Hash Type. 0=HASH_TYPE_DEFAULT, 1=PHONE_MD5, 2=PHONE_SHA256
  -source string
        Source path or filename (required)

参数说明

参数	必填	含义	样例
-source	是	本地文件或目录路径，JSONL格式	./users.jsonl 或 ./data_dir/
-ds	是	数据空间ID	did、wuid、geo、geoip 或 geofac
-appid	否	小程序ID，当ds为wuid时必填	wx1111111111111111
-accountid	否	广告主ID，当appid不为空时必填	12345
-hashtype	否	哈希类型：0=默认，1=PHONE_MD5，2=PHONE_SHA256；当ds为wuid且appid为空时必填	1
-batchsize	否	批处理大小	10000（默认）
-clear	否	写入前是否清空所有数据	不填时为false
-config	否	配置文件路径	cfg.toml（默认）

wuid数据空间约束

当 ds 为 wuid 时，需要满足以下条件之一：

• 提供 -appid 且同时提供 -accountid（按openid写入）
• 不提供 -appid，但必须设置 -hashtype 为 1 或 2（按手机号哈希写入）

数据格式说明

JSONL 文件格式，每行一个JSON对象，包含 userid 和数据字段：

{"userid":"cfcd208495d565ef66e7dff9f98764da","bytesKv":{"1":1,"2":100},"uint32sKv":{"1":1000000}}
{"userid":"a87ff679a2f3e71d9181a67b7542122c","bytesKv":{"1":2,"2":200},"flagsWithExpireKv":{"1":{"flag":true}}}

使用示例

# 写入单个文件数据
saastool write -ds did -source ./users.jsonl

# 写入目录下所有文件
saastool write -ds did -source ./data_dir/ -batchsize 5000

# 写入前清空所有数据
saastool write -ds did -source ./users.jsonl -clear

# 写入wuid数据空间（openid方式，需要appid和accountid）
saastool write -ds wuid -source ./openid_users.jsonl -appid wx1111111111111111 -accountid 12345

# 写入wuid数据空间（手机号MD5方式）
saastool write -ds wuid -source ./phone_users.jsonl -hashtype 1

4.1.5 resetds（重置数据空间）

重置指定数据空间，清除所有用户数据。

注意

此操作为破坏性操作，将删除数据空间中的所有数据，请谨慎使用。

saastool resetds -help

Usage of resetds:
  -config string
        Config file. (default "cfg.toml")
  -ds string
        Data space ID (required)

参数说明

参数	必填	含义	样例
-ds	是	数据空间ID	geo、geoip 或 geofac
-config	否	配置文件路径	cfg.toml（默认）

使用示例

# 重置geo数据空间
saastool resetds -ds geo

# 重置geofac数据空间
saastool resetds -ds geofac

4.1.6 convert（数据转换）

将简化的数据格式转换为saastool写入格式，便于批量数据导入。

saastool convert -help

Usage of convert:
  -dest string
        Destination path or filename (required)
  -map string
        target map setting (required)
  -source string
        Source path or filename (required)

参数说明

参数	必填	含义	样例
-source	是	源数据文件或目录路径	./raw_data/ 或 ./raw_data.txt
-dest	是	转换后数据的输出目录	./converted_data/
-map	是	映射配置文件路径（JSON格式）	./map.json

映射文件格式

{
    "targets": {
        "news_1": {
            "write_byte": 1,
            "write_byte_pos": 0
        },
        "music_2": {
            "write_byte": 2,
            "write_byte_pos": 1
        }
    }
}

使用示例

saastool convert -map ./map.json -source ./raw_data/ -dest ./converted_data/

转换结果示例：

{"userid":"692873b822ef89cb7e935ff370881026","bytesKv":{"1":1,"2":2}}
{"userid":"a763b592c846f0a78fb9b326d5c8ba78","bytesKv":{"1":1,"2":3}}

4.1.7 columnclear（列清零）

将指定数据空间中全量用户的一个或多个列（byte、uint32、flag）清零。对于 DID/WUID 数据空间采用惰性失效机制，对于 Geo/GeoIP/GeoFAC 采用直接 Redis 覆写方式。

saastool columnclear -help

Usage of columnclear:
  -all
        Clear all columns
  -config string
        Config file. (default "cfg.toml")
  -ds string
        Data space ID (required)
  -flag string
        Flag column indexes to clear (1-4), comma separated. e.g. '1,2'
  -u32 string
        Uint32 column indexes to clear (1-8), comma separated. e.g. '1,2'
  -u8 string
        Uint8 column indexes to clear (1-64), comma separated. e.g. '1,2,3'

参数说明

参数	必填	含义	样例
-ds	是	数据空间ID	did、wuid、geo、geoip 或 geofac
-all	否	是否清零所有列	不填时为false
-u8	否	要清零的 uint8 列索引（1-64），逗号分隔	1,2,3
-u32	否	要清零的 uint32 列索引（1-8），逗号分隔	1,2
-flag	否	要清零的 flag 列索引（1-4），逗号分隔	1,2
-config	否	配置文件路径	cfg.toml（默认）

提示

必须指定 -all 或至少一个 -u8、-u32、-flag 参数。

使用示例

# 清零 did 数据空间的所有列
saastool columnclear -ds did -all

# 清零 did 数据空间的指定 uint8 列
saastool columnclear -ds did -u8 1,2,3

# 清零 wuid 数据空间的指定 uint32 和 flag 列
saastool columnclear -ds wuid -u32 1,2 -flag 1

# 清零 geo 数据空间的所有列
saastool columnclear -ds geo -all

4.1.8 daemon（守护进程/HTTP服务）

以守护进程模式启动saastool HTTP服务，提供HTTP接口进行数据读写操作。

saastool daemon -help

环境变量

变量名	含义	样例
SRTA_ACCOUNT	sRTA账号（必填）	2000
SRTA_TOKEN	sRTA Token（必填）	test_token
SRTA_ENV	环境类型：demo、prd 或 dev	demo、prd
SRTA_PORT	服务监听端口（可选）	8080（默认）

使用示例

# 启动daemon模式
export SRTA_ACCOUNT=2000
export SRTA_TOKEN=mytoken
export SRTA_ENV=demo
export SRTA_PORT=8080
saastool daemon

启动后，HTTP服务监听在配置的端口（默认8080），支持 /read 和 /write 接口。

4.1.9 task（任务管理）命令列表

用于管理文件上传任务。任务管理分为两个阶段：

1. 本地处理阶段：计算文件哈希和块大小（make）
2. 服务端操作阶段：创建、查询、上传、下载、运行和删除任务

saastool task help

Usage:  saastool task COMMAND [OPTIONS]

Commands:
    list                 List tasks on server
    make                 Make file hash for upload task
    create               Create a task on server
    upload               Upload task's file block to server
    download             Download task's file block to local
    run                  Run a task on server
    delete               Delete a task on server
    info                 Get a task info on server

"help" is the default command.

Use "saastool task COMMAND -help" for more information about a command.

4.1.9.1 task list（查询任务列表）

查询已创建的所有任务及其状态。

saastool task list -help

Usage of list:
  -config string
        Config file. (default "cfg.toml")
  -status string
        Filter status. enums 'all', 'waiting', 'running', 'success', 'fail', 'deleted'

参数说明

参数	必填	含义	样例
-status	否	任务状态过滤：all、waiting、running、success、fail、deleted	waiting（默认all）
-config	否	配置文件路径	cfg.toml（默认）

使用示例

# 查询所有任务
saastool task list

# 查询正在运行的任务
saastool task list -status running

# 查询已完成的任务
saastool task list -status success

4.1.9.2 task make（生成任务哈希）

计算本地文件或目录的SHA256哈希值，生成任务文件。这是上传文件前的必要步骤。

saastool task make -help

Usage of make:
  -accountid int
        Account ID (advertiser ID), required when appid is not empty
  -appid string
        AppID for wuid dataspace
  -blocksize string
        Block size to make hash. using size mode K, M, G, T (default "50M")
  -ds string
        DataSpace ID (required)
  -hashfile string
        Output hash file (required)
  -hashtype int
        Hash Type. 0=HASH_TYPE_DEFAULT, 1=PHONE_MD5, 2=PHONE_SHA256
  -source string
        source file or directory path (required)
  -desc string
        Task description

参数说明

参数	必填	含义	样例
-source	是	本地文件或目录路径	./data.jsonl 或 ./data_dir/
-hashfile	是	输出的哈希文件路径	./task.json
-ds	是	数据空间ID	did、wuid、geo、geoip 或 geofac
-blocksize	否	块大小，支持 K/M/G/T 单位（50M-200M）	100M、1G（默认50M）
-appid	否	小程序ID，当ds为wuid时必填	wx1111111111111111
-accountid	否	广告主ID，当appid不为空时必填	12345
-hashtype	否	哈希类型：0=默认，1=PHONE_MD5，2=PHONE_SHA256	1
-desc	否	任务描述	用户属性批量导入

使用示例

# 计算单个文件的哈希
saastool task make -source ./users.jsonl -hashfile ./task.json -ds did

# 计算目录的哈希，指定块大小
saastool task make -source ./data_dir/ -hashfile ./task.json -ds did -blocksize 100M

# 为wuid数据空间创建任务（需要appid和accountid）
saastool task make -source ./users.jsonl -hashfile ./task.json -ds wuid -appid wx1111111111111111 -accountid 12345 -desc "openid用户导入"

# 为wuid数据空间创建任务，使用手机号MD5哈希（无需appid）
saastool task make -source ./phones.jsonl -hashfile ./task.json -ds wuid -hashtype 1

4.1.9.3 task create（创建任务）

将本地生成的任务文件上传到服务器，创建一个新任务。

saastool task create -help

Usage of create:
  -config string
        Config file. (default "cfg.toml")
  -hashfile string
        Input hash file (required)

参数说明

参数	必填	含义	样例
-hashfile	是	任务文件路径（由task make生成）	./task.json
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool task create -hashfile ./task.json

4.1.9.4 task upload（上传任务文件）

上传任务的文件块到服务器。

saastool task upload -help

Usage of upload:
  -config string
        Config file. (default "cfg.toml")
  -sha256 string
        Task SHA256 hash (required)

参数说明

参数	必填	含义	样例
-sha256	是	任务SHA256哈希值	abc123def456...
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool task upload -sha256 abc123def456...

4.1.9.5 task download（下载任务文件）

从服务器下载任务的文件块到本地。

saastool task download -help

Usage of download:
  -config string
        Config file. (default "cfg.toml")
  -dest string
        Destination path (required)
  -sha256 string
        Task SHA256 hash (required)

参数说明

参数	必填	含义	样例
-sha256	是	任务SHA256哈希值	abc123def456...
-dest	是	目标下载路径	./output/
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool task download -sha256 abc123def456... -dest ./output/

4.1.9.6 task run（运行任务）

在服务器上运行任务，处理已上传的数据。

saastool task run -help

Usage of run:
  -config string
        Config file. (default "cfg.toml")
  -sha256 string
        Task SHA256 hash (required)

参数说明

参数	必填	含义	样例
-sha256	是	任务SHA256哈希值	abc123def456...
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool task run -sha256 abc123def456...

4.1.9.7 task delete（删除任务）

从服务器删除任务。

saastool task delete -help

Usage of delete:
  -config string
        Config file. (default "cfg.toml")
  -sha256 string
        Task SHA256 hash (required)

参数说明

参数	必填	含义	样例
-sha256	是	任务SHA256哈希值	abc123def456...
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool task delete -sha256 abc123def456...

4.1.9.8 task info（获取任务信息）

获取服务器上的任务详细信息。

saastool task info -help

Usage of info:
  -config string
        Config file. (default "cfg.toml")
  -sha256 string
        Task SHA256 hash (required)

参数说明

参数	必填	含义	样例
-sha256	是	任务SHA256哈希值	abc123def456...
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool task info -sha256 abc123def456...

4.1.10 target（策略管理）命令列表

用于管理策略/目标，包括创建、查询和删除策略。

saastool target help

Usage:  saastool target COMMAND [OPTIONS]

Commands:
    list                 List targets
    create               Create a new target
    delete               Delete an existing target
    config               Manage target-level configurations

"help" is the default command.

Use "saastool target COMMAND -help" for more information about a command.

4.1.10.1 target list（查询策略列表）

查询已创建的所有策略及其信息。

saastool target list -help

Usage of list:
  -config string
        Config file. (default "cfg.toml")
  -targets string
        Target IDs. Use commas to separate multiple IDs
  -b
        List Binds

参数说明

参数	必填	含义	样例
-targets	否	目标ID列表，多个ID用逗号分隔	target1,target2
-b	否	是否列出绑定信息	不填时仅列出策略名称
-config	否	配置文件路径	cfg.toml（默认）

使用示例

# 查询所有策略
saastool target list

# 查询指定策略
saastool target list -targets my_target

# 查询多个策略及其绑定信息
saastool target list -targets target1,target2 -b

4.1.10.2 target create（创建策略）

创建一个新的策略。

saastool target create -help

Usage of create:
  -config string
        Config file. (default "cfg.toml")
  -target string
        Target ID (required)
  -desc string
        Task description

参数说明

参数	必填	含义	样例
-target	是	策略ID，3-20个字符	my_target
-desc	否	策略描述	核心用户策略
-config	否	配置文件路径	cfg.toml（默认）

使用示例

# 创建简单策略
saastool target create -target my_target

# 创建带描述的策略
saastool target create -target my_target -desc "核心用户策略"

4.1.10.3 target delete（删除策略）

删除已创建的策略。

saastool target delete -help

Usage of delete:
  -config string
        Config file. (default "cfg.toml")
  -target string
        Target ID (required)

参数说明

参数	必填	含义	样例
-target	是	策略ID	my_target
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool target delete -target my_target

4.1.10.4 target config（策略级配置）

用于管理策略级配置，目前支持赔付期 CPA 出价调节和赔付期权重调节两个开关。

saastool target config help

Usage:  saastool target config COMMAND [OPTIONS]

Commands:
    list                 List target-level configurations
    update               Update target-level configurations (single target per call)

Field values (0=enable/default, 2=disable):
    -enable-cpa          Enable CPA on cost guarantee.    -1=keep, 0=enable, 2=disable
    -enable-weight       Enable weight on cost guarantee. -1=keep, 0=enable, 2=disable

Note: saastool update supports one target per call.
      For batch updates (up to 10 targets), use 'saasai target config update --items=...'.

4.1.10.4.1 target config list（查询策略级配置）

查询本账户策略的赔付期配置状态。不传 -targets 时返回全部策略。

saastool target config list -help

Usage of list:
  -config string
        Config file. (default "cfg.toml")
  -targets string
        Target IDs. Use commas to separate multiple IDs

参数说明

参数	必填	含义	样例
-targets	否	策略 ID 列表，逗号分隔（空=全部）	t1,t2,t3
-config	否	配置文件路径	cfg.toml（默认）

字段值语义

值	含义
0	启用（默认）
2	禁用

使用示例

# 查询全部策略的配置
saastool target config list

# 查询指定策略
saastool target config list -targets t1,t2

4.1.10.4.2 target config update（修改策略级配置）

修改单个策略的赔付期配置。一次只能修改一个策略；如需批量修改，请使用 saasai target config update --items=...。

saastool target config update -help

Usage of update:
  -config string
        Config file. (default "cfg.toml")
  -enable-cpa int
        Enable CPA on cost guarantee. -1=keep, 0=enable, 2=disable (default -1)
  -enable-weight int
        Enable weight on cost guarantee. -1=keep, 0=enable, 2=disable (default -1)
  -target string
        Target ID

参数说明

参数	必填	含义	样例
-target	是	策略 ID	t1
-enable-cpa	否	赔付期 CPA 调节：-1=保持, 0=启用, 2=禁用	2
-enable-weight	否	赔付期权重调节：-1=保持, 0=启用, 2=禁用	2
-config	否	配置文件路径	cfg.toml（默认）

至少指定 -enable-cpa 或 -enable-weight 中的一个。

使用示例

# 禁用某策略的 CPA 调节
saastool target config update -target t1 -enable-cpa 2

# 恢复某策略的权重调节为默认（启用）
saastool target config update -target t1 -enable-weight 0

# 同时修改两个字段
saastool target config update -target t1 -enable-cpa 2 -enable-weight 2

4.1.11 bind（策略绑定）命令列表

用于将广告主账户和广告组与策略进行绑定。

saastool bind help

Usage:  saastool bind COMMAND [OPTIONS]

Commands:
    setaccount           Set Account binds
    setad                Set AdGroup binds
    delete               Delete binds

"help" is the default command.

Use "saastool bind COMMAND -help" for more information about a command.

4.1.11.1 bind setaccount（绑定账户）

将广告主账户与策略进行绑定。

saastool bind setaccount -help

Usage of setaccount:
  -config string
        Config file. (default "cfg.toml")
  -target string
        Target ID (required)
  -accounts string
        Advertiser IDs. Use commas to separate multiple IDs (required)

参数说明

参数	必填	含义	样例
-target	是	策略ID	my_target
-accounts	是	广告主ID列表，多个ID用逗号分隔	123,456,789
-config	否	配置文件路径	cfg.toml（默认）

使用示例

# 绑定单个账户
saastool bind setaccount -target my_target -accounts 123

# 绑定多个账户
saastool bind setaccount -target my_target -accounts 123,456,789

4.1.11.2 bind setad（绑定广告组）

将广告组与策略进行绑定。

saastool bind setad -help

Usage of setad:
  -config string
        Config file. (default "cfg.toml")
  -target string
        Target ID (required)
  -account int64
        Advertiser ID (required)
  -ads string
        AdGroup IDs. Use commas to separate multiple IDs (required)

参数说明

参数	必填	含义	样例
-target	是	策略ID	my_target
-account	是	广告主ID	123
-ads	是	广告组ID列表，多个ID用逗号分隔	1001,1002,1003
-config	否	配置文件路径	cfg.toml（默认）

使用示例

# 绑定单个广告组
saastool bind setad -target my_target -account 123 -ads 1001

# 绑定多个广告组
saastool bind setad -target my_target -account 123 -ads 1001,1002,1003

4.1.11.3 bind delete（删除绑定）

删除账户或广告组与策略的绑定关系。

saastool bind delete -help

Usage of delete:
  -config string
        Config file. (default "cfg.toml")
  -idtype int
        ID Type. empty is Automatic matching, 1=AdGroup, 3=Account
  -ids string
        IDs for delete. Use commas to separate multiple IDs (required)
  -target string
        Target ID (required)

参数说明

参数	必填	含义	样例
-target	是	策略ID	my_target
-ids	是	要删除的ID列表，多个ID用逗号分隔	1001,1002
-idtype	否	ID类型：空=自动匹配，1=广告组，3=账户	1 或 3
-config	否	配置文件路径	cfg.toml（默认）

使用示例

# 删除指定策略的广告组绑定
saastool bind delete -target my_target -ids 1001,1002

# 删除指定策略的广告组绑定（指定类型）
saastool bind delete -target my_target -idtype 1 -ids 1001,1002,1003

# 删除指定策略的账户绑定
saastool bind delete -target my_target -idtype 3 -ids 123,456

4.1.12 grant（授权管理）命令列表

用于管理数据空间的授权，允许其他账号访问您的数据。

saastool grant help

Usage:  saastool grant COMMAND [OPTIONS]

Commands:
    list                 List data grants
    add                  Add data grant
    delete               Delete data grant

"help" is the default command.

Use "saastool grant COMMAND -help" for more information about a command.

4.1.12.1 grant list（查询授权列表）

查询已授权给他人以及他人授权给您的权限。

saastool grant list -help

Usage of list:
  -config string
        Config file. (default "cfg.toml")

参数说明

参数	必填	含义	样例
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool grant list

4.1.12.2 grant add（添加授权）

为其他账号授权访问您的数据。

saastool grant add -help

Usage of add:
  -config string
        Config file. (default "cfg.toml")
  -account uint
        sRTA account ID (required)
  -ds uint
        Raw data space ID (required)
  -index string
        Grant index. Format: "1, 2, 4, 55-64" (required)

参数说明

参数	必填	含义	样例
-account	是	被授权的目标账号ID	2001
-ds	是	数据空间ID	1
-index	是	授权位索引，支持单个或范围格式	1,2,4,55-64
-config	否	配置文件路径	cfg.toml（默认）

使用示例

# 授权单个位
saastool grant add -account 2001 -ds 1 -index 1

# 授权多个位和范围
saastool grant add -account 2001 -ds 1 -index "1,2,4,10-20"

4.1.12.3 grant delete（删除授权）

撤销已授予其他账号的数据访问权限。

saastool grant delete -help

Usage of delete:
  -config string
        Config file. (default "cfg.toml")
  -account uint
        sRTA account ID (required)
  -ds uint
        Raw data space ID (required)
  -index string
        Grant index. Format: "1, 2, 4, 55-64" (required)

参数说明

参数	必填	含义	样例
-account	是	目标账号ID	2001
-ds	是	数据空间ID	1
-index	是	要删除的授权位索引	1,2,4
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool grant delete -account 2001 -ds 1 -index "1,2"

4.1.13 script（脚本管理）命令列表

用于管理Lua脚本，用于数据处理和业务逻辑定制。

saastool script help

Usage:  saastool script COMMAND [OPTIONS]

Commands:
    list                 List all scripts on server
    debug                Debug lua script on server
    create               Create lua script on server
    delete               Delete a script from server
    get                  Get script content from server
    use                  Use a script as default

"help" is the default command.

Use "saastool script COMMAND -help" for more information about a command.

4.1.13.1 script list（查询脚本列表）

列出所有已创建的脚本及其状态。

saastool script list -help

Usage of list:
  -config string
        Config file. (default "cfg.toml")

参数说明

参数	必填	含义	样例
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool script list

4.1.13.2 script debug（调试脚本）

在服务器上调试Lua脚本。

saastool script debug -help

Usage of debug:
  -config string
        Config file. (default "cfg.toml")
  -lua string
        LUA file name (required)
  -userid string
        device md5 (lower case) / openid / phone md5 / phone sha256 (required)
  -ds string
        dataspace id
  -os uint
        1=iOS, 2=Android, 7=Harmony default=2

参数说明

参数	必填	含义	样例
-lua	是	Lua脚本文件路径	./script.lua
-userid	是	用户ID（设备md5值小写、openid、手机号md5、手机号sha256）	abc123def456...
-ds	否	数据空间ID	123
-os	否	操作系统：1=iOS，2=Android，7=Harmony	2（默认）
-config	否	配置文件路径	cfg.toml（默认）

使用示例

# 调试脚本
saastool script debug -lua ./script.lua -userid abc123def456 -os 2

# 指定数据空间
saastool script debug -lua ./script.lua -userid abc123def456 -ds 123 -os 2

4.1.13.3 script create（创建脚本）

在服务器上创建一个新的Lua脚本。

saastool script create -help

Usage of create:
  -config string
        Config file. (default "cfg.toml")
  -lua string
        LUA file name (required)
  -name string
        Name (required)

参数说明

参数	必填	含义	样例
-lua	是	Lua脚本文件路径	./script.lua
-name	是	脚本名称，3-20个字符，英文字母、数字和中划线	my-script
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool script create -lua ./script.lua -name my-script

4.1.13.4 script delete（删除脚本）

从服务器删除一个脚本。

saastool script delete -help

Usage of delete:
  -config string
        Config file. (default "cfg.toml")
  -name string
        Name (required)

参数说明

参数	必填	含义	样例
-name	是	脚本名称	my-script
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool script delete -name my-script

4.1.13.5 script get（获取脚本内容）

从服务器获取指定脚本的内容。

saastool script get -help

Usage of get:
  -config string
        Config file. (default "cfg.toml")
  -name string
        Name (required)

参数说明

参数	必填	含义	样例
-name	是	脚本名称	my-script
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool script get -name my-script

4.1.13.6 script use（设置默认脚本）

将指定的脚本设置为默认脚本。

saastool script use -help

Usage of use:
  -config string
        Config file. (default "cfg.toml")
  -name string
        Name (required)

参数说明

参数	必填	含义	样例
-name	是	脚本名称	my-script
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool script use -name my-script

4.1.14 exp（实验管理）命令列表

用于管理和查询实验数据。

saastool exp help

Usage:  saastool exp COMMAND [OPTIONS]

Commands:
    list                 List exps
    get                  Get exp report
    grant                Experiment authorization management

"help" is the default command.

Use "saastool exp COMMAND -help" for more information about a command.

4.1.14.1 exp list（查询实验列表）

列出所有已创建的实验。

saastool exp list -help

Usage of list:
  -config string
        Config file. (default "cfg.toml")

参数说明

参数	必填	含义	样例
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool exp list

4.1.14.2 exp get（获取实验报告）

查询实验的数据报告。

saastool exp get -help

Usage of get:
  -config string
        Config file. (default "cfg.toml")
  -beginday uint64
        Begin day (required)
  -endday uint64
        End day (required)
  -target string
        Target ID (required)
  -bucketids string
        Bucket IDs. Use commas to separate multiple IDs. empty is all
  -uid string
        Advertiser IDs. Use commas to separate multiple IDs.
  -groupby string
        Group by. Use commas to separate multiple fields. empty is none
  -extfields string
        Ext fields. Use commas to separate multiple fields. * is all
  -total
        Total flag

参数说明

参数	必填	含义	样例
-beginday	是	开始日期（YYYYMMDD格式）	20250101
-endday	是	结束日期（YYYYMMDD格式）	20250131
-target	是	策略ID	my_target
-bucketids	否	桶ID列表，用逗号分隔；留空表示所有	1,2,3
-uid	否	广告主ID列表，用逗号分隔	123,456
-groupby	否	分组字段，用逗号分隔；可选值：advertiser_id、user_weight_factor	advertiser_id
-extfields	否	扩展字段，用逗号分隔；* 表示所有	*
-total	否	是否返回总计数据	不填时为false
-config	否	配置文件路径	cfg.toml（默认）

日期范围说明

• 最早支持日期：20250101
• 最晚支持日期：21001231
• 格式：YYYYMMDD

使用示例

# 查询日期范围内的实验数据
saastool exp get -beginday 20250101 -endday 20250131 -target my_target

# 查询指定桶的数据
saastool exp get -beginday 20250101 -endday 20250131 -target my_target -bucketids 1,2,3

# 按广告主分组查询
saastool exp get -beginday 20250101 -endday 20250131 -target my_target -uid 123,456 -groupby advertiser_id

# 查询所有扩展字段及总计
saastool exp get -beginday 20250101 -endday 20250131 -target my_target -total -extfields "*"

4.1.14.3 exp grant（实验授权管理）

管理实验的授权权限。

saastool exp grant help

Usage:  saastool exp grant COMMAND [OPTIONS]

Commands:
    list                 List experiment authorization
    add                  Add experiment authorization
    delete               Delete experiment authorization

"help" is the default command.

Use "saastool exp grant COMMAND -help" for more information about a command.

4.1.14.3.1 exp grant list（查询实验授权列表）

查询实验授权情况。

saastool exp grant list -help

Usage of list:
  -config string
        Config file. (default "cfg.toml")

参数说明

参数	必填	含义	样例
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool exp grant list

4.1.14.3.2 exp grant add（添加实验授权）

为指定sRTA账户添加实验访问权限。

saastool exp grant add -help

Usage of add:
  -config string
        Config file. (default "cfg.toml")
  -account uint64
        sRTA account ID (required)

参数说明

参数	必填	含义	样例
-account	是	sRTA账户ID	12345
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool exp grant add -account 12345

4.1.14.3.3 exp grant delete（删除实验授权）

撤销指定sRTA账户的实验访问权限。

saastool exp grant delete -help

Usage of delete:
  -config string
        Config file. (default "cfg.toml")
  -account uint64
        sRTA account ID (required)

参数说明

参数	必填	含义	样例
-account	是	sRTA账户ID	12345
-config	否	配置文件路径	cfg.toml（默认）

使用示例

saastool exp grant delete -account 12345

4.1.15 rtexp（实时实验报表）命令列表

用于查询实时实验报表数据（InfluxDB 数据源），支持自定义对照组/实验组分桶、分钟级时间范围和归一化。

saastool rtexp help

Usage:  saastool rtexp COMMAND [OPTIONS]

Commands:
    get                 Get realtime exp report

"help" is the default command.

Use "saastool rtexp COMMAND -help" for more information about a command.

4.1.15.1 rtexp get（获取实时实验报表）

查询实时实验报表数据。与 exp get（离线 T+1 数据）不同，rtexp get 从 InfluxDB 实时流查询，延迟在分钟级。

saastool rtexp get -help

Usage of get:
  -basebuckets string
        Base bucket IDs, comma separated (required)
  -begintime uint
        Begin time YYYYMMDDHHMMSS (default: today 00:00)
  -config string
        Config file. (default "cfg.toml")
  -endtime uint
        End time YYYYMMDDHHMMSS (default: now, minute precision)
  -expbuckets string
        Exp bucket groups, semicolon separated; commas within each group
  -normalize int
        Normalization flag: 0=off, 1=normalize by bucket count (default 0)
  -target string
        Target ID (required)
  -uid string
        Advertiser IDs. Use commas to separate multiple IDs

参数说明

参数	必填	含义	样例
-target	是	策略ID	my-target
-basebuckets	是	对照组桶ID，逗号分隔（1-10）	0,1,5,6,10
-expbuckets	否	实验组桶ID，分号分隔多组，组内逗号分隔	"2,7;3,8;4,9"
-begintime	否	起始时间 YYYYMMDDHHMMSS	20250622000000（默认今天00:00）
-endtime	否	结束时间 YYYYMMDDHHMMSS	20250622230000（默认当前分钟）
-uid	否	广告主ID，逗号分隔	123,456
-normalize	否	归一化标志：0=否，1=按桶数归一化	1
-config	否	配置文件路径	cfg.toml（默认）

时间范围说明

• 时间格式为14位 YYYYMMDDHHMMSS，秒位自动清零
• 最早支持 T-2（今天0点减2天）
• 结束时间不能大于当前时间
• 结束时间不能小于起始时间+1分钟

分桶ID说明

• 桶 ID 范围 1-10，全局（base + 所有 exp 组）不可重复
• 对照组和实验组的分桶可以不覆盖全部 1-10

跨账户策略

• 跨账户策略格式：<源账户ID>_<策略ID>（如 2033_target-v3）
• 需要源账户已通过 exp grant add 授权

使用示例

# 基本查询
saastool rtexp get -target my-target -basebuckets 0,1,5,6,10 -expbuckets "2,7;3,8;4,9"

# 指定时间范围
saastool rtexp get -target my-target -basebuckets 0,1,5,6,10 \
  -begintime 20250622000000 -endtime 20250622230000

# 带归一化和广告主过滤
saastool rtexp get -target my-target -basebuckets 1,5,6 -expbuckets "2,7;3,8" \
  -uid 123,456 -normalize 1

# 跨账户策略
saastool rtexp get -target 2033_target-v3 -basebuckets 1,5,6 -expbuckets "2,7"

4.1.16 admincode（行政区划代码）命令列表

用于查询中国行政区划代码信息，包括省、市级别的行政区划代码。

saastool admincode help

Usage: saastool admincode <command> [options]

Commands:
  list           List all admin codes

Examples:
  saastool admincode list -c cfg.toml

4.1.16.1 admincode list（查询行政区划代码列表）

查询所有中国行政区划代码，包括省、市级别的代码信息。

saastool admincode list -help

Usage of list:
  -config string
        Config file. (default "cfg.toml")

参数说明

参数	必填	含义	样例
-config	否	配置文件路径	cfg.toml（默认）

使用示例

# 查询所有行政区划代码
saastool admincode list

# 使用指定配置文件
saastool admincode list -config my.toml

返回数据示例

{
  "adminCodes": [
    {
      "code": "110000",
      "province": "北京市",
      "city": ""
    },
    {
      "code": "110100",
      "province": "北京市",
      "city": "市辖区"
    },
    {
      "code": "120000",
      "province": "天津市",
      "city": ""
    },
    {
      "code": "310000",
      "province": "上海市",
      "city": ""
    }
  ]
}

行政区划代码说明

行政区划代码采用国家标准6位数字编码：

• 前2位：省级（省、自治区、直辖市）
• 中间2位：地级（市、地区、自治州）
• 后2位：县级（县、区、县级市）

示例：

• 110000：北京市（省级）
• 110100：北京市市辖区（地级）
• 310000：上海市（省级）

4.2 容器/服务模式

saastool提供了容器版本。在容器中将默认启动为daemon并提供http接口供调用。使用容器版本可以简化配置及开发工作，在操作量不高时使用更通用的http交互形式提供数据读写。

注意

在执行复杂而繁重的处理时，推荐使用标准API。

4.2.1 Docker Compose配置

Demo环境

services:
  saastool:
    image: rta-docker.pkg.coding.net/public/docker/saastool:2026070113
    restart: unless-stopped
    environment:
      - SRTA_ACCOUNT=2000
      - SRTA_TOKEN=mytoken
      - SRTA_ENV=demo
    ports:
      - "8080:8080"

生产环境

services:
  saastool:
    image: rta-docker.pkg.coding.net/public/docker/saastool:2026070113
    restart: unless-stopped
    environment:
      - SRTA_ACCOUNT=2000
      - SRTA_TOKEN=mytoken
      - SRTA_ENV=prd
    ports:
      - "8080:8080"

环境变量

变量名	含义
SRTA_ACCOUNT	sRTA账号
SRTA_TOKEN	sRTA Token
SRTA_ENV	与Demo环境交互(demo) 或 与生产环境交互(prd)

4.2.2 基础信息

在http交互时，sRTA daemon http服务使用 Query String 风格写入/读取数据。它是一种遵循Url规范的格式，通过字段key value来描述需要读取/写入的数据。

http://saastool/[OP]?ds=[DSID]&appid=[APPID]&clear=[CLEAR]

OP类型

OP	功能
read	单个读（适用于GET方法）
write	单个写（适用于GET方法），批量写（适用于POST方法）

基础字段

字段名	必填	含义	样例
ds	是	数据空间ID	did / wuid
appid	否	小程序/小游戏/公众号/视频号的appid 数据空间为wuid类型时填写	wx1111111111111111
clear	否	是否在写入前清空该userid下的全部数据。 仅在write有效	true。如不填该字段，则默认为false

读取操作字段

读取操作仅需在url中增加用户ID

字段名	含义	样例
userid	用户ID。设备号MD5值小写，或是openid	cfcd208495d565ef66e7dff9f98764da

curl "http://saastool/read?ds=did&userid=cfcd208495d565ef66e7dff9f98764da"

写入操作字段

写入操作的写入信息采用 字段类型名称.[编号] 的格式。字段可以拼接在GET请求（单个写），也可以放在POST请求的Body中发送（批量写）。

单个写的用户ID拼接在url中。批量写的用户ID放置在body的每条记录中。

userid=cfcd208495d565ef66e7dff9f98764da&u8.1=10&u8.2=20&u32.1=100000&flag.1=true&flag.2=1758686629&flag.3=!3600

字段名	含义	样例
userid	用户ID。设备号MD5值小写，或是openid。在使用GET请求时，该字段填在query中。	cfcd208495d565ef66e7dff9f98764da
u8.[n]	写入uint8数字区	u8.1=10
u32.[n]	写入uint32数字区	u32.1=1000000
flag.[n]	写入flag区	支持多种格式 flag.1=true 或 flag.1=false（置位且不过期） flag.1=1758686629（在2025-09-24 12:03:49前为true，之后为false） flag.1=!3600（在当前时间+3600秒之前为true，之后为false）

4.2.3 单个读

使用HTTP GET方法发送read请求，读取单条数据。

读did数据：

curl "http://saastool/read?ds=did&userid=cfcd208495d565ef66e7dff9f98764da"

读wuid数据：

curl "http://saastool/read?ds=wuid&userid=o_e3j4ggVPO2CP8iCPBLunzKL79n&appid=wx1111111111111111"

4.2.4 单个写

使用HTTP GET方法发送write请求，写入单条数据

写did数据：

curl "http://saastool/write?ds=did&userid=cfcd208495d565ef66e7dff9f98764da&u8.2=20&u32.1=100000"

写did数据，并在写入前先清空：

curl "http://saastool/write?ds=did&userid=cfcd208495d565ef66e7dff9f98764da&u8.1=10&u32.1=100000&clear=true"

写wuid数据：

curl "http://saastool/write?ds=wuid&userid=o_e3j4ggVPO2CP8iCPBLunzKL79n&appid=wx1111111111111111&u8.1=10&u32.1=100000"

写wuid数据，并在写入前先清空：

curl "http://saastool/write?ds=wuid&userid=o_e3j4ggVPO2CP8iCPBLunzKL79n&appid=wx1111111111111111&u8.1=10&u32.1=100000&clear=true"

4.2.5 批量写

在http POST模式下，sRTA daemon http服务使用 Query String 规范标记公共字段，并在Body中携带写入信息。Header中的 Content-Type 约定为 text/plain。

在url中带入的非公共字段将被忽略

curl -X POST "http://saastool/write?ds=did" \
  -H "Content-Type: text/plain" \
  -d "userid=cfcd208495d565ef66e7dff9f98764da&u8.1=10&u32.1=100000" \
  -d "userid=a87ff679a2f3e71d9181a67b7542122c&u8.1=60&flag.2=true" \
  -d "userid=9dd4e461268c8034f5c8564e155c67a6&u8.2=200&u32.6=1000000&flag.3=!3600" 

4.2.6 容器中使用saastool

在容器中的saastool命令行仍然可以使用，运行时其配置依赖config文件，而不受环境变量的影响。