原始数据导出API V1.0

anwei • 发表于：2019年12月09日 10:57:37 • 更新于：2019年12月09日 10:58:54

原始数据导出API V1.0


概述

是否付费

数据保留时间

导出延迟

导出格式

时间

是

开通之日起最多15天

小时数据：30分钟。举例说明：xxxx

天数据：1-2小时。建议早上六点

gzip压缩包。

以每64M大小分包发送。


UTC时间

原始数据导出为付费功能，且只能导出从开通之日起的原始数据，原始数据仅保留15天，请定期下载。数据导出一般延迟为 30 分钟，比如早上 8 点到 9 点之间的数据，一般 9:30 会准备好。每天凌晨因为需要运行天级别的统计任务，所以导出任务会延迟 1-2 小时，在导出数据时请判断接口返回的 status 字段 。

导出时数据以每 64M 为单位分包发送，导出数据默认采用 gzip 压缩。原始数据中所有时间字段均为 UTC 时间，并非中国时间；此处导出的压缩包名也是由 UTC 时间命名。

使用流程

原始数据导出包括鉴权、获取连接、下载三个过程。



-Lo08UtW7H58ehFKeZ4g-Lp1sZNPgLCCmevimgtG-Lp1sadpDf1phjkJ7TGnimage.png


鉴权：获取Authorization，参考认证章节。

获取连接：获取请求API的响应中的downloadLinks，参见按事件类型导出原始数据和导出全部事件类型原始数据。

下载：通过“获取连接”获取到的链接下载文件。


一.字段说明

1.事件类型

原始数据导出API可导出的所有字段的事件分类如下：

V1.0可导出字段的事件分类有7种。

事件大类

事件小类

无埋点事件

visit、page、action、action_tag

埋点事件

custom_attr

广告相关

ads_track_click、ads_track_activation


2.无埋点事件字段


无埋点事件

visit

名称

类型（长度）

说明

userId

string（36）

用户ID。

正对单个用户生成的唯一ID。

示例：Web网站生成一个有效期3年的cookie值，App则为机器唯一标识码。

sessionId

string（36）

访问ID。

  • Web: 30分钟过期的session值，代表一次访问。

  • 移动端: App退出30秒后再进入，刷新session值。

  • 小程序：关闭5分钟再进入刷新session值。

示例：6b5099c7-6006-422d-92ac-4f3bf4ddd37c

sendTime

bigint

发送时间。

eventTime

bigint

事件发生事件

eventType

string（10）

事件类型

ip

string（64）


countryName

string（30）

国家名称。

用户所在的国家。

region

string（30）

省份。

用户所在的省份。

city

string（30）

城市。

用户所在的城市。

domain

string（100）

域名。

用户访问的网站域名。

path

string（512）

路径。

网站路径。

refer

string（1024）

来源链接

userAgent

string（1024）


appVersion

string（10）

客户的产品版本，仅限App端。

model

string（50）

用户的设备型号

manufacturer

string（50）

用户的设备生产产商。

示例：小米

channel

string（40）

下载渠道。

App的下载渠道，仅限移动端。

language

string（10）

语言。

用户使用的设备系统语言。

osVersion

string（50）

系统版本。

用户使用的设备系统版本。

resolution

string（20）

设备分辨率

用户使用的设备分辨率。

platform

string（10）

数据来源

平台区分该数据属于哪个平台。

示例：Web Android iOS

id

string（16）

访问事件ID

即visit_id，用于与page数据聚合，唯一标记visit事件。

query

string（512）

访问事件的query信息

访问时的连接中的query，与掐年的domain，path一起构建完整的链接。

lat

double

gps纬度

mobile平台，需要gps权限。？？？

lng

double

gps经度mobile平台独有的子弹，紧缺到小数点后5位。


page

名称

类型（长度）

说明

userId

string(36)

用户ID

针对单个用户生成的唯一id

例如，web网站生成一个有效期三年的cookie值，App 则为机器唯一标识码

sessionId

string(36)


sendTime

bigint

数据发送过来的时间

eventTime

bigint

事件实际发生的时间

eventType

string(15)

该消息的类型

page表内类型为page

domain

string(100)

用户访问的网站域名

path

string(512)

网站路径

query

string(512)

request请求中的查询参数

k1=v1&k2=v2

refer

string(1024)

该用户从refer所在地址跳转过来

title

string(1024)

页面名称

该网页名称，page title

platform

string(10)

区分该数据属于哪个平台：web, android, ios

cs1

string(200)

用户信息字段1

客户平台的登陆用户id：cs1，如果客户安装sdk时设置过cs1字段（上传用户属性字段集cs，cs1用于设置用户id）

cs2

string(200)

客户平台的项目id：cs2

cs3

string(200)


cs4

string(200)


cs5

string(200)


cs6

string(200)


cs7

string(200)


cs8

string(200)


cs9

string(200)


cs10

string(200)


id

string(23)

页面事件id

即page_id，用于与action数据聚合

唯一标记page事件

visit_id

string(16)

访问事件ID

即visit_id，用于与visit表数据聚合

。visit表内id

pagegroup

string(100)

页面组名称

需要在sdk集成时配置

用于标记设置的一组ps字段信息

ps1

string(200)

sdk配置的页面信息字段1

ps2

string(200)


ps3

string(200)


ps4

string(200)


ps5

string(200)


ps6

string(200)


ps7

string(200)


ps8

string(200)


ps9

string(200)


ps10

string(200)



action

  1. 三张数据表分别代表GIO定义的三种数据级别，访问级别（visit），页面级别（page）与标签级别（action）。visit代表访问级别的数据，按照session定义访问，page代表页面级别数据，打开的浏览页面就是一条记录，一条访问级别数据对应多条页面级别，action级别数据代表标签数据，定义页面元素标签的显示，点击，提交等事件，三者形成整个用户行为数据层级。目前导出的数据类型除了action下的imp(impression)类型因为数据量过大不可导出，其它数据都已经导出。

  2. sendTime与eventTime的区别在于前者相当于是GIO平台接收到的时间，而eventTime是事件在客户端真正发生的时间，客户可以根据eventTime重现用户操作时间线。

  3. 在refer中可以提取utm（广告链接关键字）或者搜索关键字等信息，用于分析访问来源。也可在visit表的query字段中提取utm信息。

  4. appVersion，model，manufacturer，channel，osVersion仅在mobile端提供，更多信息可以从userAgent中提取。

  5. 三张数据表可以根据“外键”join，分别是page_id与page表的id，visit_id与visit表的id，action_id单独提供。因为标签事件并不导出impression（显示级别）的数据（数据量太大的缘故），所以建议通过action full outer join page，visit与page基本保持对应，若是在小时级别page数据无法join到对应的visit记录，visit记录可能存在于之前的小时单位中。

  6. 所有数据已经根据userId, sessionId, sendTime进行排序，基本能够做到具体用户行为跟踪。

  7. mobile端浏览器打开页面访问，默认platform类型为Web，若是需要区分则建议根据osVersion。

  8. action数据中index，info为补充字段，参考changelog说明。

圈选数据映射关系

action_tag

rules

名称

类型

说明

sendTime

bigint

发送时间

数据发送过来的时间

action_id

string(30)

事件ID。

标签事件的唯一id web的action_id以wa开头，mobile以ma开头

rule_id

string(8)

规则ID。

匹配事件的规则id，该id为growingio平台圈选的标签的唯一id.

该值由字母与数字组成，例如‘1ba052a9’.

  1. 在基础部分数据导出（visit, page, action)之外，提供圈选数据与action级别数据的映射部分。

  2. 通过action数据中的action_id与action_tag中的action_id聚合，绑定对应的rule_id（映射的规则名称）到action数据上。

  3. rules代表了客户在GrowingIO平台上圈选的标签，rule_id即其唯一标识符。

  4. 通过rules表将名称绑定到上述的action_tag表中，便于通过名称进行数据分析，识别导出数据中圈选部分的数据情况。

  5. action_tag与rules表均是关联信息表，用于更进一步分析导出的部分数据，在导出数据中定位圈选数据。建议规则建立时保持名称的唯一性，GrowingIO平台不保证规则名称唯一性。

  6. 相同的规则名称下可能有多个规则类型，规则名称＋规则类型才能区分，此处的规则类型与基础数据action中的事件类型保持一致。


3.埋点事件与变量字段

custom_attr


sendTime

发送时间

bigint

数据发送过来的时间

示例

eventname

埋点事件名称

string

用户定义的埋点事件名称

管理平台内定义

attribute

埋点事件属性

string

埋点事件属性为json字符串

以_ 开头的字段为growingio相关定义字段，包括_sessionId，_userId，_domain，_eventTime等，其他为客户自定义的字段


custom_attr内attribute字段说明


列名

字段名称

字段格式

字段说明

值(example)

_userId

用户ID

string(36)

针对单个用户生成的唯一id

例如，web网站生成一个有效期三年的cookie值，mobile则为机器唯一标识码

_sessionId

会话ID

string(36)

"web: 30分钟过期的session值，代表一次会话。mobile: app退出30秒后再进入，刷新session值"


_eventTime

事件发生时间

bigint

事件实际发生的时间


_domain

域名

string(100)

用户访问的网站域名

www.growingio.com

_path

路径

string(512)

网站路径

/login

_query

访问事件的query信息

string(512)

访问时的链接中的query，与前面的domain，path一起构建完整的链接


_cs1

自定义用户信息字段1

string(200)

客户平台的登陆用户id：cs1，如果客户安装sdk时设置过cs1字段（上传用户属性字段集cs，cs1用于设置用户id）

cs1默认用于标记登陆用户ID， userid:12345

xxx

用户打点字段

string / double

客户自定义的打点字段，这部分字段最多有30个字段

所有自定义的打点字段，不同的事件有不同的定义，需要客户根据eventName自定义解析处理


4.广告相关字段


ads_track_activation



列名

字段名称

字段格式

字段说明

值（example）

userId

用户ID

string(36)

针对单个用户生成的唯一id

例如，web网站生成一个有效期三年的cookie值，App 则为机器唯一标识码

idfa

idfa

string(32)

iOS系统中的设备标志

CCD6E1CD-8C4B-40CB-8A62-4BBC7AFE07D6

imei

imei

string(32)

安卓系统中的设备唯一标志

10bc955ac2a67ed3

uuid

uuid

string(32)

GIO在设备中成的设备标志ID

略。即将下线，可忽视此字段

androidid

androidid

string(32)

安卓系统中的设备唯一标志

9774d56d682e549c

ip

ip

string(64)

用户IP地址

10.10.0.21

useragent

用户客户端UA信息

string(1024)

简称ua，例如浏览器信息或者移动设备信息

略

platform

数据来源平台

string(10)

区分该数据属于哪个平台

web, android, ios

osversion

系统版本

string(50)

用户使用的设备系统版本

ios 9.1.3

sendTime

发送时间

bigint

数据发送过来的时间

略

link_id

监测链接ID

string(10)

监测链接ID

o3ox2dV

campaign_id

推广活动ID

string(10)

推广活动ID

略

channel_id

目标渠道ID

string(20)

目标渠道ID

略

link_name

链接名称

string

链接名称

测试链接

campaign_name

活动名称

string

活动名称

双十一推广

channel_name

渠道名称

string

渠道名称

今日头条


ads_track_click

列名

字段名称

字段格式

字段说明

值（example）

idfa

idfa

string(32)

iOS系统中的设备标志

CCD6E1CD-8C4B-40CB-8A62-4BBC7AFE07D6

imei

imei

string(32)

安卓系统中的设备唯一标志

10bc955ac2a67ed3

uuid

uuid

string(32)

GIO在设备中成的设备标志ID

略。即将下线，可忽视此字段

androidid

androidid

string(32)

安卓系统中的设备唯一标志

9774d56d682e549c

ip

ip

string(64)

用户IP地址

10.10.0.21

useragent

用户客户端UA信息

string(1024)

简称ua，例如浏览器信息或者移动设备信息

略

platform

数据来源平台

string(10)

区分该数据属于哪个平台

web, android, ios

eventTime

事件发生时间

bigint

事件实际发生的时间


link_id

监测链接ID

string(10)

监测链接ID

o3ox2dV

campaign_id

推广活动ID

string(10)

推广活动ID

略

channel_id

目标渠道ID

string(20)

目标渠道ID

略

link_name

链接名称

string

链接名称

测试链接

campaign_name

活动名称

string

活动名称

双十一推广

channel_name

渠道名称

string

渠道名称

今日头条


二.接口定义

1.导出原始数据

URL

https://www.growingio.com/insights/{ai}/{date}.json

请求类型

GET


请求头参数

请参考认证>公共请求参数获取。

参数说明与示例

请求参数

路径参数

类型

是否必传

说明

ai

string

是

项目ID

date

string

是

数据日期

天级别示例：20160520

小时级别示例：20160502008

查询参数

类型

是否必传

说明

expire

integer

否

过期时间，以分为单位

默认值：  5


返回示例

{  
     "status": "FINISHED",  
     "downlinks": [   
          "link1",    
          "link2"  
      ]
}

响应中的 status 字段，状态值有： 1. FINISHED 任务完成； 2. RUNNING 任务正在跑； 3. NOT_EXISTS 任务不存在，可能是任务还没跑或者请求日期格式不对。

2.来源管理数据导出


URL

https://www.growingio.com/projects/{project_uid}/activities.json

请求方式

GET

请求头参数

请参考认证>公共请求参数获取。

参数说明与示例

请求参数


路径参数

类型

是否必传

说明

project_uid

string

是

项目UID。


返回参数

名称

说明

id

ID

name

名称（落地页命名）

示例：12.16增长大会

href

目标链接

示例：www.growingio.com

platform

平台

示例：网页为web，移动应用为mobile

utmCampaign

广告名称

示例：增长大会活动首页

utmMedium

广告媒介

示例：CPC

utmSource

广告来源

示例：广点通

utmContent

广告内容

示例：活动介绍和报名表单

utmTerm

广告关键词

示例：增长GrowingIO

comment

备注

示例：推广预算两万

advertiser

推广平台

示例：普通推广位”none“

projectId

项目ID

creatorName

创建人

示例：jacky

createdAt

创建时间

示例：1484397370856

shortUrl

用于投放的短链

示例：https://s.growingio.com/6XNmKl

uv

新用户，通过GIO广告链接访问广告，并在过去90天内首次使用您的App或网站的用户。用户首次使用后，数据有1小时左右的延迟。

示例：100

tc

链接访问，GIO广告链接的访问次数，通常通过点击广告位或者扫码访问。用户访问后，数据有1小时左右的延迟。

示例：120


三.导出数据处理建议


1.数据处理建议

数据处理建议采用Hive或者Spark平台工具，若是需要导入自有BI平台，可能需要进一步调整数据格式（csv转成其他符合数据处理需求的格式），针对以上的需求，给出相应的数据处理建议。

注意不要以逗号为分隔符进行处理，csv数据格式以引号外的逗号为分隔符。

2.处理方式

Spark

建议下载数据后，将下载的压缩文件放于hdfs的以日期建立目录结构，同一小时或者同一天的数据放在同一目录下，然后通过spark streaming的fileStream接口监控根目录，读取变动的文件内容。


streamingContext.fileStream[KeyClass, ValueClass, InputFormatClass](dataDirectory)

在依赖中添加：


roupId: com.databricks
artifactId: spark-csv_2.10
version: 1.4.0

具体数据操作参考spark-csv(https://github.com/databricks/spark-csv)

Hive

可以参考Hive对CSV数据操作的支持 https://cwiki.apache.org/confluence/display/Hive/CSV+Serde

目前暂未测试该方式～


create external table xxx


3.数据格式调整处理


以java为例

新建maven project，在prm.xml中添加以下依赖


    <dependency>     
         <groupId>org.apache.commons</groupId>      
         <artifactId>commons-compress</artifactId>      
         <version>1.12</version>    
    </dependency>    
    <!-- https://mvnrepository.com/artifact/org.apache.commons/commons-csv -->    
    <dependency>      
         <groupId>org.apache.commons</groupId>      
         <artifactId>commons-csv</artifactId>      
         <version>1.4</version>   
    </dependency>

而后在读取数据的方法中：


    GzipCompressorInputStream stream = new GzipCompressorInputStream(new BufferedInputStream(new FileInputStream("data/test.gz")));    
    
    Reader reader = new InputStreamReader(stream);    
    Iterable<CSVRecord> records = CSVFormat.DEFAULT.parse(reader);    
    for (CSVRecord record : records) {        
         System.out.println(record);   
    }

上例中，数据读取依赖于commons-compress与commons-csv库，同样在python中有类似的数据处理库。




    最多浏览的文档