本文件所描述的內容屬於神策分析的高級使用功能，涉及較多技術細節，適用於對相關功能有經驗的用戶參考。如果對文件內容有疑惑，請諮詢您的數據諮詢顧問取得一對一的協助。

查詢 API 主要用於取得各種數據分析報告。

1. 呼叫方法

請參見 API 文件 中的呼叫方法描述。

2.  通用參數

2.1. 屬性表達式

幾乎所有的 API 都會用到屬性表達式，例如按照某個屬性進行過濾、分組或者聚合等等。屬性包括事件屬性和用戶屬性，事件屬性使用 event.事件名.屬性名 的方式，例如表示 註冊渠道 這個屬性的表達式如下:

event.Signup.Channel

用戶屬性類似，例如表示 用戶性別:

user.Gender

2.2. 篩選表達式

篩選表達式同樣適用於絕大多數 API，用於表示對某些事件或者用戶的篩選操作，使用如下格式的 JSON 表示:

{
  // 表示 conditions 裡的各個條件的關係是 或 還是 且
  "relation": "and",
  // 具體的條件列表，可以有多個
  "conditions": [{
    // 條件的左值，是一個屬性表達式
    "field": "event.BuyGold.$os",
    // 條件的運算子，這裡表示等於
    "function": "equal",
    // 條件的參數，根據不同的運算子可以有一個或者多個
    "params": [
      "iOS"
    ]
    }, {
    "field": "user.Gender",
    "function": "equal",
    "params": [
      "男"
    ]
  }]
}

目前支援的運算子如下:

  • equal / notEqual

        表示等於/不等於，對字串、數值型別有效。如果 Params 有多個，則相當於 In 或者 Not In。例如想篩選出來自北京或者上海的用戶:

{
  "field": "user.$city",
  "function": "equal",
  "params": ["北京", "上海"]
}
  •  isTrue / isFalse

        只對布林型別有效。

  •  isSet / notSet

        某個屬性是否有值，對字串、數值型別有效。

  •  include

        針對集合的操作，表示包含某個元素，例如篩選出所有喜歡蘋果的用戶:

{
  "field": "user.FavoriteFruits",
  "function": "include",
  "params": ["Apple"]
}
  •  less / greater / between：表示小於/大於/小於且大於，其中 between 是前閉後閉的區間，只對數值型別有效。例如篩選買入黃金的價格在 230 和 232 之間的所有事件:
{
  "field": "event.BuyGold.GoldPrice",
  "function": "between",
  "params": [230, 232]
}

  • contain / notContain

        包含或者不包含，表示字串的部分匹配，只對字串型別有效。

  • absoluteBetween / relativeBefore / relativeWithin

        針對日期型別的運算子，分別表示在一個絕對日期範圍/在 N 天之前/在 N 天之內。例如想篩選所有註冊時間在 3 天之內的用戶:

{
  "field": "user.$signup_time",
  "function": "relativeWithin",
  "params": [3]
}

        或者篩選所有在 2015-1-1~2015-1-10 註冊的用戶:

{
  "field": "user.$signup_time",
  "function": "absoluteBetween",
  "params": ["2015-01-01", "2015-01-10"]
}

3. 行為分析報告

所有的分析報告均有 JSON 和 CSV 兩種格式，預設是 JSON 格式，如果需要 CSV 格式的數據可以手動指定 format 參數。例如事件分析報告對應的 CSV 格式的 URL 為: /events/report?format=csv 。

3.1. 事件分析報告

[POST /events/report]

{
  "measures":[
    {
      // 事件名稱，特别是，可以使用 $Anything 表示任意事件
      "event_name":"payOrder",
      // 聚合運算子
      "aggregator":"uniq_count",
      //（可選）對於指標的篩選條件
      "filter": {
        "conditions": [
          {
            "field": "user.sex",
            "function": "equal",
            "params": [
              "男"
            ]
          }
        ]
      }
    }
  ],
  // 起始日期
  "from_date":"2018-04-30",
  // 結束日期
  "to_date":"2018-05-02",
  // 時間單位，可以是 hour/day/week/month
  "unit":"day",
  //（可選）篩選條件
  "filter":{
    "relation":"and",
    "conditions":[
      {
        "field":"event.payOrder.$lib_version",
        "function":"equal",
        "params":[
          "1.6.18"
        ]
      },
      {
        "field":"event.payOrder.$lib",
        "function":"equal",
        "params":[
          "Android"
        ]
      }
    ]
  },
  //（可選）分組屬性，可以有零個或者多個
  "by_fields":[
    "event.payOrder.$screen_width",
    "event.payOrder.$screen_height"
  ],
  //（可選）分桶條件，對數值型屬性進行分組時，可以自定義分桶條件
  "bucket_params":{
    "event.payOrder.$screen_width":[2000,3000],
    "event.payOrder.$screen_height":[2000]
  },
  // 是否計算合計值
  "detail_and_rollup":true,
  //（可選）抽樣因子，64為全量，32為2分之1抽樣
  "sampling_factor":64,
  //（可選）使用近似計算
  "approx":true,
  //（可選）基數計算算法 hyperloglog 的精度，值越大精度越高，但對應記憶體佔用也會變高，推薦用12。
  "hll_precision":12,
  //（可選）使用近似計算合計，當“approx”為 true 時，“approx_total”也設為 true，當“approx”為 false 時，如果“approx_total”為 true，那合計會以近似計算算法得出
  "approx_total":false,
  //（可選）最大分組個數
  "limit":1000,
  //（可選）使用快取，若快取中找不到相應數據，則從資料庫讀出
  "use_cache":true
} 
{
  "by_fields":[
    "event.$Anything.$screen_width",
    "event.$Anything.$screen_height"
  ],
  "series":[
    "2018-04-30 00:00:00",
    "2018-05-01 00:00:00",
    "2018-05-02 00:00:00"
  ],
  "rows":[
    {
      "values":[
        [57],
        [60],
        [38]
      ],
      "by_values":[
        "-INF~2000",
        "-INF~2000"
      ]
    },
    {
      "values":[
        [7],
        [7],
        [2]
      ],
      "by_values":[
        "2000~3000",
        "-INF~2000"
      ]
    }
  ],
  "num_rows": 2,
  "total_rows": 2,
  "report_update_time": "2018-05-02 13:51:08.356",
  "data_update_time": "2018-05-02 16:03:32.000",
  "data_sufficient_update_time": "2018-05-02 16:03:32.000",
  "truncated": false
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/events/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "measures": [
    {
      "event_name": "payOrder",
      "aggregator": "unique",
      "filter": {
        "conditions": [
          {
            "field": "user.sex",
            "function": "equal",
            "params": [
              "男"
            ]
          }
        ]
      }
    }
  ],
  "from_date": "2018-04-30",
  "to_date": "2018-05-02",
  "unit": "day",
  "filter": {
    "relation": "and",
    "conditions": [
      {
        "field": "event.payOrder.$lib_version",
        "function": "equal",
        "params": [
          "1.6.18"
        ]
      },
      {
        "field": "event.payOrder.$lib",
        "function": "equal",
        "params": [
          "Android"
        ]
      }
    ]
  },
  "by_fields": [
    "event.payOrder.$screen_width",
    "event.payOrder.$screen_height"
  ],
  "bucket_params": {
    "event.payOrder.$screen_width": [
      2000,
      3000
    ],
    "event.payOrder.$screen_height": [
      2000
    ]
  },
  "unit":"day",
  "detail_and_rollup": true,
  "sampling_factor": 64,
  "approx": true,
  "hll_precision": 12,
  "approx_total": false,
  "limit": 1000,
  "use_cache": true
}

'

關鍵參數說明：

  • **aggregator: **聚合運算子，可取值為：
  • general:事件觸發次數
  • unique:觸發用戶數
  • average/uniqAvg:人均次數/人均值
  • sum: 數值總和
  • max:數值最大值
  • min:數值最小值
  • avg:數值平均值
  • **field: **若aggregator為sum/max/min/avg，需要增加field欄位，即聚合的欄位名，與aggregator同級，例如：“field" : "event.payOrder.discountAmount"
  • **bucket_params: **分桶條件，對數值型屬性進行分組時，可以自定義分桶條件，分桶條件裡所包含的屬性必須全包含在分組屬性“by_fields”
  • **limit: **最大分組個數，如果limit較大（超過1W），建議使用stream模式下載（僅對於事件分析）。stream模式開啟：增加參數“downloadOriginalFormat” : true。如果不傳入該欄位，回傳的分組數量將根據以下規則計算：10000 / 時間段個數 / 指標個數，時間段個數為 from_date 和 to_date 包含多少個單位為 unit 的時間段，指標個數即 measures 數組個數

3.2. 漏斗分析報告

[POST /funnels/report]

{
  // 漏斗 ID
  "funnel_id": 158,
  // 起始日期
  "from_date": "2015-04-17",
  // 結束日期
  "to_date": "2015-04-19",
  // 篩選條件
  "filter": {
    "conditions": [
      {
        "field": "event.$AppStart.$lib_version",
        "function": "contain",
        "params": [
          "0.1.0"
        ]
      },
      {
        "field": "event.$AppEnd.$lib",
        "function": "contain",
        "params": [
          "python"
        ]
      },
      {
        "field": "user.Gender",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation": "and"
  },
  // （可選）分組屬性，按指定步驟事件屬性、用戶屬性或分群名進行分組
  "by_field": "event.$AppStart.$os",
  // 是否限制漏斗所以步驟在事件窗口內，true:不限制，false:限制
  "extend_over_end_date": true,
  // （可選）分組的步驟 id，如果為 -1 表示用戶屬性/分群名，0 表示第一步驟事件屬性，若 ”by_field” 中能明確看出為第幾步的事件屬性/用戶屬性，則此參數可以不用設定。否則需要設定相應參數值，並且和 ”by_field” 請求參數保持一致
  "by_field_step": -1,
  // （可選）抽樣
  "sampling_factor": 64,
  // 指定篩選條件針對的步驟，0 為第一步驟，-1 為用篩選條件為用戶屬性/用戶分群。在請求參數中 "filter" "conditions"中 “field”中指定了每一步驟的事件名及篩選條件，”filter_field_steps”參數可以不用設定。如果設定此參數，需要和 “field” 請求參數中的步驟保持一致。
  "filter_field_steps": [
      0，
      1，
     -1
    ]
}

在 1.13 及以上的版本中，我們支援 "from_date" 與 "to_date" 使用"秒級精度"或"天級精度"進行篩選

範例：

// 使用秒級精度
"from_date": "2015-04-17 22:00:00",
"to_date" : "2015-04-18 22:00:00",
  • 系統將會匹配出時間範圍為 2015-04-17 22:00:00.000 至 2015-04-18 22:00:00.999 的全部數據
// 使用天級精度
"from_date": "2015-04-17",
"to_date" : "2015-04-18",
  • 系統將會匹配出時間範圍為 2015-04-17 00:00:00.000 至 2015-04-18 23:59:59.999 的全部數據
{
  "date_list": [
    "$ALL",
    "2017-04-17",
    "2017-04-18",
    "2017-04-19"
  ],
  "funnel_detail": [
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 98726,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 76110,
              "conversion_rate": 77.09,
              "wastage_user": 22616,
              "median_converted_time": 1505
            },
            {
              "converted_user": 76110,
              "conversion_rate": 77.09,
              "wastage_user": 22616,
              "median_converted_time": 1505
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 76110,
          "conversion_rate": 77.09,
          "rows": [
            {
              "converted_user": 21266,
              "conversion_rate": 27.94,
              "wastage_user": 54844,
              "median_converted_time": 2530
            },
            {
              "converted_user": 21266,
              "conversion_rate": 27.94,
              "wastage_user": 54844,
              "median_converted_time": 2530
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 21266,
          "conversion_rate": 27.94,
          "rows": [
            {
              "converted_user": 17522,
              "conversion_rate": 82.39,
              "wastage_user": 3744,
              "median_converted_time": 939
            },
            {
              "converted_user": 17522,
              "conversion_rate": 82.39,
              "wastage_user": 3744,
              "median_converted_time": 939
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 17522,
          "conversion_rate": 82.39,
          "rows": []
        }
      ],
      "completion_rate": 17.75,
      "overview": [
        [
          {
            "converted_user": 98726,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 76110,
            "conversion_rate": 77.09,
            "completion_rate": 77.09
          },
          {
            "converted_user": 21266,
            "conversion_rate": 27.94,
            "completion_rate": 21.54
          },
          {
            "converted_user": 17522,
            "conversion_rate": 82.39,
            "completion_rate": 17.75
          }
        ],
        [
          {
            "converted_user": 98726,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 76110,
            "conversion_rate": 77.09,
            "completion_rate": 77.09
          },
          {
            "converted_user": 21266,
            "conversion_rate": 27.94,
            "completion_rate": 21.54
          },
          {
            "converted_user": 17522,
            "conversion_rate": 82.39,
            "completion_rate": 17.75
          }
        ]
      ]
    },
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 34099,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 26813,
              "conversion_rate": 78.63,
              "wastage_user": 7286,
              "median_converted_time": 1537
            },
            {
              "converted_user": 26813,
              "conversion_rate": 78.63,
              "wastage_user": 7286,
              "median_converted_time": 1537
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 26813,
          "conversion_rate": 78.63,
          "rows": [
            {
              "converted_user": 7787,
              "conversion_rate": 29.04,
              "wastage_user": 19026,
              "median_converted_time": 2710
            },
            {
              "converted_user": 7787,
              "conversion_rate": 29.04,
              "wastage_user": 19026,
              "median_converted_time": 2710
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 7787,
          "conversion_rate": 29.04,
          "rows": [
            {
              "converted_user": 6449,
              "conversion_rate": 82.82,
              "wastage_user": 1338,
              "median_converted_time": 942
            },
            {
              "converted_user": 6449,
              "conversion_rate": 82.82,
              "wastage_user": 1338,
              "median_converted_time": 942
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 6449,
          "conversion_rate": 82.82,
          "rows": []
        }
      ],
      "completion_rate": 18.91,
      "overview": [
        [
          {
            "converted_user": 34099,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26813,
            "conversion_rate": 78.63,
            "completion_rate": 78.63
          },
          {
            "converted_user": 7787,
            "conversion_rate": 29.04,
            "completion_rate": 22.84
          },
          {
            "converted_user": 6449,
            "conversion_rate": 82.82,
            "completion_rate": 18.91
          }
        ],
        [
          {
            "converted_user": 34099,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26813,
            "conversion_rate": 78.63,
            "completion_rate": 78.63
          },
          {
            "converted_user": 7787,
            "conversion_rate": 29.04,
            "completion_rate": 22.84
          },
          {
            "converted_user": 6449,
            "conversion_rate": 82.82,
            "completion_rate": 18.91
          }
        ]
      ]
    },
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 34445,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 26701,
              "conversion_rate": 77.52,
              "wastage_user": 7744,
              "median_converted_time": 1521
            },
            {
              "converted_user": 26701,
              "conversion_rate": 77.52,
              "wastage_user": 7744,
              "median_converted_time": 1521
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 26701,
          "conversion_rate": 77.52,
          "rows": [
            {
              "converted_user": 7407,
              "conversion_rate": 27.74,
              "wastage_user": 19294,
              "median_converted_time": 2594
            },
            {
              "converted_user": 7407,
              "conversion_rate": 27.74,
              "wastage_user": 19294,
              "median_converted_time": 2594
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 7407,
          "conversion_rate": 27.74,
          "rows": [
            {
              "converted_user": 6111,
              "conversion_rate": 82.5,
              "wastage_user": 1296,
              "median_converted_time": 956
            },
            {
              "converted_user": 6111,
              "conversion_rate": 82.5,
              "wastage_user": 1296,
              "median_converted_time": 956
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 6111,
          "conversion_rate": 82.5,
          "rows": []
        }
      ],
      "completion_rate": 17.74,
      "overview": [
        [
          {
            "converted_user": 34445,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26701,
            "conversion_rate": 77.52,
            "completion_rate": 77.52
          },
          {
            "converted_user": 7407,
            "conversion_rate": 27.74,
            "completion_rate": 21.5
          },
          {
            "converted_user": 6111,
            "conversion_rate": 82.5,
            "completion_rate": 17.74
          }
        ],
        [
          {
            "converted_user": 34445,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26701,
            "conversion_rate": 77.52,
            "completion_rate": 77.52
          },
          {
            "converted_user": 7407,
            "conversion_rate": 27.74,
            "completion_rate": 21.5
          },
          {
            "converted_user": 6111,
            "conversion_rate": 82.5,
            "completion_rate": 17.74
          }
        ]
      ]
    },
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 33579,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 25271,
              "conversion_rate": 75.26,
              "wastage_user": 8308,
              "median_converted_time": 1485
            },
            {
              "converted_user": 25271,
              "conversion_rate": 75.26,
              "wastage_user": 8308,
              "median_converted_time": 1485
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 25271,
          "conversion_rate": 75.26,
          "rows": [
            {
              "converted_user": 6845,
              "conversion_rate": 27.09,
              "wastage_user": 18426,
              "median_converted_time": 2469
            },
            {
              "converted_user": 6845,
              "conversion_rate": 27.09,
              "wastage_user": 18426,
              "median_converted_time": 2469
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 6845,
          "conversion_rate": 27.09,
          "rows": [
            {
              "converted_user": 5599,
              "conversion_rate": 81.8,
              "wastage_user": 1246,
              "median_converted_time": 928
            },
            {
              "converted_user": 5599,
              "conversion_rate": 81.8,
              "wastage_user": 1246,
              "median_converted_time": 928
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 5599,
          "conversion_rate": 81.8,
          "rows": []
        }
      ],
      "completion_rate": 16.67,
      "overview": [
        [
          {
            "converted_user": 33579,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 25271,
            "conversion_rate": 75.26,
            "completion_rate": 75.26
          },
          {
            "converted_user": 6845,
            "conversion_rate": 27.09,
            "completion_rate": 20.38
          },
          {
            "converted_user": 5599,
            "conversion_rate": 81.8,
            "completion_rate": 16.67
          }
        ],
        [
          {
            "converted_user": 33579,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 25271,
            "conversion_rate": 75.26,
            "completion_rate": 75.26
          },
          {
            "converted_user": 6845,
            "conversion_rate": 27.09,
            "completion_rate": 20.38
          },
          {
            "converted_user": 5599,
            "conversion_rate": 81.8,
            "completion_rate": 16.67
          }
        ]
      ]
    }
  ],
  "by_field": "event.$Anything.$os",
  "by_values": [
    "$ALL",
    "iOS"
  ],
  "event_names": [
    "ViewHomePage",
    "ViewProduct",
    "SubmitOrder",
    "PayOrder"
  ],
  "report_update_time": "2017-04-21 11:13:47.703",
  "data_update_time": "2017-04-21 11:12:56.000",
  "data_sufficient_update_time": "2017-04-21 11:12:56.000"
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/funnels/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \

--data-binary '{
    "from_date":"2015-04-17",
    "to_date":"2015-04-19",
    "funnel_id":"158",
    "filter":{
        "conditions":[
            {
                "field":"event.$AppStart.$lib_version",
                "function":"equal",
                "params":[
                    "0.1.0"
                ]
            },
            {
                "field":"event.$AppEnd.$libe",
                "function":"equal",
                "params":[
                    "python"
                ]
            }，
            {
                "field": "user.Gender",
                "function": "equal",
                "params": [
                    "男"
                ]
            }
        ],
        "relation":"and"
    },
    "by_field":"event.$AppStart.$os"
}'



3.3.  留存分析報告

[POST /retentions/report]

{
  // 起始日期
  "from_date": "2018-04-30",
  // 結束日期
  "to_date": "2018-05-02",
  // 表示取得往後 N 個單位的留存
  "duration": "7",
  // 第一個事件的資訊
  "first_event": {
    // 事件名
    "event_name": "login"
  },
  // 第二個事件的資訊
  "second_event": {
    // 事件名
    "event_name": "submitOrder",
    // 事件的篩選條件
    "filter": {
      "conditions": [
        {
          "field": "event.submitOrder.$lib",
          "function": "equal",
          "params": [
            "Android"
          ]
        }
      ],
      "relation":"and"
    }
  },
  // （可選）同時顯示第三個指標
  "measures": [
    {
      "event_name": "payOrder",
      "aggregator": "unique"
    }
  ],
  // （可選）用戶的篩選條件
  "user_filter": {
    "conditions": [
      {
        "field": "user.sex",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation":"and"
  },
  // （可選）時間標識，例如上週，優先級高於 from_date 和 to_date
  "rangeText": "上週"
  // （可選）留存的單位，可以是 day/week/month
  "unit": "day",
  // （可選）後續事件是否可以超出時間區間
  "extend_over_end_date": true,
  // （可選）抽樣因子，64為全量，32為2分之1抽樣
  "sampling_factor": 64,
  // （可選）是否計算流失，false為計算留存，true為計算流失
  "is_wastage": false,
  "use_cache": true
}
{
  "by_field": "",
  "has_first_day": false,
  "rows": [
    {
      "by_value": "2018-04-30",
      "total_people": 95,
      "cells": [
        {
          "people": 36,
          "percent": 37.89,
          // 選擇同時顯示後，values 的值即為同時顯示的指標的值
          "values": [
            0
          ]
        },
        {
          "people": 6,
          "percent": 6.32,
          "values": [
            5
          ]
        }
      ]
    },
    {
      "by_value": "2018-05-01",
      "total_people": 91,
      "cells": [
        {
          "people": 25,
          "percent": 27.47,
          "values": [
            0
          ]
        },
        {
          "people": 1,
          "percent": 1.1,
          "values": [
            1
          ]
        }
      ]
    },
    {
      "by_value": "2018-05-02",
      "total_people": 62,
      "cells": [
        {
          "people": 25,
          "percent": 40.32,
          "values": [
            0
          ]
        }
      ]
    }
  ],
  "report_update_time": "2018-05-02 17:00:21.355",
  "data_update_time": "2018-05-02 16:59:43.000",
  "data_sufficient_update_time": "2018-05-02 16:59:43.000",
  "truncated": false
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/retentions/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "from_date": "2018-04-30",
  "to_date": "2018-05-02",
  "duration": "7",
  "first_event": {
    "event_name": "login"
  },
  "second_event": {
    "event_name": "submitOrder",
    "filter": {
      "conditions": [
        {
          "field": "event.submitOrder.$lib",
          "function": "equal",
          "params": [
            "Android"
          ]
        }
      ],
      "relation": "and"
    }
  },
  "measures": [
    {
      "event_name": "payOrder",
      "aggregator": "unique"
    }
  ],
  "user_filter": {
    "conditions": [
      {
        "field": "user.sex",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation": "and"
  },
  "unit": "day",
  "extend_over_end_date": true,
  "sampling_factor": 64,
  "is_wastage": false,
  "use_cache": true
}

'

3.4. 分布分析報告

[POST /addictions/report]

{
  // 事件名稱
  "event_name": "submitOrder",
  // 起始時間
  "from_date": "2018-04-30",
  // 結束時間
  "to_date": "2018-05-02",
  // 事件篩選條件
  "filter": {
    "conditions": [
      {
        "field": "event.submitOrder.$lib",
        "function": "equal",
        "params": [
          "Android"
        ]
      }
    ],
    "relation":"and"
  },
  // 用戶篩選條件
  "user_filter": {
    "conditions": [
      {
        "field": "user.sex",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation":"and"
  },
  // （可選）時間標識，如：上週，優先級高於 from_date、to_date
  "rangeText":"上週",
  // 抽樣因子，64為全量，32為2分之1抽樣
  "sampling_factor":64,
  // 事件單位，可以是 day/week/month
  "unit": "day",
  // 測量類型,可以是 times/period, period 是當按小時數或者天數進行分佈分析時使用
  "measure_type":"times",
  // 測量類型如果是 times，即可以自定義分桶，可省略
  "result_bucket_param": [
    2,
    3
  ]
}
{
  "by_field": "",
  "rows": [
    {
      "by_value": "2018-04-30",
      "total_people": 455,
      "cells": [
        {
          "people": 436,
          "percent": 95.82,
          "bucket_end": 2
        },
        {
          "people": 19,
          "percent": 4.18,
          "bucket_start": 2,
          "bucket_end": 3
        }
      ]
    },
    {
      "by_value": "2018-05-01",
      "total_people": 499,
      "cells": [
        {
          "people": 484,
          "percent": 96.99,
          "bucket_end": 2
        },
        {
          "people": 15,
          "percent": 3.01,
          "bucket_start": 2,
          "bucket_end": 3
        }
      ]
    },
    {
      "by_value": "2018-05-02",
      "total_people": 280,
      "cells": [
        {
          "people": 273,
          "percent": 97.5,
          "bucket_end": 2
        },
        {
          "people": 7,
          "percent": 2.5,
          "bucket_start": 2,
          "bucket_end": 3
        }
      ]
    }
  ],
  "report_update_time": "2018-05-02 17:15:26.739",
  "data_update_time": "2018-05-02 17:14:10.000",
  "data_sufficient_update_time": "2018-05-02 17:14:10.000",
  "truncated": false
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/addictions/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "event_name": "submitOrder",
  "from_date": "2018-04-30",
  "to_date": "2018-05-02",
  "filter": {
    "conditions": [
      {
        "field": "event.submitOrder.$lib",
        "function": "equal",
        "params": [
          "Android"
        ]
      }
    ],
    "relation": "and"
  },
  "user_filter": {
    "conditions": [
      {
        "field": "user.sex",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation": "and"
  },
  "sampling_factor": 64,
  "unit": "day",
  "measure_type": "times",
  "result_bucket_param": [
    2,
    3
  ]
}

'

3.5. 用戶路徑分析報告

[POST /path/analytics/report]

{
  // 起始事件是initial_event, 結束事件是termination_event
  "source_type": "initial_event",
  // 起始事件和對起始事件的過濾
  "source_event": {
    "event_name": "StartApp",
    "filter": {
      "conditions": [
        {
          "field": "event.StartApp.$wifi",
          "function": "isTrue",
          "params": []
        }
      ]
    }
  },
  "event_names": [
    "BuyBullion",
    "BuyGold",
    "SaleGold",
    "StartApp"
  ],
  "by_fields": [
    "event.BuyBullion.$country"
  ],
  // （可選）列數量的限制
  "col_limit": 20,
  // （可選）每列節點數限制
  "row_limit": 7,
  "from_date": "2017-05-01",
  "to_date": "2017-05-22",
  "user_filter": {},
  "bucket_params": {},
  "sampling_factor": 64,
  "session_interval": 1200,
  "use_cache": true
} 
{
  "nodes": [
    [
      {
        "id": "0_StartApp",
        "event_name": "StartApp",
        "times": 27336
      }
    ],
    [
      {
        "id": "1_StartApp",
        "event_name": "StartApp",
        "times": 163
      },
      {
        "id": "1_BuyGold",
        "event_name": "BuyGold",
        "times": 118
      },
      {
        "id": "1_SaleGold",
        "event_name": "SaleGold",
        "times": 104
      },
      {
        "id": "1_BuyBullion_$country_3392903",
        "event_name": "BuyBullion",
        "times": 37
      }
    ],
    [
      {
        "id": "2_SaleGold",
        "event_name": "SaleGold",
        "times": 68
      },
      {
        "id": "2_BuyGold",
        "event_name": "BuyGold",
        "times": 50
      },
      {
        "id": "2_BuyBullion_$country_3392903",
        "event_name": "BuyBullion",
        "times": 18
      },
      {
        "id": "2_StartApp",
        "event_name": "StartApp",
        "times": 2
      }
    ],
    [
      {
        "id": "3_SaleGold",
        "event_name": "SaleGold",
        "times": 39
      },
      {
        "id": "3_BuyGold",
        "event_name": "BuyGold",
        "times": 23
      },
      {
        "id": "3_BuyBullion_$country_3392903",
        "event_name": "BuyBullion",
        "times": 1
      }
    ],
    [
      {
        "id": "4_StartApp",
        "event_name": "StartApp",
        "times": 1
      }
    ]
  ],
  "links": [
    [
      {
        "source": "0_StartApp",
        "target": "1_wastage",
        "is_wastage": true,
        "times": 26914
      },
      {
        "source": "0_StartApp",
        "target": "1_StartApp",
        "times": 163
      },
      {
        "source": "0_StartApp",
        "target": "1_BuyGold",
        "times": 118
      },
      {
        "source": "0_StartApp",
        "target": "1_SaleGold",
        "times": 104
      },
      {
        "source": "0_StartApp",
        "target": "1_BuyBullion_$country_3392903",
        "times": 37
      }
    ],
    [
      {
        "source": "1_StartApp",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 160
      },
      {
        "source": "1_StartApp",
        "target": "2_StartApp",
        "times": 2
      },
      {
        "source": "1_StartApp",
        "target": "2_BuyBullion_$country_3392903",
        "times": 1
      },
      {
        "source": "1_BuyGold",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 68
      },
      {
        "source": "1_BuyGold",
        "target": "2_BuyGold",
        "times": 50
      },
      {
        "source": "1_SaleGold",
        "target": "2_SaleGold",
        "times": 68
      },
      {
        "source": "1_SaleGold",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 36
      },
      {
        "source": "1_BuyBullion_$country_3392903",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 20
      },
      {
        "source": "1_BuyBullion_$country_3392903",
        "target": "2_BuyBullion_$country_3392903",
        "times": 17
      }
    ],
    [
      {
        "source": "2_SaleGold",
        "target": "3_SaleGold",
        "times": 39
      },
      {
        "source": "2_SaleGold",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 29
      },
      {
        "source": "2_BuyGold",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 27
      },
      {
        "source": "2_BuyGold",
        "target": "3_BuyGold",
        "times": 23
      },
      {
        "source": "2_BuyBullion_$country_3392903",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 17
      },
      {
        "source": "2_BuyBullion_$country_3392903",
        "target": "3_BuyBullion_$country_3392903",
        "times": 1
      },
      {
        "source": "2_StartApp",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 2
      }
    ],
    [
      {
        "source": "3_SaleGold",
        "target": "4_wastage",
        "is_wastage": true,
        "times": 38
      },
      {
        "source": "3_SaleGold",
        "target": "4_StartApp",
        "times": 1
      },
      {
        "source": "3_BuyGold",
        "target": "4_wastage",
        "is_wastage": true,
        "times": 23
      },
      {
        "source": "3_BuyBullion_$country_3392903",
        "target": "4_wastage",
        "is_wastage": true,
        "times": 1
      }
    ],
    [
      {
        "source": "4_StartApp",
        "target": "5_wastage",
        "is_wastage": true,
        "times": 1
      }
    ]
  ],
  "truncate_row": [],
  "truncate_col": false,
  "report_update_time": "2017-05-22 11:07:40.544",
  "data_update_time": "2017-05-22 11:06:54.000",
  "data_sufficient_update_time": "2017-05-22 11:06:54.000"
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/path/analytics/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "source_type": "initial_event",
  "source_event": {
    "event_name": "StartApp",
    "filter": {
      "conditions": [
        {
          "field": "event.StartApp.$wifi",
          "function": "isTrue",
          "params": []
        }
      ]
    }
  },
  "event_names": [
    "BuyBullion",
    "BuyGold",
    "SaleGold",
    "StartApp"
  ],
  "by_fields": [
    "event.BuyBullion.$country"
  ],
  "col_limit": 20,
  "row_limit": 7,
  "from_date": "2017-05-01",
  "to_date": "2017-05-22",
  "user_filter": {},
  "bucket_params": {},
  "sampling_factor": 64,
  "session_interval": 1200,
  "use_cache": true
}

'

3.6. 屬性分析報告

[POST /user/analytics/report]

{
  "measures": [
    {
      "aggregator": "count",
      "field": ""
    }
  ],
  "filter": {
    "conditions": [
      {
        "field": "user.HasByGold",
        "function": "isTrue",
        "params": []
      }
    ]
  },
  "by_fields": [
    "user.IncomeLevel",
    "user.Gender"
  ],
  "sampling_factor": null,
  // 橫軸分組指標
  "x_axis_field": "user.IncomeLevel",
  "use_cache": false
} 
{
  "by_fields": [
    "user.Gender"
  ],
  "series": [
    "5000~10000",
    "3000~5000",
    "10000~20000",
    "0~3000",
    null
  ],
  "rows": [
    {
      "values": [
        [
          83169
        ],
        [
          27776
        ],
        [
          55699
        ],
        [
          27892
        ],
        [
          36106
        ]
      ],
      "by_values": [
        "男"
      ]
    },
    {
      "values": [
        [
          55363
        ],
        [
          18208
        ],
        [
          37030
        ],
        [
          18668
        ],
        [
          24090
        ]
      ],
      "by_values": [
        "女"
      ]
    },
    {
      "values": [
        [
          25864
        ],
        [
          8490
        ],
        [
          17327
        ],
        [
          8628
        ],
        [
          17353
        ]
      ],
      "by_values": [
        null
      ]
    }
  ],
  "num_rows": 3,
  "report_update_time": "2017-05-22 14:16:03.595",
  "data_update_time": "1970-01-01 08:00:00.000",
  "data_sufficient_update_time": "1970-01-01 08:00:00.000"
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/user/analytics/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "measures": [
    {
      "aggregator": "count",
      "field": ""
    }
  ],
  "filter": {
    "conditions": [
      {
        "field": "user.HasByGold",
        "function": "isTrue",
        "params": []
      }
    ]
  },
  "by_fields": [
    "user.IncomeLevel",
    "user.Gender"
  ],
  "sampling_factor": null,
  "x_axis_field": "user.IncomeLevel",
  "request_id": 1495433768121,
  "use_cache": false
}

'

3.7. 歸因分析报告

需要注意的是歸因分析報告不支援csv

[POST /attribution/report]

{
  // 開始時間
  "from_date": "2020-06-08",
  // 結束時間
  "to_date": "2020-06-12",
  // 是否使用快取
  "use_cache": false,
  // 直接轉化是否參與歸因計算
  "direct_conversion": true,
  // 抽樣係數
  "sampling_factor": 64,
  // 目標事件
  "target_event": {
    "event_name": "UserLogin",
    // 聚合運算子 可選常規、求和 ["general", "SUM"]
    "aggregator": "SUM",
    // 聚合欄位 運算子為SUM時 此項必填
    "field": "event.AddToShoppingCart.$viewport_position",
    // 目標事件過濾條件
    "filter": {}
  },
  // 前向事件 可設定多個
  "link_events": [
    {
      // 前向事件名稱
      "event_name": "UserLogin",
      // 前向事件關聯屬性
      "link_properties": {
        // 當前前向事件屬性
        "current_event_property": "event.UserLogin.$ip",
        // 目標事件屬性
        "target_event_property": "event.watch.$distinct_id"
      },
      // 前向事件篩選條件
      "filter": {}
    }
  ],
  // 待歸因事件
  "attribution_events": {
    // 事件集合
    "events": [
      {
        "event_name": "watch"
      }
    ],
    // 篩選條件
    "filter": {},
    // 分組
    "by_fields": [
      "event.$Anything.MovieName"
    ]
  },
  // 篩選條件
  "filter": {
    "relation": "and",
    "conditions": []
  },
  // 歸因分析模型可選首次觸點歸因、末次觸點歸因、線性歸因、位置歸因、時間衰減歸因 ["first","last","linear","position","time_decay"]
  "model_type": "first",
  // 歸因窗口期
  "lookback_window": {
    // 窗口期單位可選分鐘、小時、天 ["minute","hour","day"]
    "unit": "day",
    "value": 1
  }
}
{
  "detail_result": {
    "rows": [
      {
        // 沒有【待歸因事件】代表【直接轉換】
        "groups": [
          {
            "by_values": [
              "$ALL"
            ],
            // 待歸因事件總點擊數
            "value": 5,
            // 待歸因事件轉化數量
            "converted_number": 5,
            // 轉化用戶數
            "converted_user_number": 0,
            // 對目標事件的貢獻得分
            "goal_conversion": 5,
            // 對目標事件的貢獻度
            "conversion_value_rate": 100.0
          }
        ]
      },
      {
        // 待歸因事件
        "event_name": "$AppClick",
        "groups": [
          {
            "by_values": [
              "$ALL"
            ],
            "value": 66809,
            "converted_number": 10549,
            "converted_user_number": 8046,
            "goal_conversion": 9991,
            "conversion_value_rate": 100
          }
        ]
      }
    ]
  },
  // 全量快取更新時間
  "report_update_time": "2020-06-12 19:38:29.861",
  // 查詢涉及事件數據的最後更新時間
  "data_update_time": "2020-06-12 10:39:29.000",
  // 查詢涉及事件數據量變化超過 5% 的最後更新時間
  "data_sufficient_update_time": "2020-06-12 10:39:29.000",
  // 查詢是否截斷
  "truncated": false,
  // 抽樣係數
  "sampling_factor": 64
}
curl 'https://golddemo.cloud.sensorsdata.cn/api/attribution/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '
{
  "from_date": "2020-05-13",
  "to_date": "2020-06-11",
  "use_cache": false,
  "direct_conversion": true,
  "target_event": {
    "event_name": "AddToShoppingCart",
    "aggregator": "general",
    "field": "",
    "filter": {}
  },
  "link_events": [],
  "attribution_events": {
    "events": [
      {
        "event_name": "$AppClick"
      }
    ],
    "filter": {
      "relation": "and",
      "conditions": []
    },
    "by_fields": []
  },
  "filter": {
    "relation": "and",
    "conditions": []
  },
  "model_type": "first",
  "lookback_window": {
    "unit": "day",
    "value": 1
  }
}
'

使用 curl 時需注意 網址是 https 還是 http

4. 用戶明細查詢

用戶明細系列介面用於查詢某一個特定分析報告中的具體用戶列表，請求的大部分參數與分析報告相同，新增的參數會在每個介面裡具體說明。用戶列表也支援 JSON 和 CSV 兩種格式，預設式 JSON 格式，如果需要 CSV 格式的數據可以手動指定 format 參數。例如事件分析的用戶列表對應的 CSV 格式的 URL 為: /events/user/list?format=csv。

4.1. 事件分析用戶明細報告

[POST /events/user/list]

{
  "measures": [
    {
      "aggregator": "unique",
      "event_name": "SaleGold"
    }
  ],
  "filter": {
    "conditions": [
      {
        "field": "event.SaleGold.$city",
        "function": "equal",
        "params": [
          "廈門市"
        ]
      },
      {
        "field": "event.SaleGold.$app_version",
        "function": "equal",
        "params": [
          "1.7"
        ]
      }
    ]
  },
  "by_fields": [
    "event.SaleGold.$app_version",
    "event.SaleGold.$screen_width"
  ],
  "rollup_date": false,
  "unit": "week",
  // 查看哪個分組的用戶明細
  "slice_by_values": [
    "1.7",
    1080
  ],
  // 查看哪天的用戶明細,比如2015年8月18號當週
  "slice_date": "2015-08-18 00:00:00",
  // 是否展示詳情，如果 true，則會按照 profile 中的列回傳，false 則只回傳基本的 id 列
  "detail": true,
  // 預設值30，表示每頁展示用戶數，可不加 
  "num_per_page": 10,
  // 請求的頁面 
  "page":1,
  // 限制回傳的條數
  "limit": 100000,
  // 是否回傳所有用戶，如果為 true，則會無視分頁參數，否則需要加上分頁參數 
  "all_page": true
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陳爍簣",
        "IncomeLevel": "3000~5000",
        "$city": "德陽市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪關市",
        "$province": "甘肅省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1, // 頁數，總人數/每頁展示用戶數
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/events/user/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "measures":[
        {
            "aggregator":"unique",
            "event_name":"SaleGold"
        }
    ],
    "filter":{
        "conditions":[
            {
                "field":"event.SaleGold.$city",
                "function":"equal",
                "params":[
                    "厦门市"
                ]
            },
            {
                "field":"event.SaleGold.$app_version",
                "function":"equal",
                "params":[
                    "1.7"
                ]
            }
        ]
    },
    "by_fields":[
        "event.SaleGold.$app_version",
        "event.SaleGold.$screen_width"
    ],
    "rollup_date":false,
    "unit":"week",
    "slice_by_values":[
        "1.7",
        1080
    ],
    "slice_date":"2015-08-18 00:00:00",
    "detail":true,
    "num_per_page":10,
    "page":1,
    "limit":100000,
    "all_page":true
}

'


4.2. 漏斗分析用戶明細報告

[POST /funnels/user/list]

{
  "funnel_id": 158,
  "from_date": "2015-04-17",
  "to_date": "2015-07-16",
  "filter": {
    "conditions": [
      {
        "field": "event.$Anything.$lib_version",
        "function": "contain",
        "params": [
          "0.1.0"
        ]
      },
      {
        "field": "event.$Anything.$lib",
        "function": "contain",
        "params": [
          "python"
        ]
      },
      {
        "field": "user.Gender",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation": "and"
  },
  "by_field": "event.SaleGold.$lib_version",
  // 用戶明細的分群值
  "slice_by_value": "0.1.0",
  // 用戶明細的步驟
  "slice_step": 0,
  // true 表示查看流失用戶明細，false 表示轉化用戶
  "slice_wastage_user": false,
  // 是否展示詳情，如果 true，則會按照 profile 中的列回傳，false 則只回傳基本的 id 列
  "detail": true,
  // 請求的頁數 
  "page":1,
  // 每頁數據條數
  "num_per_page": 30,
  // 限制回傳的條數
  "limit": 100000,
  // 是否回傳所有用戶，如果為 true，則會無視分頁參數，否則需要加上分頁參數
  "all_page": true
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陳爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德陽市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪關市",
        "$province": "甘肅省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/funnels/user/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "funnel_id":158,
    "from_date":"2015-04-17",
    "to_date":"2015-07-16",
    "filter":{
        "conditions":[
            {
                "field":"event.$Anything.$lib_version",
                "function":"contain",
                "params":[
                    "0.1.0"
                ]
            },
            {
                "field":"event.$Anything.$lib",
                "function":"contain",
                "params":[
                    "python"
                ]
            },
            {
                "field":"user.Gender",
                "function":"equal",
                "params":[
                    "男"
                ]
            }
        ],
        "relation":"and"
    },
    "by_field":"event.SaleGold.$lib_version",
    "slice_by_value":"0.1.0",
    "slice_step":0,
    "slice_wastage_user":false,
    "detail":true,
    "page":1,
    "num_per_page":30,
    "limit":100000,
    "all_page":true
}

'

4.3. 留存分析用戶明細報告

[POST /retentions/user/list]

{
  "first_event": {
    "event_name": "BuyGold",
    "filter": {
      "conditions": [
        {
          "field": "event.BuyGold.$lib_version",
          "function": "contain",
          "params": [
            "0.1.0"
          ]
        }
      ]
    }
  },
  "second_event": {
    "event_name": "StartApp"
  },
  // 是否流失用戶，預設留存用戶
  "is_wastage": false,
  // 指定哪些用戶屬性，為空表示所有用戶屬性
  "profiles": [],
  "duration": 7,
  "from_date": "2015-07-21",
  "to_date": "2015-07-24",
  "unit": "day",
  "by_field": "event.SaleGold.$lib_version",
  // 用戶明細分的分組值
  "slice_by_value": "0.1.0",
  // 查看第幾天留存的用戶明細，0 表示當天，null 表示全部
  // 表示隨後第幾天留存
  "slice_interval": 1,
  // 是否展示詳情，如果 true，則會按照 profile 中的列回傳，false 則只回傳基本的 id 列
  "detail": true,
  // 請求的頁數 
  "page":1,
  // 每頁數據條數
  "num_per_page": 30,
  // 限制回傳的條數
  "limit": 100000,
  // 是否回傳所有用戶，如果為 true，則會無視分頁參數，否則需要加上分頁參數
  "all_page": true
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陳爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德陽市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪關市",
        "$province": "甘肅省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/retentions/user/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "first_event":{
        "event_name":"BuyGold",
        "filter":{
            "conditions":[
                {
                    "field":"event.BuyGold.$lib_version",
                    "function":"contain",
                    "params":[
                        "0.1.0"
                    ]
                }
            ]
        }
    },
    "second_event":{
        "event_name":"StartApp"
    },
    "is_wastage":false,
    "profiles":[

    ],
    "duration":7,
    "from_date":"2015-07-21",
    "to_date":"2015-07-24",
    "unit":"day",
    "by_field":"event.SaleGold.$lib_version",
    "slice_by_value":"0.1.0",
    "slice_interval":1,
    "detail":true,
    "page":1,
    "num_per_page":30,
    "limit":100000,
    "all_page":true
}

'

4.4. 分佈分析用戶明細報告

[POST /addictions/user/list]

{
  "event_name": "BuyGold",
  "filter": {
    "conditions": [
      {
        "field": "event.BuyGold.$lib_version",
        "function": "contain",
        "params": [
          "0.1.0"
        ]
      }
    ]
  },
  "rollup_date": false,
  "from_date": "2015-04-22",
  "to_date": "2015-04-22",
  "unit": "day",
  "by_field": "event.SaleGold.$lib_version",
  // 用戶明細的分組資訊
  "slice_by_value": "0.1.0",
  // 查看回訪頻率為多少的用戶明細
  "slice_freq": 2,
  "detail": true,
  // 請求的頁數 
  "page":1,
  // 每頁數據條數
  "num_per_page": 30,
  // 限制回傳的條數
  "limit": 100000,
  // 是否回傳所有用戶，如果為 true，則會無視分頁參數，否則需要加上分頁參數
  "all_page": true
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陳爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德陽市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪關市",
        "$province": "甘肅省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/addictions/user/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "event_name":"BuyGold",
    "filter":{
        "conditions":[
            {
                "field":"event.BuyGold.$lib_version",
                "function":"contain",
                "params":[
                    "0.1.0"
                ]
            }
        ]
    },
    "rollup_date":false,
    "from_date":"2015-04-22",
    "to_date":"2015-04-22",
    "unit":"day",
    "by_field":"event.SaleGold.$lib_version",
    "slice_by_value":"0.1.0",
    "slice_freq":2,
    "detail":true,
    "page":1,
    "num_per_page":30,
    "limit":100000,
    "all_page":true
}

'

4.5. 用戶列表明細報告

[POST /users/list]

{
  "filter": {
    "conditions": [
      {
        // 這裡可以任意增加篩選條件
        // 可以指定指分群或標籤名，如想取得某個分群的用戶，則指定 為 'user.fenqun1'
        // 也可以指定普通屬性名，如 'user.birthday'
        // 更多的用法請參考上面的篩選表達式說明
        "field": "user.test",
        "function": "isTrue"
      }
    ]
  },
  "profiles": [
    // 請求的用戶屬性列表
    "user.$utm_source"
  ],
  // 請求的頁數，從 0 開始，0 代表第一頁 
  "page":0,
  // 每頁數據條數
  "num_per_page": 30,
  // 限制回傳的條數
  "limit": 100000,
  // 是否回傳所有用戶，如果為 true，則會無視分頁參數，否則需要加上分頁參數
  "all_page": true
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陳爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德陽市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪關市",
        "$province": "甘肅省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/users/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "filter":{
        "conditions":[
            {
                "field":"user.test",
                "function":"isTrue"
            }
        ]
    },
    "profiles":[
        "user.$utm_source"
    ],
    "page":0,
    "num_per_page":30,
    "limit":100000,
    "all_page":true
}

'

這個介面也可以指定要查詢的用戶id，這樣能取得指定用戶的屬性資訊。

{
  "filter":{
    "conditions":[
      {
        "field":"user.test",
        "function":"isTrue"
      }
    ]
  },
  "users":["1902482830", "3834577070"],
  "profiles":[
    "user.$utm_source"
  ]
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陳爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德陽市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪關市",
        "$province": "甘肅省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/users/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
  "filter":{
    "conditions":[
      {
        "field":"user.test",
        "function":"isTrue"
      }
    ]
  },
  "users":["1902482830", "3834577070"],
  "profiles":[
    "user.$utm_source"
  ]
}

'

4.6. 用戶路徑用戶明細報告

[POST /users/list]

{
  "slice_element_filter": [
    {
      "slice_event_name": "StartApp",
      "slice_by_value": "8.1"
    }
  ],
  "next_slice_element_filter": [
    {
      "slice_event_name": "SaleGold",
      "slice_by_value": "1"
    }
  ], // 合計，後續事件統計和流失不需要這個過濾條件
  "session_level": "0", // 源端的層數
  "source_type": "initial_event",
  "source_event": {
    "event_name": "StartApp",
    "filter": {
      "conditions": [
        {
          "field": "event.StartApp.$wifi",
          "function": "isTrue"
        }
      ]
    }
  },
  "event_names": [
    "BuyBullion",
    "BuyGold",
    "SaleGold",
    "StartApp"
  ],
  "by_fields": [
    "event.SaleGold.$wifi",
    "event.StartApp.$os_version"
  ],
  "session_interval": "1200",
  "from_date": "2017-05-01",
  "to_date": "2017-05-22",
  "detail": true,
  "col_limit": "20",
  "row_limit": "7",
  "sampling_factor": 64,
  "is_aggregate": "false", // 當前節點是否表示更多
  "edge_type": "ALL", // 可以是 WASTAGE，RETENTION 和 ALL，分别表示流失節點，後續事件統計，該節點合計人數
  "is_next_aggregate": "false", // 後續節點是否表示更多
  "num_per_page": 50,
  "all_page": true,
  "filter": {},
  "use_cache": false
}
{
  "users": [
    {
      "id": "1902482830",
      "first_id": "23e3ff2a3ff1e1bc",
      "second_id": "1696144579",
      "profiles": {
        "FavoriteFruits": [
          "Raspberry",
          "Orange"
        ],
        "$name": "陳爍簀",
        "IncomeLevel": "3000~5000",
        "$city": "德陽市",
        "$province": "四川省",
        "$signup_time": 1.432805251963E12,
        "Gender": "男",
        "Age": 20.0
      }
    },
    {
      "id": "3834577070",
      "first_id": "51b0fecc44b5c75b",
      "second_id": "1602971488",
      "profiles": {
        "FavoriteFruits": [
          "Cranberry",
          "Guava",
          "cantaloupe"
        ],
        "$name": "周瀌狙",
        "IncomeLevel": "10000~20000",
        "$city": "嘉峪關市",
        "$province": "甘肅省",
        "$signup_time": 1.432799799529E12,
        "Gender": "女",
        "Age": 20.0
      }
    }
  ],
  "size": 2,
  "page_num": 1,
  "column_name":[
    "FavoriteFruits",
    "$name",
    "Age",
    "Gender",
    "IncomeLevel",
    "$signup_time",
    "$city",
    "$province"
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/users/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "slice_element_filter":[
        {
            "slice_event_name":"StartApp",
            "slice_by_value":"8.1"
        }
    ],
    "next_slice_element_filter":[
        {
            "slice_event_name":"SaleGold",
            "slice_by_value":"1"
        }
    ],
    "session_level":"0",
    "source_type":"initial_event",
    "source_event":{
        "event_name":"StartApp",
        "filter":{
            "conditions":[
                {
                    "field":"event.StartApp.$wifi",
                    "function":"isTrue"
                }
            ]
        }
    },
    "event_names":[
        "BuyBullion",
        "BuyGold",
        "SaleGold",
        "StartApp"
    ],
    "by_fields":[
        "event.SaleGold.$wifi",
        "event.StartApp.$os_version"
    ],
    "session_interval":"1200",
    "from_date":"2017-05-01",
    "to_date":"2017-05-22",
    "detail":true,
    "col_limit":"20",
    "row_limit":"7",
    "sampling_factor":64,
    "is_aggregate":"false",
    "edge_type":"ALL",
    "is_next_aggregate":"false",
    "num_per_page":50,
    "all_page":true,
    "filter":{

    },
    "use_cache":false
}

'

5. 自定義查詢和用戶行為列表

5.1. 自定義查詢

[POST /sql/query]

透過 SQL 進行自定義查詢，表結構及自定義查詢方法詳見 自定義查詢 功能的介紹。

  • Parameters
  • q: 查詢的 SQL，例如 SELECT event,time,user_id FROM events LIMIT 10。
  • format: 可能的值包括
    • csv：預設格式
    • json：每行一個 JSON
    • event_json：匯出可以用於直接匯入的 Event Track 格式的 Json，1.*.3338 之後的版本支援，且不支援使用別名（select $utm_source as utm_source ……）
    • profile_json：匯出可以用於直接匯入的 Profile Set/Track Signup 格式的 Json，1.*.3338 之後的版本支援，且不支援使用別名（select $utm_source as utm_source ……）
    • item_json: 匯出可以用戶直接匯入神策系統的 item_set 格式的 Json，1.15.1646 及之後的版本才支援，且不支援使用別名（select $utm_source as utm_source ……）
    • sql：不直接回傳數據，而是翻譯為一條可以直接在 Spark/Impala/Hive 裡執行的 SQL

q=SELECT * FROM events LIMIT 10

format=csv

event time user_id
RechargeCash 2015-09-02 13:01:00.125336 1731174795
RechargeCash 2015-09-02 02:02:48.133002 1751664241
RechargeCash 2015-09-02 13:01:53.308174 1784316911
RechargeCash 2015-09-02 09:09:07.784417 1793667170
RechargeCash 2015-09-02 09:09:42.420781 1807294808
RechargeCash 2015-09-02 16:04:06.211421 1808422371
RechargeCash 2015-09-02 08:08:44.646672 1810351186
RechargeCash 2015-09-02 00:12:20.456509 1874214895
RechargeCash 2015-09-02 02:02:38.494175 1897237370
RechargeCash 2015-09-02 15:03:08.338102 2012805794

該介面和其它 API 的呼叫方式有所不同，q 參數直接用 GET/POST 參數傳遞即可，csv 格式回傳的數據為 \t 分隔。一個使用 curl 的例子如下:

curl 'https://saasdemo.cloud.sensorsdata.cn/api/sql/query?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \

-X POST \

--data-urlencode "q=SELECT * FROM events LIMIT 10" \

--data-urlencode "format=csv"

注意： （1）如果查詢的事件是預設事件，那麼 $ 符號需要使用 \ 進行轉義。 （2）如果是匯出 items 表中的數據，需要確保神策系統版本為 1.15.1646 及之後的版本。

5.2. 用戶行為列表

[POST /users/event/list]

取得一個或者多個用戶在某一段時間內的詳細行為資訊。

{
  "users": [
    86015190,
    81952822,
    87961512
  ],
  "from_date": "2015-04-22",
  "to_date": "2015-04-22",
  // false 表示 users 參數指定的是内部的 user_id，true 表示傳入的是 distinct_id
  "distinct_id": false
}
{
  "events": [
    {
      "user_id": "422337220",
      "event": "SaleGold",
      "time": 1432822231055,
      "properties": {
        "$province": "遼寧省",
        "$screen_height": 640.0,
        "$city": "大連市",
        "$os": "iOS",
        "$screen_width": 320.0,
        "$model": "iPhone 5",
        "$lib_version": "0.1.0",
        "$app_version": "1.3",
        "$manufacturer": "Apple",
        "$os_version": "7.0",
        "$wifi": 1.0,
        "$lib": "python",
        "SaleStep": 1.0
      }
    },
    {
      "user_id": "422337220",
      "event": "SaleGold",
      "time": 1432822232022,
      "properties": {
        "$province": "遼寧省",
        "$screen_height": 640.0,
        "$city": "大連市",
        "$os": "iOS",
        "$screen_width": 320.0,
        "$model": "iPhone 5",
        "$lib_version": "0.1.0",
        "$app_version": "1.3",
        "$manufacturer": "Apple",
        "$os_version": "7.0",
        "$wifi": 1.0,
        "$lib": "python",
        "GoldPrice": 240.34,
        "GoldWeight": 16153.0,
        "SaleStep": 2.0
      }
    }
  ]
}

curl 'https://golddemo.cloud.sensorsdata.cn/api/users/event/list?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '

{
    "users":[
        86015190,
        81952822,
        87961512
    ],
    "from_date":"2015-04-22",
    "to_date":"2015-04-22",
    "distinct_id":false
}

'

6. 常見問題

6.1. 查詢 API 提示 {"error":"沒有訪問權限，請檢查 project 和 token"} ？

首先：檢查數據接收網址的域名是不是客戶系統自己環境登入系統的域名（注意，不是數據接收網址的域名哦）

其次：檢查 project 和 token 是不是同一個專案的參數

最後：檢查 token 是 admin 帳號下的 API Secret 還是透過自己的帳號密碼取得的 Access token。如果是 API Secret ，token 直接放在 url 連結後面。如果是 Access token ，token 參數不能直接放在 url 連結後面 ，需要放在 Header 參數中，即增加參數：

-H 'sensorsdata-token: {取得的 Access token}'

具體可參考此文件：http://manual.sensorsdata.cn/sa/latest/page-1573880.html#id-.%E5%8A%9F%E8%83%BDAPIv1.13-%E8%8E%B7%E5%8F%96ACCESS_TOKEN

6.2. 查詢引擎錯誤

可以檢查查詢的 API 介面和參數名是否對應，以及設定的參數格式是否正確。

6.3. 報錯API return 422

API SQL 查詢時，$ 符號需要轉譯

6.4. API 查詢或者下載用戶列表等使用後台分析服務時，504報錯

服務轉發設定沒有設定連接超時時間或者超時時間設定較短，讓客戶修改超時時間即可。一般我們建議數據接收網址超時時間為 60 ，後台分析服務超時時間為 1800。

6.5. 是否可以使用查詢 API 將查詢結果回傳到客戶線上的業務用於實時分析？查詢 API 的請求頻次有什麼限制？

神策查詢 API 只適合低頻呼叫，相應速度取決如下兩方面：

  1. 實際的查詢場景：如數據量、查詢數據的時間範圍、所用的分析模型或 SQL 的複雜度等；
  2. 硬體和網路設定：如 CPU、記憶體、網卡、硬碟等

在查詢場景和神策伺服器設定匹配的前提下，神策建議 API 呼叫頻率保持在分鐘級，單次查詢的數據範圍在 1 萬條以內，同一時間最大併發請求量不超過 10 個，以確保查詢相應和神策服務性能穩定。如條件超出如上描述範圍，可能出現無法回應/查詢慢/甚至神策服務性能不穩定情況。

如上為神策根據歷史對接經驗給出，考慮到不同客戶查詢呼叫的場景各有差異，建議以實測為準，根據實際測試結果合理調整查詢條件和呼叫頻次。