API上传说明文档

API 上传方式仅适合上传超过 10 个 CS 字段的客户使用。10 个字段之内的客户推荐使用 SDK 方式进行上传。

接口说明

为了接口安全，我们会为您分配三个认证字段：

• projectKeyId: 由 GrowingIO 分配给您的项目 ID. 使用管理员及以上权限登录在项目管理中可以看到项目ID. 也简称为 ai
• secretKey: 由 GrowingIO 分配给您的项目的传输用私钥
• publicKey: 由 GrowingIO 分配给您的项目的传输用公钥

以上三个字段，可在「项目管理-项目配置-CS 配置」页面中查看。此key分配后，联调测试通过后才会正式环境上启用。

接口联调测试

请使用地址：testdata.growingio.com 替换文档中 data.growingio.com 来进行联调测试。

用户属性数据上传接口

协议：HTTPS
方法：POST
URL：https://data.growingio.com/saas/{projectKeyId}/user?auth={auth_token, 算法参见后续文档}

Headers:

• Access-Token = publicKey
• Content-Type = application/json

数据：

备注：

• 上传后对数据生效：不会覆盖历史数据，当用历史数据进行分析时，CS 字段的值仍保留历史时间的值
  举例：在 2014-2015 年，CS3 的值为 A，当前值为 B。当对 2014-2015 年的数据进行分析时，CS3值为A

• 覆盖历史数据生效：会以当前的字段值覆盖历史上的所有值，不保留历史数据

• 对于未登陆用户（访客用户），请不要上传用户 ID（例如：userid:0）,以及其他属性字段

• 对于注册用户，请不要漏传某些字段。
  举例：cs3字段代表手机号码，一部分用户没有手机号码。请上传「无」「-」...等方便您自己辨识意义的字符

格式：
一次上传多条记录：
举例：

[
  {
    "cs1": "user_id:12345",
    "cs2": "tenant_id:67890",
    "cs3": "rep_id:13579"
  },
  {
    "cs1": "user_id:12346",
    "cs2": "tenant_id:67891",
    "cs3": "rep_id:13580"
  },
  ...
]

一次上传单条记录：
举例：

{
  "cs1": "user_id:12346",
  "cs2": "tenant_id:67891",
  "cs3": "rep_id:13580"
}

数据大小：单个请求上传的数据包总大小不超过1MB，内含json对象不超过100个

返回值（status code）：
成功：

• 200, message = “Data uploaded.”

失败：

• 400
  message = “Authentication failed.”
  message = “Request too large.”
  message = “Project not found.”

公司属性数据上传接口（SaaS 企业适用）

您可以使用该接口上传相关的公司和用户属性，并且在 SDK 中上传cs1，cs2字段。这样我们就能够将您上传的数据进行绑定。运用这样的方式能够大大提高您的上传效率，减少您发送的数据量。

协议：HTTPS
方法：POST
URL：https://data.growingio.com/saas/{projectKeyId}/company?auth={auth_token, 算法参见后续文档}

Headers:
Access-Token = publicKey
Content-Type = application/json
数据：

格式：序列化的json对象
举例：

[
  {
    "cs2": "tenant_id:67890",
    "cs3": "rep_id:13579",
  },
  {
    "cs2": "tenant_id:67891",
    "cs3": "rep_id:13580",
  },
  ...
]

也支持单个json对象，例如

{
  "cs2": "tenant_id:67891",
  "cs3": "rep_id:13580",
}

auth_token的计算方式

• projectKeyId: 由GrowingIO分配给您的项目ID

• secretKey：由GrowingIO分配给您的私钥

• keyArray：
  • 对于一次上传多条记录时，取多条数据中的每个对象的主键的值（User接口为CS1，Company接口为CS2），并用逗号连接成为一个字符串
  • 对于一次上传单条记录时，取该对象的主键的值（User接口为CS1，Company接口为CS2）

Java:

public String authToken(String projectKeyId, String secretKey, String keyArray) throws Exception {
    String message = "ai="+projectKeyId+"&cs="+keyArray;
    Mac hmac = Mac.getInstance("HmacSHA256");
    hmac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"));
    byte[] signature = hmac.doFinal(message.getBytes("UTF-8"));
    return Hex.encodeHexString(signature);
}

Scala:

def authToken(projectKeyId: String, secretKey: String, keyArray: String): String = {
  val message = s"ai=$projectKeyId&cs=$keyArray"
  val hmac: Mac = Mac.getInstance("HmacSHA256")
  hmac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"))
  val signature = hmac.doFinal(message.getBytes("UTF-8"))
  Hex.encodeHexString(signature)
}

Python：

#coding:utf-8 
import hashlib
import hmac

def authToken(projectKeyId,secretKey,keyArray):
    message = ("ai=" + projectKeyId + "&cs=" + keyArray).encode('utf-8')
    signature = hmac.new(bytes(secretKey.encode('utf-8')), bytes(message), digestmod=hashlib.sha256).hexdigest()
    return signature

PHP:

function authToken($projectKeyId, $secretKey, $keyArray)
{
   $message="ai=".$projectKeyId."&cs=".$keyArray;
   return hash_hmac('sha256',$message, $secretKey, false);
}

举例：对于上述的json

{
  "cs1": "user_id:12346",
  "cs2": "tenant_id:67891",
  "cs3": "rep_id:13580"
}

对应keyArray 的值是user_id:12346

用户属性字段的新增和修改说明

以下情况下，您需要在「项目管理-CS 配置」页面进行更新，确保您 CS 数据的准确性：

1. 新增任何一个CS字段
2. 对任何一个CS字段的名称和意义进行修改
3. 对CS字段的值进行重新传输

注：当您对新应用上传所属项目下的相同字段时，不需要重新进行配置。