# 用户档案

## 1 单用户属性明细

根据用户ID获取用户属性数据。

5.2可支持获取标签属性，并且新增了新的接口：[根据方舟ID获取用户属性](/integration/api/api-cohort/api_user.md#4-gen-ju-fang-zhou-id-huo-qu-yong-hu-ming-xi)，可根据distinctId或者xwho任一维度获取用户明细。

### 1.1 接口地址

【POST】 /uba/api/cohort/users/{xwho}

{% hint style="info" %}
xwho 表示用户ID，取用户属性ID为xwho的值，传参方式：path variable，非request body
{% endhint %}

### 1.2 请求参数示例

```haskell
{
    //【选填】这里表示不指定，默认获取方舟系统所有可用的用户属性
    "properties":[],
    //【选填】5.2版本新增，要获取的标签code，如果不指定则不获取任何标签内容
  	"tags":[
      	//标签参数包含code和version两个部分，version可以不指定，不指定时默认获取最新标签
        {"code":"tag_3", "version":"2020-11-01"},
        {"code":"tag_4"},
        {"code":"tag_6"}
    ]
}
```

> **properties**：指定需要的用户属性列，传入用户属性ID，可以通过方舟系统或者 [元数据管理](/integration/api/api-manage-project/api-meta.md)-[用户属性](/integration/api/api-manage-project/api-meta.md#1-huo-qu-yong-hu-shu-xing) 接口获取用户属性列表。不指定默认查询方舟系统【元数据管理 - 用户属性】中 可见 的所有用户属性。
>
> **认证参数**：接口必传token和appKey两个参数，详情见 [项目接口认证](/integration/api.md#21-xiang-mu-jie-kou-ren-zheng)。

### 1.3 返回结果示例

```java
{
        "$imei": null,
        "chuangke_topic": null,
        "$first_visit_language": "zh-cn",
        "$city": null,
        "$email": null,
        "$platform": "JS",
        "chuangke_region": null,
        "chuangke_createtime": null,
        "$country": null,
        "$first_visit_time": 1557403591272,
        "phone": null,
        "$province": null,
        "$signup_time": null,
        "$mac": null,
        "company_code": null,
        "xwho": "JSd650856937040a530ff54fdaab4e56d7d650",
        "email": null,
        //如果请求参数中包含标签，则返回内容中会包含标签内容，标签内容和用户属性相比，返回的key会以tag.xxx开头
  		  "tag.tag_3":"男",
  		  "tag.tag_4":"高价值用户",
  		  "tag.tag_6":null
    }
```

### 1.4 接口调用示例

```java
curl -H "Content-Type:application/json" -H "token:4113c9cad1c301113783f433e254888c" -H "appKey:31abd9593e9983ec" -X POST --data '{
    "properties":[]
}' http://127.0.0.1:4005/uba/api/cohort/users/JSd650856937040a530ff54fdaab4e56d7d650
```

## **2. 单用户行为序列**

根据用户ID查看单用户某段时间内的行为轨迹，按发生时间倒序，包含发生事件和对应事件属性。

此接口适用于查询小数据量的场景，一般建议不超过100条行为记录。如果需要导出或者获取更多行为，可通过 [单用户行为序列导出接口](/integration/api/api-cohort/api_user.md#3-dan-yong-hu-hang-wei-xu-lie-dao-chu) 获取。

5.2新增了新的接口：[根据方舟ID获取用户行为序列](/integration/api/api-cohort/api_user.md#5-gen-ju-fang-zhou-id-huo-qu-yong-hu-hang-wei-xu-lie)，可根据distinctId或者xwho任一维度获取行为轨迹。

### **2.1 接口地址**

> 【POST】 /uba/api/cohort/users/{xwho}/sequence

xwho 表示用户ID，取用户属性ID为xwho的值，传参方式：path variable

### **2.2 请求参数示例**

```java
{
    //【必填】 时间范围-开始时间
    "fromDate":"2019-06-18",
    //【必填】 时间范围-结束时间
    "toDate":"2019-06-20",
    //【选填】指定事件范围，对应事件ID，不传默认查询指定时间范围内的所有发生事件
    "events":[],
    //查看多少条行为记录 默认为100
    "limit":100,
    //使用缓存 这里表示是
    "useCache":true,
}
```

> **认证参数**：接口必传token和appKey两个参数，详情见 [项目接口认证](/integration/api.md#21-xiang-mu-jie-kou-ren-zheng)。

### **2.3 返回结果示例**

```java
{
    //事件行为列表
    "rows": [
        {
            //事件ID
            "eventId": "$pageview",
            //事件发生时间
            "eventTime": "2020/02/12 21:08:38",
            //事件下的属性
            "properties": {
                "$browser_version": "Chrome 80.0.3987.100",
                "$utm_medium": null,
                "$network": null,
                "$os": "Mac OS X",
                "$platform": "JS",
                "$carrier_name": null,
                "$ip": "111.197.233.250",
                "project_name": "用户数据权限(勿删)",
                "$screen_height": 1050,
                "$referrer": "https://arkpaastest.analysys.cn:4005/project-management/member-management",
                "$user_agent": null,
                "$language": "zh",
                "$is_login": 1,
                "$province": "北京",
                "$url": "https://arkpaastest.analysys.cn:4005/project-management/role-management",
                "company": "企业管理",
                "company_code": null,
                "tag": null,
                "$device_type": null,
                "$traffic_source_type": "direct",
                "demo_type": null,
                "$os_version": "Mac OS X 10.15.3",
                "$search_engine": null,
                "$web_crawler": 0,
                "$is_first_day": 0,
                "$city": "北京",
                "$model": null,
                "$screen_width": 1680,
                "$channel": null,
                "$brand": null,
                "$utm_source": "direct",
                "$browser": "Chrome",
                "$url_domain": "https://arkpaastest.analysys.cn:4005/project-management/role-management",
                "$app_version": null,
                "$lib": "JS",
                "$country": "中国",
                "$utm_campaign": null,
                "$title": "易观方舟",
                "$utm_content": null,
                "$lib_version": "4.2.0.1",
                "$referrer_domain": "arkpaastest.analysys.cn",
                "$search_keyword": null,
                "$manufacturer": null,
                "$session_id": "14a851b749ab64ca"
            }
        }
    ],
    //查询时间
    "reportUpdateTime": "2020-02-14 15:33:54"
}
```

### **2.4 接口调用示例**

```javascript
curl -H "Content-Type:application/json" -H "token:4113c9cad1c301113783f433e254888c" -H "appKey:31abd9593e9983ec" -X POST --data '{
  "fromDate":"2020-02-06",
    "toDate":"2020-02-12",
    "events":[],
    "limit":100,
    "useCache":true
}' http://127.0.0.1:4005/uba/api/cohort/users/JSd650856937040a530ff54fdaab4e56d7d650/sequence
```

## 3 单用户行为序列导出

5.0版本中新增

适用于需要导出或者获取更多(百万级以下)的用户行为轨迹场景，返回接口使用的是流式输出。

### 3.1 接口地址

> 【POST】 /uba/api/cohort/users/{xwho}/sequence/export

xwho 表示用户ID，取用户属性ID为xwho的值，传参方式：path variable

### 3.2 请求参数

```java
{
    //【必填】 时间范围-开始时间
    "fromDate":"2019-06-18",
    //【必填】 时间范围-结束时间
    "toDate":"2019-06-20",
    //【选填】指定事件范围，对应事件ID，不传默认查询指定时间范围内的所有发生事件
    "events":[],
    //使用缓存 这里表示是
    "useCache":true,
}
```

> 认证参数：接口必传token和appKey两个参数，详情见 [项目接口认证](/integration/api.md#21-xiang-mu-jie-kou-ren-zheng)。

### 3.3 返回结果示例

```javascript
{"$app_version":"(已脱敏)",......,"$os_version":"Mac OS X 10.15.2","xwhat":"$pageview","$lib":"JS"}
{"$app_version":"(已脱敏)",......,"$os_version":"Mac OS X 10.15.2","xwhat":"$search","$lib":"JS"}
{"$app_version":"(已脱敏)",......,"$os_version":"Mac OS X 10.15.2","xwhat":"$click","$lib":"JS"}
```

> 1. 因为可以支撑大数据量，为了方便客户端可以进行批次处理，json类型的输出并非是一个完整的json数组，而是一行一条json（无`[]`,按`\n`分割）
> 2. 因为可以支撑大数据量，接口response为 流式输出。如果是通过程序来调用，那么建议：
>    * 建议一：避免一次性加载response到内存中，改为流式接收 response body
>    * 建议二：`Http Connection` 需要增加`SocketTimeout`时长，同时修改nginx 超时配置
> 3. 关于流式导出类型API的java 客户端调用示例可以参考 [【API-自定义sql查询】](https://app.gitbook.com/s/-LaKVSdcX30MGZ24jKF_/integration/api/analytics/api-sql-query.md)的第2.5章节

### 3.4 接口调用示例

导出`xwho=JS7daf4d2bfa06b1723346b884ce986f8a7daf`的3月6日到16日之间的所有行为数据，输出写入到output.json 文件中

```haskell
curl -o output.json -H "Content-Type:application/json" -H "token:3edbaf427ecdda80beef322ad3c333a4" -H "appKey:31abd9593e9983ec" -X POST --data '{
  "fromDate":"2020-03-06",
    "toDate":"2020-03-16",
    "events":[],
    "useCache":true
}' https://127.0.0.1:4005/uba/api/cohort/users/JS7daf4d2bfa06b1723346b884ce986f8a7daf/sequence/export
```

关于流式导出类型API的java 客户端调用示例可以参考 [【API-自定义查询-Java HttpClient 接口调用示例](/integration/api/api-analytics/api_sql_query.md#25-java-httpclient-jie-kou-tiao-yong-shi-li)】

## 4 根据方舟ID获取用户明细

此接口和[单用户明细](/integration/api/api-cohort/api_user.md#1-dan-yong-hu-shu-xing-ming-xi)接口对比，参数从url上移到了参数体内，增加了可以通过方舟ID-distinctId获取用户属性；其他调用此接口的认证参数、获取用户明细内容参数规则和输出结果格式保持一致。

### 4.1 接口地址

【POST】 /uba/api/users/personal

### 4.2 请求参数

```haskell
{
  	//【和xwho二选一】方舟ID，对应表中的distinct_id
    "distinctId": -2522510769241542144,
  	//【和distinctId二选一】用户ID，对应xwho
    "xwho":null,
    //【选填】要获取的用户档案字段，如果不指定表示获取此用户的所有档案数据
		"properties": [
        "xwho",
        "distinct_id",
        "$first_visit_language",
        "$platform"
    ],
  	//【选填】要获取的标签code，如果不指定则不获取任何标签内容
  	"tags":[
      	//标签参数包含code和version两个部分，version可以不指定，不指定时默认获取最新标签
        {"code":"tag_3", "version":"2020-11-01"},
        {"code":"tag_4"},
        {"code":"tag_6"}
    ]
}
```

## 5 根据方舟ID获取用户行为序列

此接口和 [单用户行为序列](/integration/api/api-cohort/api_user.md#2-dan-yong-hu-hang-wei-xu-lie) 接口对比，参数从url上移到了参数体内，增加了可以通过方舟ID-distinctId获取用户行为数据；其他调用此接口的认证参数、获取用户明细内容参数规则和输出结果格式保持一致。

### 5.1 接口地址

> 【POST】 /uba/api/users/sequence

### 5.2 请求参数

```haskell
{
  	//【和xwho二选一】方舟ID，对应表中的distinct_id
    "distinctId": -2522510769241542144,
  	//【和distinctId二选一】用户ID，对应xwho
  	"xwho":null,
    //【必填】 时间范围-开始时间
    "fromDate":"2019-06-18",
    //【必填】 时间范围-结束时间
    "toDate":"2019-06-20",
    //【选填】指定事件范围，对应事件ID，不传默认查询指定时间范围内的所有发生事件
    "events":["$Anything"],
    //查看多少条行为记录 默认为100
    "limit":100,
    //使用缓存 这里表示是
    "useCache":true,
}
```

> 行为序列导出接口：【POST】 /uba/api/users/sequence/export


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://arkdocs.analysys.cn/integration/api/api-cohort/api_user.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.