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

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

神策分析提供一系列功能 API，利用這些 API 可以：

設定數據概覽;
設定用戶分群;
取得埋點統計報告;
取得某個用戶的連接 TOKEN;

1. 呼叫方法

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

2. 數據概覽

2.1. 增加數據概覽

> [POST /dashboards]

+ Request (application/json)

{
 "name": "轉化漏斗分析"，
 "is_public": 0 // 0表示僅自己可見，1表示所有用戶可見
}

+ Response 200 (application/json)

{
"id": 2 // dashboard id 
}

2.2. 刪除數據概覽

> [DELETE /dashboards/{dashboardId}]

+ 使用 curl 範例

// $ID 為對應概覽的 id，可由下面取得所有概覽的 API 介面取得
curl 'https://golddemo.cloud.sensorsdata.cn/api/dashboards/$ID?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'

2.3. 取得所有數據概覽

> [GET /dashboards]

+ Response 200 (application/json)

[
  {
    "id": 1,
    "name": "行銷數據分析",
    "create_time": "2015-11-04 16:34:33",
    "user_id": 1,
    "is_default": 0,
    "is_public": 1,
    "username": "admin",
    "project_id": 1,
    "config": "{\"widgetTime\":\"0 week\",\"widgetUnit\":\"minute\"}"
  },
  {
    "id": 3,
    "name": "產品黏性分析",
    "create_time": "2015-11-04 17:38:29",
    "user_id": 1,
    "is_default": 0,
    "is_public": 1,
    "username": "admin",
    "project_id": 1
  }
]

2.4. 取得某個數據概覽的詳情

>［GET /dashboards/{dashboardId}］

+ Response 200 (application/json)

{
  "id": 1, // 數據概覽的id
  "name": "行銷數據分析", // 數據概覽的名稱
  "create_time": "2015-11-04 16:34:33", // 數據概覽的建立時間
  "user_id": 1,
  "is_default": 0,
  "is_public": 1,
  "username": "admin",
  "items": [
    {
      "bookmark": {
        "id": 1, // 書籤id
        "type": "/segmentation/",
        "name": "每天不同管道帶來的用戶數",
        "data": "{\"measures\":[{\"event_name\":\"views\",\"aggregator\":\"unique\"}],\"unit\":\"day\ ",\"by_fields\":[\"user.first_visit_channel\"],\"chartsType\":\"line\",\"sampling_factor\":64,\"from_date\":\"2016-06- 20\",\"to_date\":\"2016-06-26\",\"bookmarkid\":\"1\",\"bookmarktime\":\"7 day\",\"rollup_date\" :\"false\",\"filter\":{}}",
        "time": "7 day",
        "create_time": "2015-11-04 04:35:44",
        "user_id": 1,
        "dashboards": [],
        "related_events": [
          "views"
        ],
        "project_id": 1
      },
      "config": "{\"widgetIndex\":2,\"widgetByValues\":[\"百度\",\"36kr\",\"今日頭條\"],\"widgetType\":\"column \",\"widgetTime\":\"7 day\",\"widgetUnit\":\"day\",\"widgetRememberType\":{\"unit\":\"column\"}}",
      "bookmark_id": 0
    },
    {
      "bookmark": {
        "id": 183,
        "type": "/segmentation/",
        "name": "每天不同管道提交線索數",
        "data": "{\"measures\":[{\"event_name\":\"applies\",\"aggregator\":\"unique\"}],\"unit\":\"month\ ",\"by_fields\":[\"user.first_visit_channel\"],\"chartsType\":\"line\",\"sampling_factor\":64,\"from_date\":\"2016-01- 01\",\"to_date\":\"2016-06-20\",\"filter\":{}}",
        "time": "7 day",
        "create_time": "2016-06-27 07:24:23",
        "user_id": 1,
        "dashboards": [],
        "related_events": [
          "applies"
        ],
        "project_id": 1
      },
      "config": "{\"widgetIndex\":3,\"widgetByValues\":[\"百度\",\"36kr\",\"今日頭條\"],\"widgetType\":\"line \",\"widgetTime\":\"7 day\",\"widgetUnit\":\"day\",\"widgetRememberType\":{\"unit\":\"line\"}}",
      "bookmark_id": 0
    }
  ],
  "project_id": 1,
  "config": "{\"widgetTime\":\"0 week\",\"widgetUnit\":\"minute\"}"
}

2.5. 保存書籤到數據概覽

> [POST /bookmarks/bookmark]

保存書籤到數據概覽時，書籤類型可以是事件分析，漏斗分析，留存分析，分佈分析，對應的 type 分別是 /segmentation/, /funnel/, /retention/, /addiction/。 data 是對應的 request，request 寫法參考第三節。

+ Request (application/json)

{
  "related_events": [
    "Share"
  ],
  "name": "分享的總次數", // 書籤名稱
  "dashboards": [
    2 // 數據概覽的id
  ],
  "type": "/segmentation/",
  "data": "{\"measures\":[{\"event_name\":\"Share\",\"aggregator\":\"general\"}],\"unit\":\"day\ 		",\"chartsType\":\"line\",\"sampling_factor\":64,\"rangeText\":\"本週\",\"from_date\":\"2016-10-17\" ,\"to_date\":\"2016-10-	20\",\"filter\":{}}"
}

+ Response 200 (application/json)

{
    "id": 1  //書籤id      
}

2.6. 取得書籤設定

> [GET /bookmarks/bookmark/{bookmarkId}]

書籤設定包括類型、名稱和具體的查詢條件。

+ Response 200 (application/json)

{
  "id" : 26,
  "type" : "/segmentation/",
  "name" : "過去一週每個品類的每日瀏覽總數",
  "data" : "{\"unit\":\"day\",\"filter\":{},\"by_fields\":[\"event.ViewProduct.ProductType\"],\"chartsType\" :\"line\",\"to_date\":\"2015-08-28\",\"from_date\":\"2015-05-29\",\"measures\":[{\"event_name \":\"ViewProduct\",\"aggregator\":\"general\"}]}",
  "time" : "1 week",
  "create_time" : "2015-08-29 04:09:24",
  "user_id" : 1,
  "dashboards" : [ 5 ],
  "project_id" : 1
}

2.7. 刪除一個數據概覽中的書籤

> ［DELETE /bookmarks/bookmark/{bookmarkId}］

3. 用戶分群

1.13 的分群 API 相對於 1.12 版本，有不相容的改動。詳情請參考兩個版本各自的文件。

用戶分群

4. 埋點統計

埋點統計 API

5. 用戶 TOKEN

使用 API_SECRET 可以滿足各種查詢需求，但如果希望取得與某個唯一用戶對應的 ACCESS_TOKEN 可以參考本節的方法。當取得 ACCESS_TOKEN 後，請求不需要再使用 API_SECRET。該 ACCESS_TOKEN 與每個專案中的用戶帳號唯一對應，可使用的權限與該用戶在這個專案中分配角色所授予的數據查看和事件使用權限保持一致。

僅當需要進行“與某個用戶相關的操作”時才需使用“用戶 TOKEN”，例如為某個用戶設定概覽。若僅使用查詢 API，請參考 [API 文件](api.md) 的 1. 呼叫方法使用 `$API_SECRET` 即可；
對於每個用戶，最多同時有效的 ACCESS_TOKEN 為 20 個。當一個用戶已經有 20 個 ACCESS_TOKEN 時，再取得新的 ACCESS_TOKEN 將使該用戶之前有效的 ACCESS_TOKEN 裡面取得時間最早的一個失效；
使用瀏覽器透過神策介面進行登入取得的 ACCESS_TOKEN 與透過該 API 取得的等價，上一條的 20 個限制同樣適用，例如透過 API 取得時觸發 20 個上限，淘汰了用介面登入保存在瀏覽器裡的 ACCESS_TOKEN，則將導致瀏覽器的登入失效；

5.1. 取得 ACCESS_TOKEN

5.1.1. 使用 API_SECRET 並指定用戶名來取得該用戶的 ACCESS_TOKEN，使用 curl 連接：

curl -v 'http://$WEB_URL/api/auth/login?token=$API_SECRET&project=$PROJECT' \
-X POST -H 'Content-Type: application/json' \
--data '{"username":"user1"}'

Response 範例:

{
    "role":0,
    "user_id":7,
    "token":"de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f0022c851df846b0401b",
    "username":"user1",
    "event_permission":{
        "type":"ALL",
        "events":[]
    }
}

5.1.2. 神策系統版本 < 1.15 時，使用用戶名稱和密碼模擬登入取得該用戶的 ACCESS_TOKEN，使用 curl 請求命令如下：

curl -v 'http://$WEB_URL/api/auth/login?project=$PROJECT' \
-X POST -H 'Content-Type: application/json' \
--data '{"username":"user1","password":"123456"}'

Response 範例:

{   
    "role":0,
    "user_id":7,
    "token":"de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f0022c851df846b0401b",
    "username":"user1",
    "event_permission":{
        "type":"ALL"
        "events":[]
    }
}

注意：

1.13.5619 及之後某個版本支援開通驗證碼的方式登入，如果客戶開啟驗證碼的方式的登入，透過上述方式取得 ACCESS_TOKEN 時會提示“驗證碼錯誤或者已過期”。建議直接用 API_SECRET 的方式取得 ACCESS_TOKEN。
目前僅支援專案帳號透過此方式取得Token.

5.1.3. 神策系統版本 >= 1.15 時，使用用戶名稱和密碼模擬登入取得該用戶的 ACCESS_TOKEN，使用 curl 請求命令如下：

curl -v 'http://$WEB_URL/api/v2/auth/login?project=$PROJECT' \
-X POST -H 'Content-Type: application/json' \
--data '{"account_name":"user1","password":"123456", "expired_interval": 259200}'

Response 範例:

{   
    "account_name":0,
    "account_id":7,
    "session_id":"de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f0022c851df846b0401b"
}

注意：

1.13.5619 及之後某個版本支援開通驗證碼的方式登入，如果客戶開啟驗證碼的方式的登入，透過上述方式取得 ACCESS_TOKEN 時會提示“驗證碼錯誤或者已過期”。建議直接用 API_SECRET 的方式取得 ACCESS_TOKEN。
如果使用的是平台帳號，務必在請求的 URL 中增加參數 "is_global=true".

5.1.4. 指定 ACCESS_TOKEN 的過期時間

在 1.13 以及之前的版本，access_token 的有效期預設是 7 天。（這個 7 天是指距離最後一次連接時的時間間隔）。 1.14 版本及之後的版本，access_token 的有效期預設是 30 分鐘。

在 1.12 以及之後的版本中，可透過指定時間來延長 access_token 的過期時間，最長可延長到六個月的時間。請求範例如下：

curl -v 'http://$WEB_URL/api/auth/login?token=$API_SECRET&project=$PROJECT' \
-X POST -H 'Content-Type: application/json' \
--data '{"username":"user1", "expired_interval": 259200}'

回傳結果與普通的取得 ACCESS_TOKEN 相同。其中請求的參數中，透過 expired_interval 指定過期時間，單位為分鐘。範例中 259200 分鐘即為最長的過期時間: 180 天。這個過期時間，是指距離最後一次請求的時間，並不是產生 ACCESS_TOKEN 的時間。也就是說，只有你180 天沒有使用該帳號連接過系統，或者沒有使用這個 ACCESS_TOKEN 請求數據，才會過期。

注意：刪除帳號或者修改帳號密碼，之前取得的 ACCESS_TOKEN 都會失效。

5.1.5. 使用 ACCESS_TOKEN

上一節的 Response 中的 token 欄位即該用戶的 ACCESS_TOKEN，其他 API 請求使用該 ACCESS_TOKEN 可透過指定 Header `sensorsdata-token`，例如查詢事件分析報告使用 ACCESS_TOKEN:

curl -v 'https://saasdemo.cloud.sensorsdata.cn/api/events/report' \
-H 'sensorsdata-token: de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f0022c851df846b0401b' \
-H 'Content-Type: application/json' \
--data-binary '{
    "measures":[
        {
            "event_name":"FinalConvert",
            "aggregator":"SUM",
            "field":"event.FinalConvert.contract_value"
        }
    ],
    "unit":"day",
    "by_fields":[
        "event.FinalConvert.product_type"
    ],
    "to_date":"2016-08-14",
    "from_date":"2016-08-14"
}'