商品資料集 (Item Dataset)

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

建立商品資料集 (/create-item-dataset)

使用範例

呼叫 API：

curl

curl --request POST 'https://api.raas.kklab.com/create-item-dataset' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "example-items",
    "num_shards": 10,
    "attribute_schema": {
        "price": "NUMERICAL",
        "categories": "CATEGORICAL"
    },
}'

python

import json
import requests
from pprint import pprint

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

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

data={
    "name": "example-items",
    "num_shards": 10,
    "attribute_schema": {
        "price": "NUMERICAL",
        "categories": "CATEGORICAL"
    }
}

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

pprint(response.json())

回傳值：

{
    "item_dataset_id": "$ITEM_DATASET_ID",
    "name": "example-items",
    "attribute_schema": {
        "price": "NUMERICAL",
        "categories": "CATEGORICAL"
    },
    "num_shards": 10
}

資料集大小 (num_shards)

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

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

資料規格 (attribute_schema)

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

• NUMERICAL: 數字類型，其大小有意義。
• CATEGORICAL: 分類類型，若值為陣列，該商品視為有多個類別。
• TEXT: 文字類型。

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

修改商品資料集設定 (/update-item-dataset)

使用範例

呼叫 API：

curl

curl --request PUT 'https://api.raas.kklab.com/update-item-dataset' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "item_dataset_id": "$ITEM_DATASET_ID",
    "name": "new item dataset name"
}'

python

import json
import requests
from pprint import pprint

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

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

data={
    "item_dataset_id": "$ITEM_DATASET_ID",
    "name": "new item dataset name"
}

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

pprint(response.json())

回傳值：

{
    "item_dataset_id": "$ITEM_DATASET_ID",
    "name": "new item dataset name",
    "attribute_schema": {
        "price": "NUMERICAL",
        "categories": "CATEGORICAL"
    },
    "num_shards": 10
}

可更新欄位

• name
• attribute_schema

取得單一商品資料集設定 (/get-item-dataset)

使用範例

呼叫 API：

curl

curl --request GET 'https://api.raas.kklab.com/get-item-dataset?item_dataset_id=$ITEM_DATASET_ID' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY'

python

import requests
from pprint import pprint

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

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

params = {
    "item_dataset_id": "$ITEM_DATASET_ID"
}

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

pprint(response.json())

回傳值：

{
    "item_dataset_id": "$ITEM_DATASET_ID",
    "name": "example-items",
    "attribute_schema": {
        "price": "NUMERICAL",
        "categories": "CATEGORICAL"
    },
    "num_shards": 10
}

列出所有商品資料集 (/list-item-datasets)

使用範例

呼叫 API：

curl

curl --request GET 'https://api.raas.kklab.com/list-item-datasets' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY'

python

import requests
from pprint import pprint

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

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

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

pprint(response.json())

回傳值：

{
    "item_datasets": [
        {
            "item_dataset_id": "$ITEM_DATASET_ID",
            "name": "example-items",
            "attribute_schema": {
                "price": "NUMERICAL",
                "categories": "CATEGORICAL"
            },
            "num_shards": 10
        }
    ]
}

刪除商品資料集 (/delete-item-dataset)

使用範例

呼叫 API：

curl

curl --request DELETE 'https://api.raas.kklab.com/delete-item-dataset' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "item_dataset_id": "$ITEM_DATASET_ID"
}'

python

import json
import requests
from pprint import pprint

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

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

data={
    "item_dataset_id": "$ITEM_DATASET_ID"
}

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

pprint(response.json())

回傳值：

{
    "item_dataset_id": "$ITEM_DATASET_ID",
    "name": "example-items",
    "attribute_schema": {
        "price": "NUMERICAL",
        "categories": "CATEGORICAL"
    },
    "num_shards": 10
}

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

匯入商品資料 (/upsert-dataset-items)

使用範例

匯入兩筆商品資料，呼叫 API：

curl

curl --request POST 'https://api.raas.kklab.com/upsert-dataset-items' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "item_dataset_id": "$ITEM_DATASET_ID",
    "items": [
        {
            "item_id": "1",
            "attributes": {
                "name": "item 1",
                "price": 1000,
                "categories": [
                    "Men's Clothes",
                    "Fashion"
                ]
            }
        },
        {
            "item_id": "2",
            "attributes": {
                "name": "item 2",
                "price": 500
            }
        }
    ]
}'

python

import json
import requests
from pprint import pprint

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

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

data={
    "item_dataset_id": "$ITEM_DATASET_ID",
    "items": [
        {
            "item_id": "1",
            "attributes": {
                "name": "item 1",
                "price": 1000,
                "categories": [
                    "Men's Clothes",
                    "Fashion"
                ]
            }
        },
        {
            "item_id": "2",
            "attributes": {
                "name": "item 2",
                "price": 500
            }
        }
    ]
}

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

pprint(response.json())

回傳值：

{
    "item_dataset_id": "$ITEM_DATASET_ID",
    "succeed_ids": ["1", "2"],
    "failed_ids": []
}

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

參數說明

update_model: 非必填，預設為 false，是否同時更新模型內的商品資料。更新不會即時生效，且對更新有一定的頻率限制，建議僅在修改影響重要 filter query 的 attribute 時打開。

批次大小

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

壓縮

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

限制

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

刪除商品資料 (/delete-dataset-items)

使用範例

呼叫 API：

curl

curl --request DELETE 'https://api.raas.kklab.com/delete-dataset-items' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "item_dataset_id": "$ITEM_DATASET_ID",
    "item_ids": [
        "1",
        "2"
    ]
}'

python

import json
import requests
from pprint import pprint

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

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

data={
    "item_dataset_id": "$ITEM_DATASET_ID",
    "item_ids": [
        "1",
        "2"
    ]
}

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

pprint(response.json())

回傳值：

{
    "item_dataset_id": "$ITEM_DATASET_ID",
    "succeed_ids": ["1", "2"],
    "failed_ids": []
}

參數說明

update_model: 非必填，預設為 false，是否同時更新模型內的商品資料。更新不會即時生效，且對更新有一定的頻率限制，建議僅在修改影響重要 filter query 的 attribute 時打開。

批次大小

同匯入商品的 API，刪除使用者的 API 亦支援批次刪除。

限制

• 一次 API 呼叫最多刪除1000筆商品資料。

刪除特定時間內未更新的商品資料 (/delete-dataset-items-before-ts)

由於是大量刪除資料，並不會即時生效。根據資料集的大小，須等待10~120分鐘陸續生效。

使用範例

呼叫 API：

curl

curl --request DELETE 'https://api.raas.kklab.com/delete-dataset-items-before-ts' \
--header 'Authorization: Bearer $TOKEN' \
--header 'APIKey: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "item_dataset_id": "$ITEM_DATASET_ID",
    "ts": 1634201445000
}'

回傳值：

{
    "item_dataset_id": "$ITEM_DATASET_ID",
    "ts": 1634201445000
}