数据上报 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": {
        "自定义属性1": 666,
        "自定义属性2": "字符串",
        "自定义属性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": {
            "自定义属性1": 666,
            "自定义属性2": "字符串",
            "自定义属性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" => [
            "自定义属性1" => 666,
            "自定义属性2" => "字符串",
            "自定义属性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: {
        "自定义属性1": 666,
        "自定义属性2": "字符串",
        "自定义属性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.json

8.2. 工具与资源

  • 提供在线工具链接，用于 Base64 编码、UrlEncode 编码和解码。
  • 提供 SDK 和数据导入工具的下载链接和使用指南。

结语

本手册提供了从数据生成到上报的完整流程，旨在帮助用户高效地将数据上报至海纳嗨数云服务平台。我们鼓励用户在遇到问题时联系技术支持，并定期查看更新，以获取最新的上报方法和最佳实践。感谢您选择海纳嗨数，让我们一起开启数据驱动的旅程。