海纳嗨数-帮助中心
数据上报API
数据上报 API
1. 前言
1.1. 简介
本手册旨在指导用户如何利用数据上报 API，高效、安全地将数据传输至海纳嗨数云服务平台。无论您是开发者还是数据分析师，本手册都将为您提供详尽的步骤和最佳实践。
文档将会为您介绍如何使用数据上报 API，可以在不依赖传输工具与 SDK 的情况下，使用
HTTP的POST方法直接向海纳嗨数云服务传输数据。
1.2. 推荐使用方式
通常情况下，不建议自己实现本手册的接入流程，我们推荐使用海纳嗨数提供的 SDK 或数据导入工具来完成数据采集。这可以避免未知问题，并方便您在未来使用新功能。例如，如果您使用的编程语言没有对应的 SDK，可以考虑使用其他批量导入工具。
2. 准备工作
在开始数据上报之前，请确保您已经具备以下条件：
- 对海纳嗨数的数据格式和规则有充分了解。
- 拥有一个有效的海纳嗨数云服务账户，以及相应的项目名称（$project_name）和项目令牌（$project_token）。
3. 数据生成与格式
在开始对接前，您需要先阅读数据格式，在熟悉海纳嗨数的数据格式与数据规则后，再阅读参考本文档。
3.1. 数据格式要求
上报的数据应遵循 JSON 格式，每条数据记录应包含以下关键字段：
anonymous_id：匿名用户标识符（与account_id二选一，或者同时存在）。account_id：区分用户的唯一标识符（与anonymous_id二选一，或者同时存在）。event：事件名称，标识用户行为。time：事件发生的时间戳。(如果统计时需要用自己的时间来分析，例如订单时间，则需要将订单时间映射到此字段上)type：数据类型，通常为 “track”。_track_id：跟踪编号，标识事件的唯一编号。（主要用来防重放，事件的并发越高，唯一性要求越高）
注意：在上报业务数据时，请务必包含
properties字段，并添加H_lib属性，设其值为API，以便海纳云服务进行安全监控和事件识别。
3.2. 示例数据
[{
"anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
"account_id": "10001",
"event": "H_AppStart",
"time": 1704067200000,
"type": "track",
"_track_id": 123456,
"properties": {
"custom_attr_1": 666,
"custom_attr_2": "字符串",
"custom_attr_3": "2024-01-01 08:00:00",
"H_lib": "API"
}
}]4. 数据编码与压缩
3.1. Base64 编码
将 JSON 格式的数据进行 Base64 编码，以确保数据在传输过程中的兼容性和安全性。
- Gzip 压缩（可选）
先对 JSON 数据进行 Gzip 压缩，再对压缩数据进行 Base64 编码。对于大量数据，推荐使用 Gzip 压缩来减少数据体积，提高传输效率。
3.2. UrlEncode 编码
对 Base64 编码后的数据进行 UrlEncode，以适应 HTTP 请求的参数格式。
5. 构建 HTTP 请求
将编码后的数据和压缩标志（如果有）组装成 HTTP POST 请求。请求参数格式如下：
data_list=ENCODED_DATA&gzip=COMPRESSED_FLAG- data_list：UrlEncode 后的 Base64 编码数据。
- gzip：如果数据经过 Gzip 压缩，此处应标记为 1，否则为0。
6. 发送数据
使用 curl 或其他 HTTP 客户端工具发送构建好的请求到海纳嗨数的数据接收 API。
6.1. 使用 curl 发送数据示例
curl -v \
--data 'gzip=1&data_list=ENCODED_DATA' \
'https://higateway.haishuu.com/ha?project={$project_name}&token={$project_token}'请注意，海纳嗨数服务采用异步处理机制来接收和处理数据。这意味着在您成功发送数据之后，可能需要稍作等待，数据才会在系统中完全更新并可供查询。通常情况下，这个过程很快，但在数据量大或系统负载较高时，处理时间可能会有所延长。如果您对数据的实时性有特别要求，请提前规划或与我们的技术支持团队联系，以获取帮助和建议。
6.2. 使用 python 发送数据示例
import requests
import base64
import json
import gzip
import urllib.parse
# 假设 data 是一个包含 JSON 数据的字典列表
data = [
{
"anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
"account_id": "10001",
"event": "H_AppStart",
"time": 1704067200000,
"type": "track",
"_track_id": 123456,
"properties": {
"custom_attr_1": 666,
"custom_attr_2": "字符串",
"custom_attr_3": "2024-01-01 08:00:00",
"H_lib": "API"
}
}
]
# 将数据转换为 JSON 字符串并进行 Base64 编码
encoded_data = base64.b64encode(json.dumps(data).encode('utf-8')).decode('utf-8')
# 如果需要 Gzip 压缩
compressed_data = gzip.compress(encoded_data.encode('utf-8'))
encoded_compressed_data = base64.b64encode(compressed_data).decode('utf-8')
# 构建请求参数
params = {
'data_list': encoded_compressed_data if compressed_data else encoded_data,
'gzip': '1' if compressed_data else '0'
}
# 发送请求
# 请注意替换 YOUR_PROJECT_NAME 和 YOUR_PROJECT_TOKEN
response = requests.post(
'https://higateway.haishuu.com/ha?project=YOUR_PROJECT_NAME&token=YOUR_PROJECT_TOKEN',
data=params
)
# 检查响应
if response.ok:
print('发送成功:', response.text)
else:
print('发送失败:', response.text)6.3. 使用 PHP 发送数据示例
<?php
// 假设 $data 是一个包含 JSON 数据的数组
$data = [
[
"anonymous_id" => "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
"account_id" => "10001",
"event" => "H_AppStart",
"time" => 1704067200000,
"type" => "track",
"_track_id": 123456,
"properties" => [
"custom_attr_1" => 666,
"custom_attr_2" => "字符串",
"custom_attr_3" => "2024-01-01 08:00:00",
"H_lib" => "API"
]
]
];
// 将数据转换为 JSON 字符串并进行 Base64 编码
$json_data = json_encode($data);
$encoded_data = base64_encode($json_data);
// 如果需要 Gzip 压缩
$gzip_encoded_data = base64_encode(gzencode($json_data, 9));
// 构建请求参数
$project_name = 'YOUR_PROJECT_NAME'; // 替换为您的项目名称
$project_token = 'YOUR_PROJECT_TOKEN'; // 替换为您的项目令牌
$url = "https://higateway.haishuu.com/ha?project={$project_name}&token={$project_token}";
// 准备 POST 请求的参数
$params = [
'data_list' => $gzip_encoded_data ?: $encoded_data, // 使用 Gzip 压缩后的数据或原始数据
'gzip' => $gzip_encoded_data ? '1' : '0' // 标记是否进行了 Gzip 压缩
];
// 使用 cURL 发送 POST 请求
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
// 执行 POST 请求并获取响应
$response = curl_exec($ch);
$error = curl_error($ch);
// 关闭 cURL 资源
curl_close($ch);
// 检查错误并输出结果
if ($error) {
echo '发送失败: ' . $error;
} else {
echo '发送成功: ' . $response;
}
?>6.4. 使用 JavaScript 发送数据示例
// 假设 data 是一个包含 JSON 数据的对象
const data = {
anonymous_id: "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
account_id: "10001",
event: "H_AppStart",
time: 1704067200000,
type: "track",
_track_id: 123456,
properties: {
"custom_attr_1": 666,
"custom_attr_2": "字符串",
"custom_attr_3": "2024-01-01 08:00:00",
"H_lib": "API"
}
};
// 将数据转换为 JSON 字符串并进行 Base64 编码
const encodedData = btoa(JSON.stringify(data));
// 构建请求参数
const params = {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded'
},
body: `data_list=${encodedData}&gzip=0` // 假设没有使用 Gzip 压缩
};
// 使用 fetch 发送请求
// 请注意替换 YOUR_PROJECT_NAME 和 YOUR_PROJECT_TOKEN
fetch('https://higateway.haishuu.com/ha?project=YOUR_PROJECT_NAME&token=YOUR_PROJECT_TOKEN', params)
.then(response => response.json())
.then(data => console.log('发送成功:', data))
.catch((error) => console.error('发送失败:', error));7. 安全与合规性
- 确保所有传输的数据都符合数据保护法规和公司政策。
- 使用安全的连接（如 HTTPS）来保护数据在传输过程中的安全。
8. 附录
8.1. 反编码查看数据
如果需要查看已编码的数据内容，可以使用以下命令：
cat encoded_data | base64 -d | gzip -d > decoded_data.json8.2. 工具与资源
- 提供在线工具链接，用于 Base64 编码、UrlEncode 编码和解码。
- 提供 SDK 和数据导入工具的下载链接和使用指南。
结语
本手册提供了从数据生成到上报的完整流程，旨在帮助用户高效地将数据上报至海纳嗨数云服务平台。我们鼓励用户在遇到问题时联系技术支持，并定期查看更新，以获取最新的上报方法和最佳实践。感谢您选择海纳嗨数，让我们一起开启数据驱动的旅程。
