数据输出

应用场景

如果您需要将Finder-SDK采集的埋点数据实时推送到目标地址（例如您的业务数仓），数据输出模块可为您实现。

使用限制

数据输出方式

当前DataFinder的SaaS-非云原生环境支持实时传输数据；私有化环境支持实时与离线传输数据。实时与离线数据传输的主要流程如下。

• 实时传输（SaaS-非云原生、私有化）

当前实时传输支持通过“Webhook”渠道实现数据实时触达。

• 离线传输（私有化）

私有化4.6.1（含）之后支持在实时数据传输的基础上，将行为数据一次性或定时离线导出至FTP/SFTP，实现离线数据输出。
如您有其他数据传输的场景需求，可联系您的客户成功经理。

前提条件

创建数据输出任务

1. 登录DataFinder控制台后，单击顶部导航栏的数据管理>数据输出>数据输出，进入数据输出页面。
   

   说明

   如果您无法在应用管理列表找到“数据输出”入口，请联系您的管理员为您开通权限。（权限配置入口：集团设置-角色管理-增长分析-配置功能权限）

2. 单击页面右上角的新建任务，配置数据输出任务详情，完成后单击确定。

   1. 配置基本信息。
      

   参数	参数说明
   任务名称	您可以自定义名称，例如XX产品埋点数据推送。
   触发类型	当前SaaS-非云原生环境仅支持实时数据分发，即跟随数据上报即时分发到目标地址。
   分发内容	配置分发到目标地址的数据内容，支持配置为： 原始上报数据：即SDK采集上报的原始数据，数据被SDK采集上报后60秒内送达目标地址。 事件表数据：SDK采集上报的数据经DataFinder处理后落库存储的事件表数据。数据被SDK采集上报后10分钟内送达目标地址。 因原始数据落库时有数据处理过程，因此分发时间相较于原始上报数据会有延时。 采集的原始数据如果不符合DataFinder的落库数据规范要求，或事件被禁用，则这部分原始数据不落表（例如属性数据类型不一致），也就不会被分发至目标地址。 注意 实时数据输出启动数据传输时，部分数据还未落库，例如：IP解析省份&城市等需要二次解析的数据；且实时输出传输不包含profile（用户数据）和item（业务对象） API上报的数据。因此如果您需要接收此类数据时，建议使用离线传输任务。

   2. 配置分发通道及配置
      

      参数	参数说明
      分发通道	当前仅支持Webhooks分发。
      Webhook URL	配置分发的Webhook URL地址。格式示例：http://localhost:6666/payload。http/https均可支持。 注意 一个数据分发任务仅支持填写一个URL地址，如有多个地址可创建多个任务。 在SaaS-非云原生环境中，您需要添加以下来源ip的白名单： 106.38.226.0/24 116.132.239.0/24 111.63.61.128/25 111.63.211.128/25 在私有化环境中，如果接收服务是在外网，需要配置私有化机器的出口ip。
      Headers	您需要根据接收端对数据发送的Webhook要求，配置Webhook Headers，支持置多项Headers。 例如，接收端要求配置鉴权信息，您可将鉴权信息配置在Headers中，后续DataFinder传输数据时会带上此处配置的Headers信息。

   3. 配置数据管理。
      

      参数	参数说明
      添加事件	配置需要分发到目标地址的事件列表。事件列表为包含逻辑，即仅选定的事件将会被分发。
      事件属性添加规则	对已添加的事件通过事件属性进行过滤，即仅在事件列表范围内，且满足事件属性规则的数据才会被分发。

数据输出结果确认

任务创建成功后预计10分钟内生效。您可以在10分钟之后查看接收端是否正常接收到了数据。

查看/启停/编辑任务

您可以在数据输出的任务列表页面查看所有数据输出任务：

• 任务创建后默认状态为“执行中”，此时数据正常分发。如果您需要停止数据输出，可以点击“停止”将状态改为“已停用”。任务切换状态预计10分钟内生效。
  
• 执行中任务不可编辑或删除，如果您需要修改数据传输地址,请先将执行中的任务停用，编辑后重新启用即可。

以下为您介绍离线/实时传输数据时，传输的数据的格式，以及各个传输的字段的说明。

实时传输：分发数据示例

一次请求的body是一个json array，里面会包含1-50条事件。

[{
  "user": {
    "user_unique_id": "mock_user_unique_id",
    "user_id": 6934486383370142000,
    "user_type": 13,
    "user_is_auth": false,
    "user_is_login": false,
    "is_upgrade_user": false,
    "web_id": 6934486383370142000,
    "ip_addr_id": 0,
    "ssid": "acf3dd8f-7a18-42b1-996b-56a20156249c"
  },
  "header": {
    "app_id": 10000010,
    "app_name": "mock_web",
    "access": "",
    "client_ip": "221.122.122.122",
    "carrier": "",
    "os_name": "mac",
    "os_version": "10_15_5",
    "product_id": 107,
    "product_name": "default_to_b",
    "custom": "{\"app_id\":10000010,\"screen_width\":1440,\"screen_height\":900}",
    "trace_id": "16015901108710420012361360828522",
    "language": "zh-CN",
    "device_model": "Macintosh",
    "resolution": "1440x900",
    "width": 1440,
    "height": 900,
    "timezone": 8,
    "tz_offset": -28800,
    "platform": "web",
    "browser": "Chrome",
    "browser_version": "78.0.3904.108",
    "referrer": "",
    "referrer_host": ""
  },
  "params": "{\"app_name\":\"mock_web\",\"referrer\":\"\",\"user_unique_id\":\"\",\"time\":1601590110322,\"is_bav\":1,\"title\":\"测试页面\",\"event_index\":1616590857270,\"url\":\"http://demo.com.cn/product/list\",\"url_path\":\"/product/list\"}",
  "event_name": "predefine_pageview",
  "session_id": "aa7b79a1-4e27-44fe-bed8-56adfffddc07",
  "datetime": 1601590110,
  "server_time": 1601590110,
  "rnd": "ne0000",
  "log_type": "mario_event",
  "local_time_ms": 1601590110322
},{其他事件},{其他事件}]

实时传输：单个事件具体字段说明

//一个事件
Event {
          User user //user内格式见下面
          Header header //header格式见下面
          string params  // 事件参数,单层json map,需要dump成字符串
          string event_name  // 事件名
          uint64 event_id  // 事件id
          string session_id
          uint64 datetime  // 事件发生时间戳(秒)
          uint64 server_time  // 日志到达服务器时间
          string log_type 
          uint64 local_time_ms    // 事件发生时间戳(毫秒)
}

//事件内user字段

User {
     string user_unique_id  // 用户唯一id
     uint64 user_id  // 用户id
     uint32 user_type  // 用户类型
     bool user_is_auth  // 是否授权
     bool user_is_login  // 是否登录
     uint64 device_id  // 设备id
     string open_udid  // openudid
     string udid  // udid
     string client_udid  // 客户端自己生成的设备id
     string mc    // 设备mac地址
     string build_serial    // 硬件序列号
     string serial_number    // 序列号
     string idfa    // idfa
     bool is_upgrade_user    // 是否app升级用户
     uint64 web_id 
     uint64 ip_addr_id 
     string ssid 
     string idfv 
     string oaid 
     string cdid 
     string user_unique_id_type    // user_unique_id字段口径，tob场景使用，为空或default_user_unique_id_type为默认口径
}

//事件内header字段

Header {
     string headers  // 自定义header,单层json map,需要dump成字符串
     uint32 app_id  // app_id
     string app_name  // app名称
     string app_version  // app版本
     string app_package  // app包名称
     string display_name  // app名称
     string app_channel  // app分发渠道
     string access  // 网络访问类型
     string client_ip  // 客户端ip
     string carrier    // 运营商
     string os_name    // 系统名称
     string os_version    // 系统版本
     uint32 product_id    // 产品id
     string product_name    // 产品名称
     uint64 install_id    // app升级id
     string custom //自定义事件公共属性，是一个json的字符串
     string trace_id 
     uint32 client_port    // 客户端端口号
     string data_center    //上报机房
     string app_key    // 应用key
     uint32 version_code    // 版本号
     string sig_hash    // sig_hash
     uint32 update_version_code    // 内部更新版本号
     string vendor_id    // app发行商id
     string app_language    // app语言
     string language    // 系统语言
     string app_region    // app设置地区
     string region    // 系统设置地区
     string vid    // vid
     string traffic_type 
     string carrier_region 
     string device_model    // 设备型号
     string device_brand    // 设备品牌
     string device_manufacturer    // 设备制造商
     string resolution    // 屏幕分辨率
     string display_density    // 屏幕像素显示级别
     uint32 density_dpi    // 屏幕像素显示密度
     sint32 width    // 屏幕宽度
     sint32 height    // 屏幕宽度
     string cpu_abi    // cpu类型
     uint32 origin_app_id    // 中台重置的原始app_id
     string origin_app_name    // 中台重置的原始app_name
     float timezone    // 时区
     string tz_name    // 时区名称
     sint32 tz_offset    // 时区偏差
     string mcc_mnc    // 国家+运行商标记
     uint32 os_api    // 客户端系统API版本号
     string rom    // rom
     string rom_version    // rom版本
     string release_build    // release_build
     uint32 manifest_version_code    // Android配置版本号
     string sim_region    // sim地区
     string sim_serial_number    // sim序列号
     bool is_jailbroken    // 设备是否越狱
     string push_os    // 支持的推送os
     string platform    // 平台类型
     string province    // 省
     string city    // 市
     string ab_version    // ab_test字段
     string ab_group    // ab_test字段
     string ab_feature    // ab_test字段
     string ab_client    // ab_test字段
     string ab_sdk_version    // ab_test字段
     string utm_source    // 广告来源
     uint32 sdk_version    // 建议使用sdk_version_v2
     bool not_request_sender    // not_request_sender
     string user_agent    // user_agent
     bool gcm_available 
     string utm_medium    // 广告媒介
     string utm_campaign    // 广告名称
     uint64 campaign_id 
     uint64 ad_id 
     uint64 creative_id 
     string browser 
     string browser_version 
     string referrer 
     string referrer_host 
     string app_version_minor    //4位版本号
     string utm_term    //广告关键词
     string utm_content    //广告内容
     string sdk_version_v2    //string类型sdk版本
     string pgl_oaid  [deprecated]  //已废弃,请使用user中的pgl_oaid字段
     string tracer_data    // SDK tracer自定义字段，json串
     string sdk_lib    // 标识sdk类型
     uint64 harmony_os_api    // 524~530为鸿蒙系统特有标识
     string harmony_os_version 
     string harmony_release_type 
     uint64 harmony_build_version 
     uint64 harmony_major_version 
     uint64 harmony_senior_version 
     uint64 harmony_feature_version 
 
}

离线传输：数据示例

单条数据示例：

{
   "user": {
      "user_unique_id": "4010980525",
      "web_id": "",
      "ssid": "1729384455933548568",
      "anonymous_id": null,
      "device_id": "7279348669067838213",
      "hash_uid": "1729384455933548568"
   },
   "header": {
      "app_id": 10000000,
      "app_name": "toutiao",
      "ab_version": [],
      "custom": {
         "continent": "AS",
         "device_model": "iphone 7 plus",
         "platform": "ios",
         "getui_client_id": "A2800992-931C-4836-A884-AF6D6B35D064",
         "platform_type": "web/h5",
         "browser": "safari",
         "sdk_version": "6180690",
         "browser_version": "9.1.3",
         "sdk_lib": "ios",
         "__trace_id": "1694880771043042001034172826147014",
         "session_id": "f5de541d7433774ade7931a766c6087088ba",
         "network_carrier": "at&t",
         "ad_id": "0",
         "device_brand": "apple",
         "is_login": 1,
         "width": 0,
         "age": 56,
         "height": 0
      },
      "app_language": "zh_CN",
      "app_version": "0.15",
      "timezone": "8",
      "language": "zh_CN",
      "resolution": "320*570",
      "loc_country_id": "1814991",
      "app_region": "China",
      "loc_province_id": "1796231",
      "client_ip": "180.156.197.138",
      "loc_city_id": "1796236",
      "package": "ios.package",
      "os_version": "11.4.0",
      "app_channel": "\u6296\u97f3\u89c6\u9891",
      "os_name": "ios",
      "network_type": "4g",
      "region": "China"
   },
   "sdk": null,
   "preset_user_profiles": "",
   "params": {
      "is_background": "false",
      "duration": 0,
      "session_duration": 0
   },
   "event_name": "app_launch",
   "time": {
      "event_time": 1694879843000,
      "server_time": 1694879843000,
      "event_date": "2023-09-16"
   }
}

离线传输：二次解析字段的映射

离线传输的数据可能会额外包含地域ID（需要使用映射表获取中文）、是否登录等经过二次处理的预置属性。在传输过程中，此类数据以ID的形式进行存储，ID与其对应的中英文名称、属性取值等映射关系如下表所示。您可参考下表将接收到的此类数据进行映射处理，便于后续的查询分析。

geo_info.csv

16.44MB

离线传输：离线数据字段说明

Q1 能否获取历史数据？

实时任务不支持，请通过离线任务自助补推历史数据，最多支持T-30天的历史数据一次性导出。
此外，已停用的实时任务如果重新启用，停用期间的数据不可回溯。

Q2 数据发送时间？

实时数据正常情况在数据上报后60s内发送。

Q3 数据发送失败怎么办？

针对业务自身服务接收造成的发送失败，目前系统存在如下重试机制：
saas环境中，如果某条数据连续三次失败，系统将不再推送该条消息；7天内您可以联系客户成功经理或火山的技术支持手动触发推送，过期将自动删除不再支持恢复。
私有化环境中，当日内不限次重试；4.6（含）版本后将保持与SaaS一致。

Q4 接受的数据条数为什么和界面统计的指标有差异？

不排除因网络不稳定等各种原因出现部分数据重复推送的情况。如有特殊情况可联系您的客户成功经理或火山的技术支持。