1. 概述

神策分析數據模型元數據主要包括事件定義、事件屬性定義、用戶屬性定義等，透過神策分析可以查看、管理當前專案的元數據。

在預設情況下，系統會根據數據所屬的事件、包含的屬性或用戶屬性來建立元數據。若不希望任何數據都可以建立元數據，可以透過設定專案的 SuperToken 來實現限制。但是設定了 SuperToken 後，若想建立元數據，必須使用設定 SuperToken 的數據進行匯入，這又帶來了一些其他的麻煩，所以我們提供了元數據建立工具，可以直接透過命令行建立元數據。

元數據建立工具有如下幾個功能:

建立事件;
建立事件屬性;
建立用戶屬性;
建立物品屬性；
綁定事件與事件屬性;
匯出元數據;
匯入元數據;

本文將分別介紹每個功能。

使用前請先執行如下命令切換系統帳戶:

sudo su - sa_cluster

CODE

請注意，元數據一旦建立無法刪除，請建立前確認無誤。可以在前端使用管理員帳號登入後在元數據介面隱藏不需要的事件或屬性;

每次操作必須指定 `--project` 參數，表示本次元數據操作的專案;

一個使用實踐：

步驟 1: 為正式專案(區別於測試專案) 的專案設定 SuperToken (設定方法請見多專案管理工具使用說明，實際使用時不使用 SuperToken。這樣除非特意指定 SuperToken，否則不會根據數據建立事件、事件屬性、用戶屬性或物品屬性;
步驟 2: 在測試專案中建立需要的元數據，建立方法可以是透過匯入數據建立，或使用本工具建立;
步驟 3: 使用本工具匯出測試專案的元數據，適當編輯後，再將其匯入正式專案中;
步驟 4: 在正式專案中使用（匯入、查詢）新的事件或屬性; 該實踐的優點是新建元數據的操作都在測試專案中經過檢驗，無誤後才在正式專案中使用。

2. 建立事件

schema_tools -m create_event \
--project <專案名> \
--name <事件名> \
[--cname <事件顯示名>] \
[--properties <事件綁定屬性名>] \
[--bucket <分桶>] \
[--yes]

BASH

spadmin schema -m create_event \
--project <專案名> \
--name <事件名> \
[--cname <事件顯示名>] \
[--properties <事件綁定屬性名>] \
[--bucket <分桶>] \
[--yes]

BASH

project: 必須參數，操作的專案名，預設專案請使用 default;

name: 必須參數，事件名須是合法的變量名，即不能以數字開頭，且只能包含：大小寫字母、數字、_ 和 $

cname: 可選參數，可在介面上設定，不加該參數顯示名預設同事件名;

properties: 可選參數，匯入數據時可與事件屬性自動綁定，與在這裡指定效果相同; 多個屬性名使用英文逗號分隔。若屬性不存在則建立失敗，請先建立事件屬性;

bucket: 可選參數，事件分桶選項，若無特殊情況請勿指定，可選值: new 表示使用新分桶，event:xxx 表示與 xxx 事件同分桶，或直接給出分桶 ID;

yes: 可選參數，如參數指定則不需要再額外確定;

例如在 MyProject 專案中建立事件 BuyGold，顯示名是“購買黃金”:

schema_tools -m create_event \
--project MyProject \
--name BuyGold \
--cname 購買黃金

BASH

spadmin schema -m create_event \
--project MyProject \
--name BuyGold \
--cname 購買黃金

BASH

例如在 MyProject 專案中建立事件 BuyGold，顯示名是“購買黃金”，且事件包含兩個屬性 Weight,Price:

schema_tools -m create_event \
--project MyProject \
--name BuyGold \
--cname 購買黃金 \
--properties Weight,Price

BASH

spadmin schema -m create_event \
--project MyProject \
--name BuyGold \
--cname 購買黃金 \
--properties Weight,Price

BASH

若 name 相同或 cname 相同的事件已經存在，則會建立失敗;

若指定了 properties 字段但最終綁定事件屬性失敗（例如事件屬性不存在），這時事件也不會建立成功；

3. 建立事件屬性

schema_tools -m create_event_property \
--project <專案名> \
--name <屬性名> \
--data_type <數據型別> \
[--cname <屬性顯示名>] \
[--yes]

BASH

spadmin schema -m create_event_property \
--project <專案名> \
--name <屬性名> \
--data_type <數據型別> \
[--cname <屬性顯示名>] \
[--yes]

BASH

project: 必須參數，操作的專案名，預設專案請使用 default;

name: 必須參數，屬性名須是合法的變量名，即不能以數字開頭，且只能包含：大小寫字母、數字、_ 和 $

data_type: 必須參數，代表這個數據的數據型別，可選值包括 NUMBER / BOOL / STRING / LIST / DATE / DATETIME, 請參考數據格式

cname: 可選參數，可在介面上設定，不加該參數顯示名預設同屬性名;

yes: 可選參數，如參數指定則不需要再額外確定;

例如在 MyProject 專案中建立屬性 Price, 顯示名是“價格”:

schema_tools -m create_event_property \
--project MyProject \
--name Price \
--cname 價格 \
--data_type NUMBER

BASH

spadmin schema -m create_event_property \
--project MyProject \
--name Price \
--cname 價格 \
--data_type NUMBER

BASH

若 name 相同或 cname 相同的事件已經存在，則會建立失敗;

4. 建立用戶屬性

除了-m 外其他參數與建立事件屬性參數相同。

例如在 MyProject 專案中建立屬性 PhoneNumber, 顯示名是“電話號碼”:

schema_tools -m create_profile_property \
--project MyProject \
--name PhoneNumber \
--cname 電話號碼 \
--data_type STRING

BASH

spadmin schema -m create_profile_property \
--project MyProject \
--name PhoneNumber \
--cname 電話號碼 \
--data_type STRING

BASH

5. 建立物品屬性

除了 -m 外其他參數與建立事件屬性參數相同。

例如在 MyProject 專案中建立屬性 itemProperty, 顯示名是“物品屬性”:

不支援 item 模型

BASH

spadmin schema -m create_item_property \
--project MyProject \
--name itemProperty \
--cname 物品屬性 \
--data_type STRING

BASH

6. 綁定事件與事件屬性

schema_tools -m bind_event_properties \
--project <專案名> \
--event <事件名> \
--properties <事件屬性名>
[--yes]

BASH

spadmin schema -m bind_event_properties \
--project <專案名> \
--event <事件名> \
--properties <事件屬性名>
[--yes]

BASH

project: 必須參數，操作的專案名，預設專案請使用 default;

event: 必須參數，進行綁定的事件名;

properties: 必須參數，綁定的屬性名，多個時使用英文逗號分隔;

yes: 可選參數，如參數指定則不需要再額外確定;

例如在 MyProject 專案中將 BuyGold 事件與 Price 和 Weight 綁定:

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

BASH

spadmin schema -m bind_event_properties \
--project MyProject \
--event BuyGold \
--properties Price,Weight

BASH

7. 匯出元數據

使用本工具匯出的元數據可以直接用於匯入(下一節介紹)。

schema_tools -m export \
--project <專案名> \
[--file <輸出文件名>]

BASH

spadmin schema -m export \
--project <專案名> \
[--file <輸出文件名>]

BASH

project: 必須參數，操作的專案名，預設專案請使用 default;

file: 可選參數，不指定則輸出到標準輸出;

運行後會匯出指定專案的元數據資訊，例如:

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

BASH

spadmin schema -m export \
--project MyProject \
--file meta.json

BASH

导出的样例格式如下:

{
"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
}
],
"item_properties" : [
{
"name" : "itemProperty",
"cname" : "物品屬性",
"data_type" : "STRING",
"visible" : true
}
],
"bound_event_properties" : [
{
"event" : "BuyGold",
"properties" : [
"Price",
"Weight"
]
},
{
"event" : "PageView",
"properties" : [
"Weight"
]
}
]
}

CODE

8. 匯入元數據

匯入的元數據格式請見 6.匯出元數據中輸出的 JSON;

使用本工具匯出的元數據可以直接用於匯入。

schema_tools -m import \
--project production \
--file <輸入文件名>

BASH

spadmin schema -m import \
--project production \
--file <輸入文件名>

BASH

project: 必須參數，操作的專案名，預設專案請使用 default;

file: 必須參數，指定匯入的元數據所在文件;

其他說明：

若匯入的數據中包含的事件已經存在，那麼忽略該事件繼續匯入;

若匯入的數據中包含的事件或用戶屬性已經存在，那麼對比其數據型別，若相同則忽略該屬性繼續匯入，若型別不相同則全部匯入失敗;

（20170414之後的版本支援）若事件或屬性已存在，且指定了顯示名，將使用新的顯示名覆蓋舊的顯示名;

如果匯入失敗，本次匯入失敗前的操作都不生效;

目前匯入元數據工具僅支援修改元事件和屬性的顯示名，不支援修改元事件和屬性的可見/隱藏狀態。