Skip to content

事件資料集 (Event Dataset)

同一開發帳號下可存在複數個事件資料集,同一事件資料集可供複數個專案使用,避免重複上傳的工作。

建立事件資料集 (/create-event-dataset)

使用範例

呼叫 API:

curl --request POST 'https://api.raas.kklab.com/create-event-dataset' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "example-events",
    "num_shards": 10,
    "attribute_schema": {
        "duration": "NUMERICAL",
        "module": "CATEGORICAL"
    },
}'
import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/create-event-dataset"])

url = "https://api.raas.kklab.com/create-event-dataset"

data={
    "name": "example-events",
    "num_shards": 10,
    "attribute_schema": {
        "duration": "NUMERICAL",
        "module": "CATEGORICAL"
    },
}

response = requests.request("POST", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值:

{
    "event_dataset_id": "$EVENT_DATASET_ID",
    "name": "example-events",
    "attribute_schema": {
        "duration": "NUMERICAL",
        "module": "CATEGORICAL"
    },
    "num_shards": 10
}

資料集大小 (num_shards)

根據開發帳號的付費方案內容,每個開發帳號的所有事件資料集的 num_shards 數值加總有上限,開發者上傳的資料會平均的分散在不同的 shard 中,單一 shard 中無法存在超過 100,000 筆資料,故一個資料集的 num_shards 設定建議設定為該資料集的大小除以 100,000。

目前版本暫時不支援修改資料集的 num_shards 設定。

資料規格 (attribute_schema)

描述每一筆資料欄位的處理方式,預設的開發帳號支援以下格式:

  • NUMERICAL: 數字類型,其大小有意義。
  • CATEGORICAL: 分類類型,若值為陣列,該事件的屬性視為有多個類別。

Recommend HQ 對企業方案支援客製化的資料處理方式,細節請聯絡我們

修改事件資料集設定 (/update-event-dataset)

使用範例

呼叫 API:

curl --request PUT 'https://api.raas.kklab.com/update-event-dataset' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event_dataset_id": "$EVENT_DATASET_ID",
    "name": "new event dataset name"
}'
import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/update-event-dataset"])

url = "https://api.raas.kklab.com/update-event-dataset"

data={
    "event_dataset_id": "$EVENT_DATASET_ID",
    "name": "new event dataset name"
}

response = requests.request("PUT", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值:

{
    "event_dataset_id": "$EVENT_DATASET_ID",
    "name": "new event dataset name",
    "attribute_schema": {
        "duration": "NUMERICAL",
        "module": "CATEGORICAL"
    },
    "num_shards": 10
}

可修改欄位

  • name
  • attribute_schema

取得單一事件資料集設定 (/get-event-dataset)

使用範例

呼叫 API:

curl --request GET 'https://api.raas.kklab.com/get-event-dataset?event_dataset_id=$EVENT_DATASET_ID' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY'
import requests
from pprint import pprint

headers = create_headers(scopes=["/get-event-dataset"])

url = "https://api.raas.kklab.com/get-event-dataset"

params = {
    "event_dataset_id": "$EVENT_DATASET_ID"
}

response = requests.request("GET", url, headers=headers, params=params)

pprint(response.json())

回傳值:

{
    "event_dataset_id": "$EVENT_DATASET_ID",
    "name": "example-events",
    "attribute_schema": {
        "duration": "NUMERICAL",
        "module": "CATEGORICAL"
    },
    "num_shards": 10
}

列出所有事件資料集 (/list-event-datasets)

使用範例

呼叫 API:

curl --request GET 'https://api.raas.kklab.com/list-event-datasets' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY'
import requests
from pprint import pprint

headers = create_headers(scopes=["/list-event-datasets"])

url = "https://api.raas.kklab.com/list-event-datasets"

response = requests.request("GET", url, headers=headers)

pprint(response.json())

回傳值:

{
    "event_datasets": [
        {
            "event_dataset_id": "$EVENT_DATASET_ID",
            "name": "example-events",
            "attribute_schema": {
                "duration": "NUMERICAL",
                "module": "CATEGORICAL"
            },
            "num_shards": 10
        }
    ]
}

刪除事件資料集 (/delete-event-dataset)

使用範例

呼叫 API:

curl --request DELETE 'https://api.raas.kklab.com/delete-event-dataset' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event_dataset_id": "$EVENT_DATASET_ID"
}'
import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/delete-event-dataset"])

url = "https://api.raas.kklab.com/delete-event-dataset"

data={
    "event_dataset_id": "$EVENT_DATASET_ID"
}

response = requests.request("DELETE", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值:

{
    "event_dataset_id": "$EVENT_DATASET_ID",
    "name": "example-events",
    "attribute_schema": {
        "duration": "NUMERICAL",
        "module": "CATEGORICAL"
    },
    "num_shards": 10
}

API 回傳該事件資料集被刪除前的最後設定。

匯入事件資料 (/upsert-dataset-events)

使用範例

匯入兩筆事件資料,呼叫 API:

curl --request POST 'https://api.raas.kklab.com/upsert-dataset-events' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event_dataset_id": "$EVENT_DATASET_ID",
    "events": [
        {
            "event_id": "1_1_1624450092000",
            "user_id": "1",
            "item_id": "1",
            "ts": 1624450092000,
            "event_type": "click",
            "event_value": 1.0,
            "attributes": {
                "module": "index"
            }
        },
        {
            "event_id": "1_2_1624451092000",
            "user_id": "1",
            "item_id": "2",
            "ts": 1624451092000,
            "event_type": "view",
            "event_value": 1.0,
            "attributes": {
                "module": "product_info",
                "duration": 300
            }
        }
    ]
}'
import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/upsert-dataset-events"])

url = "https://api.raas.kklab.com/upsert-dataset-events"

data={
    "event_dataset_id": "$EVENT_DATASET_ID",
    "events": [
        {
            "event_id": "1_1_1624450092000",
            "user_id": "1",
            "item_id": "1",
            "ts": 1624450092000,
            "event_type": "click",
            "event_value": 1.0,
            "attributes": {
                "module": "index"
            }
        },
        {
            "event_id": "1_2_1624451092000",
            "user_id": "1",
            "item_id": "2",
            "ts": 1624451092000,
            "event_type": "view",
            "event_value": 1.0,
            "attributes": {
                "module": "product_info",
                "duration": 300
            }
        }
    ]
}

response = requests.request("POST", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值:

{
    "event_dataset_id": "$EVENT_DATASET_ID",
    "succeed_ids": ["1_1_1624450092000", "1_2_1624451092000"],
    "failed_ids": []
}

如以上範例,事件的 attributes 並不需要與 attribute schema 完全一致,可支援缺少的欄位,亦可支援未定義的欄位。

欄位說明

  • event_id: 事件的唯一 id,用以區別兩個同時發生的事件,若 log 中沒有唯一的 id,建議用 user_iditem_idts 組合而成。
  • user_id: 參與事件的使用者 id。
  • item_id: 參與事件的商品 id。
  • ts: 事件的發生時間,以毫秒(ms)為單位。
  • event_type: 事件類型,建立專案時需選擇事件類型作為模型優化使用。
  • event_value: 事件的權重,數字越大,訓練模型時的權重越高。
  • attributes: 事件的各種屬性。

批次大小

由於通常需要上傳大量資料,每一筆匯入資料 API 支援一次上傳多筆資料,一次建議上傳1000筆資料,以達到最大上傳效率。如需要更快速的上傳,建議使用多線程 (multithreading) 進行上傳。

壓縮

Recommend HQ 的所有 API 皆支援 gzip 壓縮,實際使用時建議使用 gzip 壓縮的 API 請求來減少資料傳輸大小,提升資料交換效率。

限制

  • 每一筆事件資料大小最大為 20 kb。
  • 一次 API 呼叫最多含有1000筆資料。

刪除特定使用者的所有事件 (/delete-dataset-user-events)

配合產品功能或個資法需求,Recommend HQ 支援刪除事件資料集中特定使用者的所有事件。

使用範例

呼叫 API:

curl --request DELETE 'https://api.raas.kklab.com/delete-dataset-user-events' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event_dataset_id": "$EVENT_DATASET_ID",
    "user_id": "$USER_ID"
}'
import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/delete-dataset-user-events"])

url = "https://api.raas.kklab.com/delete-dataset-user-events"

data={
    "event_dataset_id": "$EVENT_DATASET_ID",
    "user_id": "$USER_ID"
}

response = requests.request("DELETE", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值:

{
    "event_dataset_id": "$EVENT_DATASET_ID",
    "user_id": "$USER_ID"
}

刪除特定時間前的所有事件 (/delete-dataset-events-before-ts)

因事件資料集有大小上限,建議定期刪除舊的事件資料,以確保有足夠空間匯入新的事件資料。

使用範例

呼叫 API:

curl --request DELETE 'https://api.raas.kklab.com/delete-dataset-events-before-ts' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event_dataset_id": "$EVENT_DATASET_ID",
    "ts": 1000000000000
}'
import json
import requests
from pprint import pprint

headers = create_headers(scopes=["/delete-dataset-events-before-ts"])

url = "https://api.raas.kklab.com/delete-dataset-events-before-ts"

data={
    "event_dataset_id": "$EVENT_DATASET_ID",
    "ts": 1000000000000
}

response = requests.request("DELETE", url, headers=headers, data=json.dumps(data))

pprint(response.json())

回傳值:

{
    "event_dataset_id": "$EVENT_DATASET_ID",
    "ts": 1000000000000
}

欄位說明

  • ts: 刪除該時間之前的所有事件,以毫秒(ms)為單位。
  • start_ts: 非必填欄位,該時間之前的事件不會被刪除,預設為0,以毫秒(ms)為單位。