用户分析 OpenAPI（私有化）--增长分析（私有化）-火山引擎

文档中心

立即注册

导航

用户分析 OpenAPI（私有化）

最近更新时间：2024.09.19 18:41:10首次发布时间：2023.03.20 20:33:33

1.概述

本文档提供根据不同口径下ID查询用户信息、行为流、标签等信息的接口。
注：私有化4.4版本（含）后支持。

2.API 公共参数

Context-path: /datafinder
Body:

{
    "query_id": "xxxx",
    "query_type": "user_unique_id"
}

Parameter	Type	Description	Required
query_type	str	查询口径类型，当前支持的类型枚举值如下： user_unique_id ssid web_id device_id	true
query_id	str	查询id	true

Parameter

Type

Description

Required

query_type

str

查询口径类型，当前支持的类型枚举值如下：

user_unique_id
ssid
web_id
device_id

true

query_id

str

查询id

true

3.获取用户的用户信息、设备信息、用户标签与用户属性值

3.1 API 定义

Path：openapi/v1/{app_id}/behaviors/profiles
Method: POST
Content-type: application/json
Body: 参考公共参数说明

Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "user_info": {
            "register_time": 1670310396,
            "first_event_time": 1670310396,
            "last_use": "2023-01-18",
            "city": "",
            "ssid": "32cee072-0c1d-4bb4-8a24-31b605dfe673",
            "user_unique_id": "data_quality_report_38",
            "id_info": {
                "ssid": "32cee072-0c1d-4bb4-8a24-31b605dfe673",
                "user_unique_id": "data_quality_report_38",
                "device_id": ""
            }
        },
        "device_info": {
            "device_model": "",
            "app_version": "",
            ....
        },
        "custom_user_props": {
            "profile_1": "profile_value",
            ...
        },
        "user_tag_props"： {
            "tag_1": "标签值",
            ...
        }
}

字段含义说明

Field	Type	Description
user_info	object	用户信息，包含注册时间、首次事件发生时间、最近使用时间、最近ip所在城市、id信息等。 *上述信息如果不存在会用null或空串填充。
device_info	object	设备信息，包含设备型号、操作系统、应用版本、应用渠道、小程序应用版本、设备品牌、浏览器、分辨率、语言、设备价格等。私有化版本中，设备信息仅从用户的最新一条事件中抽取，假设该用户的最新一条事件没有上报设备型号，那本接口也不会返回。上述信息如果不存在会用null或空串填充
custom_user_props	object	用户属性，包含客户通过dataprofile或者sdk上报的last_value类型的用户属性的最新值。
user_tag_props	object	用户标签，包含该用户对应的所有标签值

3.2 OpenAPI SDK 使用样例

bc 为创建的 RangersClient, 其初始化请参考 “OpenAPI SDK 使用说明”，各语言的 SDK 都提供了类似的接口

调用(Python)：

body={
    "query_id": "test_1",
    "query_type": "user_unique_id"
}
res = bc.data_finder('/openapi/v1/12345/behaviors/profiles', body=body)
print(res.content)

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "user_info": {
            "register_time": 1670315402,
            "first_event_time": 1670315402,
            "last_use": "2023-01-28",
            "city": "",
            "ssid": "172020d7-2261-47d8-ae0d-5721d4445f79",
            "user_unique_id": "test_1",
            "id_info": {
                "ssid": "172020d7-2261-47d8-ae0d-5721d4445f79",
                "user_unique_id": "test_1",
                "device_id": ""
            }
        },
        "device_info": {
            "device_model": "",
            "app_version": "",
            "app_channel": "",
            "browser": "",
            "resolution": "",
            "language": "",
            "device_price": "",
            "device_brand": "",
            "os": "",
            "platform_version": ""
        },
        "custom_user_props": {
            "profile_name_a": "a",
        },
        "user_tag_props": {
            "66 (tag_66)": "2022-12-14 00:00:00.000",
            "77 (tag_77)": 7
        }
    }
}

4.获取用户的行为流

4.1 API 定义

Path：/openapi/v1/{app_id}/behaviors/flows
Method: POST
Content-type: application/json
Body:

Parameter	Type	Description	Required
query_type	str	查询口径类型	true
query_id	str	查询id	true
orientation	str	根据时间戳向前或向后查询，可选earlier	later	true
timestamp	int	需要查询的13位毫秒级时间戳	true
count	int	单次查询多少条行为，建议值为1000，最多支持5000；	true
current_earliest_timestamp	int	已知的最早一条行为发生的时间戳 *若该参数不传递或传递为0，当根据时间戳向前搜索并发现找不到任何行为时，会自动定位到该用户可查询的最早一条行为	false

Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "flow": [
            {
                "server_time": 1674889013,
                "time": 1674889013,
                "event_date": "2023-01-28",
                "event": "event_1",
                "app_name": "bytefinder",
                "app_id": 2174,
                "user": {
                    "user_unique_id": "test_1",
                    "web_id": "",
                    "ssid": "172020d7-2261-47d8-ae0d-5721d4445f79",
                    ...
                },
                "params": {
                    "$is_login": "已登录",
                    ...
                },
                "items": {},
                "local_time_ms": 1674889013000,
                "event_name": "event_1",
                "repetition_cnt": 1
            }],
        "is_reorientation": false,
        "is_earliest": false,
        "is_latest": false,
        "general_preset_params": [
            "$data_validation_test",
            ...
        ],
        "platform_types": "web"
    }
}

Field	Type	Description
flow	list	行为流
is_reorientation	bool	是否自动重定向到最早一条行为
is_latest	bool	是否已经是最新的行为了
is_earliest	bool	是否已经是最早的行为了
general_preset_params	list	行为流中包含的事件属性中，预置属性的列表
platform_types	str	app所属的端类型

4.2 OpenAPI SDK 样例

bc 为创建的 RangersClient, 其初始化请参考 “OpenAPI SDK 使用说明”，各语言的 SDK 都提供了类似的接口

调用(Python)：：

body={
    "query_id": "test_1",
    "query_type": "user_unique_id",
    "count": 1000,
    "orientation": "earlier",
    "timestamp": 1674889321177,
    "current_earliest_timestamp": null
}
res = bc.data_finder('/openapi/v1/12345/behaviors/flow', body=body)
print(res.content)

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "flow": [
            {
                "server_time": 1674889013,
                "time": 1674889013,
                "event_date": "2023-01-28",
                "event": "event_1",
                "app_name": "bytefinder",
                "app_id": 12345,
                "user": {
                    "user_unique_id": "test_1",
                    "web_id": "",
                    "ssid": "172020d7-2261-47d8-ae0d-5721d4445f79",
                    "app_channel": "unknown",
                    "user_register_ts": 1670315402,
                    "device_model": "unknown",
                    "ab_version": [],
                    "network_carrier": "unknown",
                    "app_version": "unknown",
                    "network_type": "unknown",
                    "os_version": "unknown",
                    "os_name": "unknown",
                    "package": "unknown",
                    "loc_province_id": "河北",
                    "browser": "unknown",
                    "loc_city_id": "张家口",
                    "language": "unknown",
                    "resolution": "unknown",
                    "app_language": "unknown",
                    "loc_country_id": "中国",
                    "browser_version": "unknown",
                    "user_id": "test_1",
                    "bd_did": "",
                    "brand": "unknown"
                },
                "params": {
                    "$is_login": "已登录",
                    "error_param_code": 0,
                    "error_count": 128,
                    "error_event_code": 1010006,
                    "error_platform": "Android",
                    "error_param_name": "",
                    "error_sdk_version": "6090690",
                    "error_app_id": 168436,
                    "error_event_name": "bav2b_click"
                },
                "items": {},
                "local_time_ms": 1674889013000,
                "event_name": "data_quality_error_statistics",
                "repetition_cnt": 1
            }],
        "is_reorientation": false,
        "is_earliest": false,
        "is_latest": false,
        "general_preset_params": [
            "$data_validation_test",
            "$event_name",
            "$event_time",
            "$is_first_day",
            "$is_login",
            "$latest_referrer",
            "$latest_referrer_host",
            "$latest_search_keyword",
            "$latest_traffic_source_type",
            "$tr_web_ssid",
            "$user_register_time",
            "__sdk_platform",
            "bddid",
            "event_date",
            "server_time",
            "user_register_ts",
            "user_unique_id",
            "web_id",
            "wechat_unionid",
            "$extra",
            "referer_full_domain",
            "$app_channel",
            "$deeplink_url",
            "$source_platform",
            "app_name",
            "referer_site_name",
            "referer_type",
            "scene",
            "session_duration",
            "title",
            "url",
            "url_full_domain",
            "url_path",
            "visit_from_outside",
            "$is_first_time",
            "$page_duration",
            "$app_version",
            "$cpu",
            "$crash_process",
            "$crash_thread",
            "$detailed_stack",
            "$device_model",
            "$is_backstage",
            "$os_version",
            "$resolution",
            "$rom",
            "$session_duration",
            "$link_type",
            "ssid",
            "error_app_id",
            "error_count",
            "error_event_code",
            "error_event_name",
            "error_param_code",
            "error_param_name",
            "error_platform",
            "error_sdk_version",
            "event_type",
            "message_id",
            "description",
            "message_type",
            "media_id",
            "pic_url",
            "latitude",
            "longitude",
            "precision",
            "location_x",
            "location_y",
            "scale",
            "key",
            "thumb_media_id",
            "content",
            "$inactive",
            "$inline",
            "$source_uuid",
            "$url_query",
            "currency_amount",
            "session_no",
            "session_start_time",
            "$task_unit_id",
            "$target_uuid_list"
        ],
        "platform_types": "web"
    }
}

5. 创建用户列表的查询id

5.1 API 定义

Path：/openapi/v1/{app_id}/user_analysis/queries
Method: POST
Content-type: application/json
Body:

Parameter	Type	Description	Required
profile_names	list	需要查询的用户属性名列表传null时，会自动查询20个用户属性传[]时，不会查询任何用户属性如果只关心用户id，强烈建议传[]以加快查询速度	false
id_types	list	需要查询的id类型，按照逗号（,）进行分割	false
query_type	str	用户列表的查询类型，包括： analysis，显微镜功能 cohort，分群功能	true
analysis	object	当query_type为analysis时，该字段需要传dsl	query_type为analysis时必须
cohort	object	当query_type为cohort时，该字段需要传分群id	query_type为cohort时必须
limit	int	查询数量，暂时强制为1000无法修改	false

Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "query_id": "za9fa417b308a1c8e01"
    }
}

Field	Type	Description
query_id	str	用户列表的查询id

5.2 OpenAPI SDK 样例

bc 为创建的 RangersClient, 其初始化请参考 “OpenAPI SDK 使用说明”，各语言的 SDK 都提供了类似的接口

调用(Python)：：

body={
    "analysis": {
        "dsl": {省略}
    },
    "limit": 1000,
    "profile_names": [],
    "query_type": "analysis"
}
res = bc.data_finder('/openapi/v1/12345/user_analysis/queries', body=body)
print(res.content)

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "query_id": "za9fa417b308a1c8e01"
    }
}

5.3 创建analysis类型的用户列表查询id

从各种高级分析的显微镜创建的用户列表查询id为analysis类型。analysis中的dsl可以从前端获取，如下图：

5.4 创建cohort类型的用户列表查询id

从分群创建的用户列表id为cohort类型。cohort类型时，body参数可以如下填写：

{
    "cohort": {
        "cohort_id": <cohort_id: int>
    },
    "query_type": "cohort"
}

6. 根据查询id获取结果

6.1 API 定义

Path：/openapi/v1/{app_id}/user_analysis/queries/<query_id>
Method: GET
Content-type: application/json

Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "query_result": {
            "profiles": [
                {
                    "user_id_type": "user_unique_id",
                    "show_user_id": "278145",
                    "stat_standard_id": "95a3de81-61ce-454e-90f0-7b7b1144c148",
                    "user_id": "278145",
                    "device_id": "9223372036854775807",
                    "web_id": "7049540563264423427",

                }
            ],
            "total": 323,
            "result_length": 323,
            "page": 0,
            "page_size": 1000
        },
        "show_option": {
            "query_type": "analysis",
            "profile_names": [
            ],
            "profile_sort": [],
            "limit": 1000,
            "id_types": [
                "ssid",
                "user_unique_id",
                "device_id",
                "web_id"
            ],
            "analysis": {
                "dsl": {省略}
            }
        }
    }
}

Field	Type	Description
query_result	object	用户列表的查询id
query_result.total	int	用户列表的总数
query_result.result_length	int	本次查询结果的总数，与limit有关，当limit为1000时最多为1000
query_result.profiles	list	用户列表的详情，list中每个元素代表一个用户，返回用户id信息、用户属性等字段
page	int	分页页码，默认为0
page_size	int	分页页数，默认为20，不能超过查询的limit，最多为1000
show_option	object	返回了创建该query_id时的基本信息

6.2 OpenAPI SDK 样例

bc 为创建的 RangersClient, 其初始化请参考 “OpenAPI SDK 使用说明”，各语言的 SDK 都提供了类似的接口

调用(Python)：：

res = bc.data_finder('/openapi/v1/12345/user_analysis/queries/za9fa417b308a1c8e01')
print(res.content)

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "query_result": {
            "profiles": [
                {
                    "user_id_type": "user_unique_id",
                    "show_user_id": "278145",
                    "stat_standard_id": "95a3de81-61ce-454e-90f0-7b7b1144c148",
                    "user_id": "278145",
                    "device_id": "9223372036854775807",
                    "web_id": "7049540563264423427",

                }
            ],
            "total": 323,
            "result_length": 323,
            "page": 0,
            "page_size": 1000
        },
        "show_option": {
            "query_type": "analysis",
            "profile_names": [
            ],
            "profile_sort": [],
            "limit": 1000,
            "id_types": [
                "ssid",
                "user_unique_id",
                "device_id",
                "web_id"
            ],
            "analysis": {
                "dsl": {省略}
            }
        }
    }
}

7. 根据查询id流式导出

7.1 API 定义

Path：/openapi/v1/{app_id}/user_analysis/files/<query_id>
Method: GET
Content-type: application/json
Response:
注意：

response的content/type为text/csv;charset=utf-8
response通过流式传输

当query_id对应的query_type为cohort时，response为：

[分群名称]:{分群名}
[编辑者]:{编辑人名}
[分群用户数]:{分群数量}
用户ID,stat_standard_id,device_id,web_id
{},{},{},{}
{},{},{},{}
{},{},{},{}

当query_id对应的query_type为analysis时，response为：

用户ID,stat_standard_id,device_id,web_id
{},{},{},{}
{},{},{},{}
{},{},{},{}

7.2 OpenAPI SDK 样例

bc 为创建的 RangersClient, 其初始化请参考 “OpenAPI SDK 使用说明”，各语言的 SDK 都提供了类似的接口

调用(Python)：：

res = bc.data_finder('/openapi/v1/12345/user_analysis/files/za9fa417b308a1c8e01')
for content in res.iter_lines():
    print(content.decode("utf-8"))

返回结果：

用户ID,stat_standard_id,device_id,web_id
7039603993451071012,ce4f5339-b261-4567-ac87-b9e560ce5f71,0,7039603993451071012
256065,5c188cbd-9066-4c3f-817b-3656ed2d32eb,0,6981656913172432419
270159,619619ce-788e-4058-acf4-82063ca81374,0,7040148471437133327
...
...
...
204677,aa67d722-6af4-41f1-9b0c-e478553a0d4e,0,6981289846937978399
243118,58e53ded-b220-4978-99ac-ee7137210b23,0,6970956560466134558