This document describes advanced features of Sensing Analysis, involving many technical details, and is intended for experienced users. If you have any questions about the content of the document, please consult Sensing on-duty colleagues for one-on-one assistance.

In addition to the powerful UI analysis interface, Sensing Analysis also provides comprehensive APIs.

The APIs in Sensing Analysis can be roughly divided into two categories:

Query API: Consistent with the analysis model capability, mainly used to obtain various data analysis reports and user lists;
API Features: Including Overview Management API and User Group Management API;

1. Call steps:

In this example, we take the "API_SECRET authentication method" as an example. If you want to use the "user ACCESS_TOKEN authentication method", please refer to section 2 "user ACCESS_TOKEN authentication method".

1.1. Concatenate the request URL

The API uses standard HTTP/HTTPS request. The complete URL structure is divided into:

http(s)://$WEB_URL/api/$API_URL?token=$API_SECRET&project=$PROJECT

Request URL structure	Meaning	How to obtain
$WEB_URL	Sensing Analysis access address
$API_URL	Specific Method API	For example, the API of Event Analysis model is /events/report
$PROJECT	English name of the project	After logging into the specific project, extract the value corresponding to the project parameter from the URL address in the browser.
$API_SECRET	Token for user authentication	Note:You can obtain it as user admin For versions below 2.2: 【Basic Settings】 -> 【API_SECRET】 For versions 2.2 and above, go to 【系统设置】-【项目设置】

An example of the final concatenated request address using the above method: (The example cannot be directly used)

https://family.demo.sensorsdata.cn/api/funnel/report?token=xxxxxxxxxx&project=EbizDemo

Matters needing attention：

Changing the password of the admin account changes API_SECRET.
API_SECRET of platform administrators can access data from all projects, while API_SECRET of project administrators can only access data from their own project.
API_SECRET and the token used for data import are not related.

1.2. Get request parameters quickly.

Because the parameter structure of most query APIs is complex, it is often difficult to organize them for first-time use. Here, it is recommended to access the Sensordata Analytics platform through a browser to obtain the required parameters. The method is as follows:

as follows:

Take the event analysis report /events/report request parameters in Chrome browser as an example:

The steps are as follows:

Open Sensors Analytics in Chrome and configure the query conditions in the event analysis model.
Open the browser's developer tools. The operation is shown in the screenshot below:

Click "Query" and in the browser console network, use the filter to filter out the target URL [/events/report]. Then, on the right side, find "Request Payload" and click "view parsed" to copy the target request parameters.

1.3. Use curl to make requests.

After concatenating the URL and modifying the parameters, you can use any HTTP client to call the API.

curl example:

curl 'https://saasdemo.cloud.sensorsdata.cn/api/events/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d' \ -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" }'

TEXT

2. USER ACCESS_TOKEN

This ACCESS_TOKEN corresponds uniquely to the user account in each project. The permissions available are consistent with the data permissions and functional usage permissions granted to the user in this project through role assignment. Unlike API_SECRET, ACCESS_TOKEN cannot be directly authenticated by carrying it as a request parameter. For specific usage, please refer to "2.4. Using ACCESS_TOKEN".

2.1. Use cases:

To use "user token" only when "performing operations related to a specific user", such as setting an overview for a specific user, or getting a list of groups visible to an account with a certain permission scope, if you want to use the query API to obtain all event data, you can use the API_SECRET.

2.2. Usage Restrictions

2.2.1. Number Limit

For each user, the maximum number of simultaneous ACCESS_TOKENs is 20. When a user already has 20 ACCESS_TOKENs, obtaining a new ACCESS_TOKEN will invalidate the earliest ACCESS_TOKEN obtained by that user;

ACCESS_TOKEN obtained through login via the SensData interface using a browser is equivalent to those obtained through this API. The previous limit of 20 still applies. For example, if the limit of 20 is reached when obtaining via the API, and the ACCESS_TOKEN stored in the browser from the interface login is phased out, it will cause the browser login to become invalid;

2.2.2. Validity Period Limit

The default validity period of ACCESS_TOKEN is 30 minutes, and can be specified by "expired_interval" in minutes. The upper limit is 259,200 minutes (180 days).

curl example:

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}'

TEXT

Note:

Deleting an account or modifying the account password will invalidate all previously obtained ACCESS_TOKENs.
The validity period of the access_token refers to the time since the last request made by the account user. That is, the account will expire if it has not been used to access the system for 180 days or if the ACCESS_TOKEN has not been used to request data.

2.3. Obtaining ACCESS_TOKEN

Two methods:

Obtain using API_SECRET and specify the username
Obtain using account name and password

2.3.1. Obtain ACCESS_TOKEN for a specific user using API_SECRET and specifying the username

curl example:

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

TEXT

Response 200

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

2.3.2. Log in with a username and password to obtain ACCESS_TOKEN for that user

curl Example:

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}'

TEXT

Response 200

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

Notes:

If the customer enables login with verification code, accessing ACCESS_TOKEN through the above method will prompt "verification code error or expired". It is recommended to obtain ACCESS_TOKEN directly through API_SECRET.
If using the platform account, be sure to add the parameter "is_global=true" in the requested URL.

2.4. Using ACCESS_TOKEN:

Using this ACCESS_TOKEN can be done by specifying the header `sensorsdata-token`, for example, to query event analysis report using ACCESS_TOKEN:

curl Example:

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" }'

TEXT