HUAWEI Analytics Kit provides data export APIs for you to complete the following tasks on your app server:
The following figure shows the data export process.
In this codelab, you can call APIs as instructed to export the data collected by Analytics Kit to your app server.
In this codelab, you will learn how to use APIs of Analytics Kit to export the data it collected from your app.
To use the APIs provided by Analytics Kit, you need to complete the following preparations:
A callback API and a callback certificate are required if you want to export the data collected by Analytics Kit. Therefore, you need to provide a RESTful API for receiving POST requests over HTTPS. This tutorial will guide you through how to create an HTTPS callback API.
Step 1 Create a web project based on Spring Boot. A Demo is available. Download it to a local path and decompress it.
Step 2 Open the decompressed package using IDEA. The project depends on the Spring Boot environment, and therefore the Maven repository configured for the project must contain the components on which org.springframework.boot depends.
Step 3 Modify the application.properties file in the resources folder. In the file, spring.application.name indicates the project name and server.port indicates the startup port.
Step 4 Find the CallbackFunction file in the com.huawei.analystics.callback.api folder. The file defines the callback function that you need to use during the data export. For details about the operation procedure, please refer to 4 Demo Example.
—-End
This tutorial provides two methods for starting the callback API. You can use either of them as needed:
Method 1: For a local project, right-click DemoApplication and choose Run "DemoApplication". Then, you can access the callback API using "IP address of the local host+port number/analytics/callbackinterface."
Method 2: For a server deployment project, expand the Maven project and click install. You can then obtain the Export_Data_Callback_CodeLab-0.0.1-SNAPSHOT.jar package in the target folder.
Use Xshell to log in to the Linux server, and copy the jar package to the server. Then, run Java –jar Export_Data_Callback_CodeLab-0.0.1-SNAPSHOT.jar to start the callback API, and access the callback API through "IP address of the Linux server+port number/analytics/callbackinterface."
Currently, you can access the callback API you developed over HTTP. However, to ensure data transmission security, Analytics Kit needs to access the callback API over HTTPS. Therefore, you need to perform the following steps to install the Nginx proxy server and configure the SSL certificate.
Step 1 Install the Nginx proxy server.
Use Xshell to log in to the Linux server whose IP address has been assigned a public network domain name, for example, habackup.hwcloudtest.cn. Download the Nginx installation package with Wget or use the recommended Nginx1.14 installation package.
Copy the nginx-1.14.0.zip package to a directory on the server and decompress the package.
Unzip nginx-1.14.0.zip –d /opt/Huawei/nginx2
Install GNU Compiler Collection (GCC) for Nginx compilation.
yum install gcc-c++
Install pam-devel.
yum install -y pcre pcre-devel
Install Open SSL.
yum install -y openssl openssl-devel
Run configure in the decompressed Nginx installation package.
./configure
If you need to customize installation directories, add some options when running the configure command. For example, in the following figure, –sbin-path indicates the directory of the Nginx startup command, and –conf-path indicates the directory of the Nginx configuration.
Go to the Nginx installation directory and perform compilation.
make
make install
Go to the configuration directory based on conf-path and open the nginx.conf file, for example, /etc/nginx2/nginx.conf in the demo, and configure the file as shown in the following figure.
In listen, configure the Nginx listening port. In proxy_pass, configure the IP address and port of the callback API created in Creating a Callback API.
Step 2 Install the SSL certificate.
To access the callback API over HTTPS, you need to configure a valid SSL certificate for Nginx. You can apply for an SSL certificate on HUAWEI CLOUD or a website that provides legal SSL certificates. Make sure that you use the public network domain name of the server when applying for a certificate.
An SSL certificate usually consists of two files, for example, server.pem and server.key. After obtaining the SSL certificate, place it in a fixed directory. You can configure the file path and SSL listening configuration in the conf file of Nginx. The following is the example configuration for the conf file in the demo project:
ssl on;
ssl_certificate /opt/huawei/openresty/nginx/conf/ssl/server.pem;
ssl_certificate_key /opt/huawei/openresty/nginx/conf/ssl/server.key;
ssl_session_timeout 5m;
ssl_protocols TLSv1.2;
ssl_ciphers HIGH:!SSLv2:ALL:!DH:!ADH:!EDH:!MD5:!EXPORT:!DES:!RC4;
Step 3 Go to the Nginx startup directory.
./nginx
Access Nginx through its domain name and port number. If the information shown in the following figure is displayed, Nginx has been successfully installed.
—-End
On the server, run curl to call the callback API.
https://habackup.hwcloudtest.cn:31405/analytics/callbackinterface
If any information is returned, the callback API is ready for use. It remains available throughout the demo, a process that takes at least two hours.
Access the created callback API from Google Chrome to obtain the callback certificate.
Step 1 Click the lock icon on the left of Google Chrome's address box, and then click Certificate.
Step 2 On the Details page, click Copy to File and then OK.
Step 3 Click Next.
Select Base-64 encoded X.509 (.CER)(S), click Next, specify the export directory, click Next, and then click Finish.
Open the exported certificate file in a text editor and copy the file content to the callback API configuration page as the value of HTTPS certificate.
—-End
In the previous section, you have completed the preparations for calling server APIs. In this section, you will try to call these APIs by building a demo. We have provided you with a Demo. Download it and test the APIs.
Step 1 Download the demo package to the local host and decompress it.
Open the decompressed package using IDEA.
Find the ExportDemoApi file in com.huawei.macaw.client. The file contains the API test demo.
Step 2 Configure the header field for calling APIs of Analytics Kit.
Add the following parameters to the header field:
To obtain x-product-id, sign in AppGallery Connect, and go to HUAWEI Analytics > Management > Analysis setting to obtain the value of Product ID.
To obtain x-app-id, sign in AppGallery Connect, and go to Project Setting > App information to obtain the value of App ID.
To obtain Authorization, call the following API:
https://oauth-login.cloud.huawei.com/oauth2/v2/token
You need to provide the following parameters:
In the ExportDemoApi class of the demo, the getToken method is used to obtain Authorization, and the buildHeader method is used to obtain the header.
Configure the highlighted parameters with the obtained information.
Step 3 Export the data reported by the app at the following URL:
https://datacollector-drcn.dt.hicloud.com/analytics/export/raw_data_requests/v2
The procedure is as follows:
1.Add your own service logic to the callback API. The API is used to obtain the data export result.
Wherein, ExportDataCallbackReq contains the following information:
request_id: Request ID
In the demo project, the service logic is to print the file download path carried in file_path of ExportDataCallbackReq. You can change the service logic as needed.
After adding your own service logic, you need to repeat the deployment procedure in "Preparing for the Integration" to verify the callback API.
You need to replace the URL of the data export API based on the site where you are located.
Site | URL |
China | https://datacollector-drcn.dt.hicloud.com/analytics/export/raw_data_requests/v2 |
Singapore | https://datacollector-dra.dt.hicloud.com/analytics/export/raw_data_requests/v2 |
Europe | https://datacollector-dre.dt.hicloud.com/analytics/export/raw_data_requests/v2 |
Russia | https://datacollector-drru.dt.hicloud.com/analytics/export/raw_data_requests/v2 |
2.Configure the callback API and callback certificate.
Sign in AppGallery Connect and go to HUAWEI Analytics > Management > Analysis setting to configure the callback address and the callback certificate. Specifically, enter the HTTPS callback API for receiving POST requests in Export result callback URL and paste the content in the cer.cer file to HTTPS certificate.
Test whether the callback API is functioning properly.
If the callback test is successful, click Submit.
3.Call the data export API as instructed by the demo.
As shown in the preceding figure, you can use createRawDataExportTask to call the data export API. Some parameters are required for creating a data export task. For example, startDate, endDate, and fileFormat in the following figure are mandatory. You can modify their settings as needed.
In the demo project, the data generated from 2020-08-10 to 2020-08-11 is exported as a CSV file.
You can also add the parameters in the following table as filtering conditions.
Name | Description |
app_ver | App version. |
device_maker | Device brand. |
device_name | Device model. |
region_cd | Location code. |
os_language | System language. |
os_ver | OS version. |
For example, if you only want to export the data of version 1.0 and version 2.0, you can add the following code.
Filter filter = new Filter()
filter.setName("app_ver")
filter.setValues(Arrays.asList("1.0", "2.0")
req.setFilters(Arrays.asList(filter));
Once you run the project, calling of the callback API is automatically completed.
4.Check the task status in AppGallery Connect.
You can view the created data export task on the Export data page. If Creation mode is API call, data is exported using the data export API; if Creation mode is Manual, data is exported manually. After the data export API is called, the task status is Exporting.
5.Check the callback result.
The export task takes about 2 hours to complete. After the task is complete, you can click the displayed link to download the exported file.
You can also view your service logic in the callback API. In the demo project, the service logic is to print the file download path. Therefore, the following information is recorded in the service execution log:
The export status returned by the callback API can be one of the following:
file_path is present only when the export status is EXPORTED.
So far, the process of calling the data export API of Analytics Kit is complete.
—-End
If the data export is successful but the callback API is not executed, an error may have occurred in the communication with the Analytics Kit server. Rectify the network error and try again.
You can learn the cause of a data export failure through the export status callback API. The probable causes are as follows:
Well done. You have successfully completed the codelab for exporting data from the Analytics Kit and learned how to use the APIs of the Analytics Kit to export data reported by app clients.
For more information, please click the following links:
Related documents
Sample code on GitHub:
https://github.com/HMS-Core/hms-analytics-demo-data-export/blob/master/README.md
Or, you can click the link below to download the source code.