元数据创建工具使用说明

最后更新于：2018-08-08 11:19:02

1. 概述

神策分析数据模型元数据主要包括事件定义、事件属性定义、用户属性定义等，通过数据管理可以查看、管理当前项目的元数据。

在默认情况下，系统会根据数据所属的事件、包含的属性或用户属性来创建元数据。若不希望任何数据都可以创建元数据，可以通过设置项目的 SuperToken 来实现限制（详见数据导入常见问题 - 13. 数据导入 Token 的作用是什么？）。但是设置了 SuperToken 后，若想创建元数据，必须使用设置 SuperToken 的数据进行导入，这又带来了一些其他的麻烦，所以我们提供了元数据创建工具，可以直接通过命令行创建元数据。

元数据创建工具有如下几个功能:

创建事件;
创建事件属性;
创建用户属性;
绑定事件与事件属性;
导出元数据;
导入元数据;

本文将分别介绍每个功能。

使用前请先执行如下命令切换系统账户:

sudo su - sa_cluster

schema_tools.sh 在 ~/sa/web/bin 目录下;
请注意，元数据一旦创建无法删除，请创建前确认无误。可以在前端使用管理员帐号登录后在元数据界面隐藏不需要的事件或属性;
每次操作必须指定 --project 参数，表示本次元数据操作的项目;

一个使用实践：

步骤 1: 为 正式项目(区别于测试项目) 的项目设置 SuperToken (设置方法请见多项目管理工具使用说明)，实际使用时不使用 SuperToken。这样除非特意指定 SuperToken，否则不会根据数据创建事件、事件属性或用户属性;
步骤 2: 在 测试项目 中创建需要的元数据，创建方法可以是通过导入数据创建，或使用本工具创建;
步骤 3: 使用本工具导出 测试项目 的元数据，适当编辑后，再将其导入 正式项目 中;
步骤 4: 在 正式项目 中使用（导入、查询）新的事件或属性;

该实践的优点是新建元数据的操作都在 测试项目 中经过检验，无误后才在 正式项目 中使用。

2. 创建事件

schema_tools.sh -m create_event \
                --project <项目名> \
                --name <事件名> \
                [--cname <事件显示名>] \
                [--properties <事件绑定属性名>] \
                [--bucket <分桶>] \
                [--yes]

project: 必须参数，操作的项目名，默认项目请使用 default;
name: 必须参数，事件名须是合法的变量名，即不能以数字开头，且只能包含：大小写字母、数字、_ 和 $
cname: 可选参数，可在界面上配置，不加该参数显示名默认同事件名;
properties: 可选参数，导入数据时可与事件属性自动绑定，与在这里指定效果相同; 多个属性名使用英文逗号分隔。若属性不存在则创建失败，请先创建事件属性;
bucket: 可选参数，事件分桶选项，若无特殊情况请勿指定，可选值: new 表示使用新分桶，event:xxx 表示与 xxx 事件同分桶，或直接给出分桶 ID;
yes: 可选参数，如参数指定则不需要再额外确定;

例如在 MyProject 项目中创建事件 BuyGold，显示名是“购买黄金”:

schema_tools.sh -m create_event \
                --project MyProject \
                --name BuyGold \
                --cname 购买黄金

例如在 MyProject 项目中创建事件 BuyGold，显示名是“购买黄金”，且事件包含两个属性 Weight,Price:

schema_tools.sh -m create_event \
                --project MyProject \
                --name BuyGold \
                --cname 购买黄金 \
                --properties Weight,Price

若 name 相同或 cname 相同的事件已经存在，则会创建失败;
若指定了 properties 字段但最终绑定事件属性失败（例如事件属性不存在），这时事件也不会创建成功；

3. 创建事件属性

schema_tools.sh -m create_event_property \
                --project <项目名> \
                --name <属性名> \
                --data_type <数据类型> \
                [--cname <属性显示名>] \
                [--yes]

project: 必须参数，操作的项目名，默认项目请使用 default;
name: 必须参数，属性名须是合法的变量名，即不能以数字开头，且只能包含：大小写字母、数字、_ 和 $
data_type: 必须参数，代表这个数据的数据类型，可选值包括 NUMBER / BOOL / STRING / LIST / DATE / DATETIME, 请参考数据格式 5.2 节
cname: 可选参数，可在界面上配置，不加该参数显示名默认同属性名;
yes: 可选参数，如参数指定则不需要再额外确定;

例如在 MyProject 项目中创建属性 Price, 显示名是“价格”:

schema_tools.sh -m create_event_property \
                --project MyProject \
                --name Price \
                --cname 价格 \
                --data_type NUMBER

若 name 相同或 cname 相同的事件已经存在，则会创建失败;

4. 创建用户属性

除了 -m 外其他参数与创建事件属性参数相同。

例如在 MyProject 项目中创建属性 PhoneNumber, 显示名是“电话号码”:

schema_tools.sh -m create_profile_property \
                --project MyProject \
                --name PhoneNumber \
                --cname 电话号码 \
                --data_type STRING

5. 绑定事件与事件属性

schema_tools.sh -m bind_event_properties \
                --project <项目名> \
                --event <事件名> \
                --properties <事件属性名>
                [--yes]

project: 必须参数，操作的项目名，默认项目请使用 default;
event: 必须参数，进行绑定的事件名;
properties: 必须参数，绑定的属性名，多个时使用英文逗号分隔;
yes: 可选参数，如参数指定则不需要再额外确定;

例如在 MyProject 项目中将 BuyGold 事件与 Price 和 Weight 绑定:

schema_tools.sh -m bind_event_properties \
                --project MyProject \
                --event BuyGold \
                --properties Price,Weight

6. 导出元数据

使用本工具导出的元数据可以直接用于导入(下一节介绍)。

schema_tools.sh -m export \
                --project <项目名> \
                [--file <输出文件名>]

project: 必须参数，操作的项目名，默认项目请使用 default;
file: 可选参数，不指定则输出到标准输出;

运行后会导出指定项目的元数据信息，例如:

schema_tools.sh -m export \
                --project MyProject \
                --file meta.json

导出的样例格式如下:

{
    "events" : [
        {
            "name" : "BuyGold",
            "cname" : "购买黄金",
            "visible" : true
        },
        {
            "name" : "PageView",
            "cname" : "浏览页面",
            "visible" : true
        }
    ],
    "event_properties" : [
        {
            "name" : "Price",
            "cname" : "价格",
            "data_type" : "NUMBER",
            "visible" : true
        },
        {
            "name" : "Weight",
            "cname" : "Weight",
            "data_type" : "NUMBER",
            "visible" : true
        }
    ],
    "profile_properties" : [
        {
            "name" : "PhoneNumber",
            "cname" : "电话号码",
            "data_type" : "STRING",
            "visible" : true
        }
    ],
    "bound_event_properties" : [
        {
            "event" : "BuyGold",
            "properties" : [
                "Price",
                "Weight"
            ]
        },
        {
            "event" : "PageView",
            "properties" : [
                "Weight"
            ]
        }
    ]
}

7. 导入元数据

导入的元数据格式请见 6.导出元数据中输出的 JSON;

使用本工具导出的元数据可以直接用于导入。

bin/schema_tools.sh -m import \
                    --project production \
                    --file <输入文件名>

project: 必须参数，操作的项目名，默认项目请使用 default;
file: 必须参数，指定导入的元数据所在文件;

其他说明：

若导入的数据中包含的事件已经存在，那么忽略该事件继续导入;
若导入的数据中包含的事件或用户属性已经存在，那么对比其数据类型，若相同则忽略该属性继续导入，若类型不相同则全部导入失败;
（20170414之后的版本支持）若事件或属性已存在，且指定了显示名，将使用新的显示名覆盖旧的显示名;
如果导入失败，本次导入失败前的操作都不生效;