用户属性上传 API

通过 Ptengine API，您可以将用户属性信息批量上传到 Ptengine，用于后续的用户分群分析等功能。

本 API 基于 REST 架构构建，接受 JSON 格式的请求体，并返回 JSON 编码的响应。

---

1. 认证

获取 API Key

在 Ptengine 的「Integration（集成）」页面获取或新建 API Key。

API Key 按项目发放，每个项目需要单独创建。

保护 API Key

API Key 是机密信息，请勿在浏览器或移动应用等客户端代码中暴露。建议通过后端服务器发送请求，从环境变量或密钥管理服务中安全读取 Key。

所有 API 请求都需要在 HTTP 请求头中包含 API Key：

Authorization: Bearer PTENGINE_API_KEY

---

2. API 规格

项目	内容
API URL	https://api.ptengine.com/v1/user/profiles
协议	HTTPS
请求方法	POST
数据格式	JSON

单次请求最多可同时上传 100 个用户及其属性数据。

---

3. 请求体

请求体包含以下两个字段：

字段名	数据类型	是否必填	说明	限制
field_name	String[]	是	用户属性键名的数组，必须包含 user_id	最多 50 个字段，每个属性名最长 50 个字符
values	Array[]	是	包含用户属性值的二维数组，顺序必须与 field_name 对应。空值用 "" 表示	最多 100 个用户，每个属性值最长 128 个字符

---

4. 更新策略

每个请求必须包含 user_id（用户唯一标识符）。Ptengine 通过 user_id 判断用户是否已存在，并按以下规则处理：

用户状态	属性状态	更新策略
存在	存在	更新已有的属性
存在	不存在	为该用户新建属性
不存在	/	新建用户及其属性

---

5. 请求示例

假设你想上传以下用户属性：

user_id	watch_conan	watch_attack_on_titan
abcd123	yes	no
abcd456	yes	yes
abcd789	no	no

请求体如下：

{
  "field_name": [
    "user_id",
    "watch_conan",
    "watch_attack_on_titan"
  ],
  "values": [
    ["abcd123", "yes", "no"],
    ["abcd456", "yes", "yes"],
    ["abcd789", "no", "no"]
  ]
}

values 的顺序必须与 field_name 的顺序一致。

---

6. 各语言代码示例

发送请求前，请将 <API_KEY> 替换为你的实际 API Key。

Python

import requests
import json

url = "https://api.ptengine.com/v1/user/profiles"

payload = json.dumps({
  "field_name": [
    "user_id",
    "watch_conan",
    "watch_attack_on_titan"
  ],
  "values": [
    ["abcd123", "yes", "no"],
    ["abcd456", "yes", "yes"],
    ["abcd789", "no", "no"]
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <API_KEY>'
}

response = requests.post(url, headers=headers, data=payload)
print(response.json())

Node.js

const axios = require('axios');
let data = JSON.stringify({
  "field_name": [
    "user_id",
    "watch_conan",
    "watch_attack_on_titan"
  ],
  "values": [
    ["abcd123", "yes", "no"],
    ["abcd456", "yes", "yes"],
    ["abcd789", "no", "no"]
  ]
});

let config = {
  method: 'post',
  url: 'https://api.ptengine.com/v1/user/profiles',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <API_KEY>'
  },
  data: data
};

axios(config)
  .then(response => console.log(response.data))
  .catch(error => console.log(error));

PHP

<?php
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer <API_KEY>'
];
$body = '{
  "field_name": ["user_id", "watch_conan", "watch_attack_on_titan"],
  "values": [
    ["abcd123", "yes", "no"],
    ["abcd456", "yes", "yes"],
    ["abcd789", "no", "no"]
  ]
}';
$request = new Request('POST', 'https://api.ptengine.com/v1/user/profiles', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

Java

OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,
  "{\"field_name\":[\"user_id\",\"watch_conan\",\"watch_attack_on_titan\"],"
  + "\"values\":[[\"abcd123\",\"yes\",\"no\"],"
  + "[\"abcd456\",\"yes\",\"yes\"],"
  + "[\"abcd789\",\"no\",\"no\"]]}");
Request request = new Request.Builder()
  .url("https://api.ptengine.com/v1/user/profiles")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer <API_KEY>")
  .build();
Response response = client.newCall(request).execute();

Go

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://api.ptengine.com/v1/user/profiles"
  payload := strings.NewReader(`{
    "field_name": ["user_id", "watch_conan", "watch_attack_on_titan"],
    "values": [
      ["abcd123", "yes", "no"],
      ["abcd456", "yes", "yes"],
      ["abcd789", "no", "no"]
    ]
  }`)

  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Bearer <API_KEY>")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)
  fmt.Println(string(body))
}

---

7. 响应

成功

HTTP 状态码 200 OK

{
  "msg": "Success",
  "timestamp": 1684155980
}

失败

HTTP 状态码根据错误类型不同而不同。

{
  "msg": "The reason for the request failure",
  "timestamp": 1684155980
}

状态码参考

HTTP 状态码	说明
200 (OK)	请求成功
400 (Bad Request)	请求无法接受。可能缺少必要参数（例如 field_name 中未包含 user_id）
401 (Unauthorized)	API Key 无效或不正确
403 (Forbidden)	API Key 没有执行此请求的适当权限
404 (Not Found)	请求的资源不存在或 URL 不正确
500/502/503/504	Ptengine 服务器发生问题

---

8. 大量数据上传

单次请求最多可上传 100 个用户。如果用户数超过 100，请分批发送，每批最多 100 个。

例如，要上传 600 个用户的数据，请拆分为 6 次请求，每次 100 个用户。