分析服务（Data Export）

简介

分析服务给开发者提供了数据导出API接口，可以让开发者在服务端完成以下工作：

创建Analytics Kit采集数据的导出任务。
查询Analytics Kit采集数据导出任务的执行状态。

数据导出的简介图如下：

您将建立什么

参照本文档的开发流程，通过文档指定的方式调用API接口，即可在您的服务端完成Analytics Kit采集数据的导出。

您将会学到什么

如何使用分析服务的API接口导出Analytics Kit的采集数据。

硬件要求

开发计算机（台式机或笔记本电脑）
具有网络域名的服务器（操作系统Linux x86）

软件要求

本文档适用于HUAWEI Analytics-Kit 5.0.3+
Java JDK (Level 1.7，建议使用1.8)
Maven 3.5+
IDEA 2019+
Nginx 1.14+
Xshell

使用分析服务提供的API接口，需要完成以下准备工作：

注册成为开发者。
在AGC上创建应用。
创建一个用于接收post请求的https回调接口。
创建一个用于测试API的Web工程。

Analytics Kit采集数据的导出需要开发者提供回调接口和回调证书，所以需要开发者提供一个能够接收post请求的restful接口（接口需要用https访问）。本文档提供一种方法，参照以下步骤即可完成接口创建。

创建回调接口

步骤1 开发者需要创建一个基于SpringBoot的Web项目，这里我们提供了Demo，下载解压到本地即可。

步骤2 用IDEA打开解压的文件夹，项目依赖于SpringBoot开发包，需要项目配置的maven仓库中包含org.springframework.boot依赖组件。

步骤3 修改"resources"文件夹中的"application.properties"文件，spring.application.name为项目名称，server.port为启动端口，可以在Demo中的这个文件中进行配置。

步骤4 在"com.huawei.analystics.callback.api"文件夹下找到"CallbackFunction"文件，这是回调函数，如下图所示，开发者在进行数据导出时需要使用此回调函数，具体操作流程请参见4 Demo示例。

—-结束

启动回调接口服务

本文档提供两种方式启动回调接口服务，您可以任选一种方式进行。
方法一：本地启动项目，找到DemoApplication右击启动即可，那么可以通过本地机器IP+端口+/analytics/callbackinterface访问回调接口。

方法二：服务器部署项目，打开IDEA右侧Maven按钮，点击install后可以在target文件夹下获取一个jar包"Export_Data_Callback_CodeLab-0.0.1-SNAPSHOT.jar"

利用Xshell登录上准备好的Linux服务器，将jar包拷贝到准备好的服务器上，用Java –jar Export_Data_Callback_CodeLab-0.0.1-SNAPSHOT.jar命令启动服务，然后通过服务器IP+端口+/analytics/callbackinterface访问回调接口。

设置Https访问

目前，开发者可以通过http的方式访问自己开发的回调接口，但是为了传输数据的安全，分析服务后台需要通过https的方式去访问回调接口。所以需要通过下面步骤安装nginx代理服务器和配置SSL证书。

步骤1 安装nginx代理服务器。

利用Xshell登录上准备好的Linux服务器，服务器对应的IP具有公网域名例如habackup.hwcloudtest.cn，下载nginx安装包，可以wget直接下载或者使用推荐的nginx1.14安装包。
将压缩包nginx-1.14.0.zip拷贝到机器上某个目录下进行解压。


Unzip nginx-1.14.0.zip –d /opt/Huawei/nginx2

安装GCC（GNU Compiler Collection），用于编译nginx


yum install gcc-c++

安装pcre-devel


yum install -y pcre pcre-devel

安装Open SSL


yum install -y openssl openssl-devel

进行解压的nginx安装包中，运行configure


./configure

如果需要自定义安装一些路径，需要configure命令下携带一些参数，例如下图中，–sbin-path表示nginx启动命令的路径，–conf-path表示nginx配置文件夹的路径等。

进入nginx安装目录下进行编译操作


make 
make install

最后，按照配置的conf-path路径找到配置文件夹，然后打开nginx.conf文件，例如Demo中找到/etc/nginx2/nginx.conf，根据下图进行配置。
listen端口为nginx监听端口，proxy_pass中代理的http路径为创建回调接口步骤中创建的回调接口的IP端口。

步骤2 安装SSL证书

为了实现https访问，还需要为nginx配置SSL证书，这个证书须为合法证书，开发者可以在华为云或者其他SSL证书提供网站上申请证书，证书申请时注意用服务器公网域名。
开发者获取到SSL证书后一般有两个文件例如"server.pem,server.key", 将其放置在固定目录下，然后可以在"conf"文件中加入文件路径和ssl监听的一些配置，例如Demo中的"conf"文件中配置如下内容。


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;

步骤3 进入nginx配置的启动目录


./nginx

然后利用域名和端口访问nginx，出现下图即表示nginx安装成功了。

—-结束

测试Https的回调接口

在服务器上，执行curl命令调用接口。


https://habackup.hwcloudtest.cn:31405/analytics/callbackinterface

如果有返回内容，就表示接口已经准备完毕，服务需要保持在线状态直至整个demo执行结束，最少需要2个小时。

获取回调证书

下面通过浏览器访问您所创建的回调接口获取证书。请参考下方步骤：

步骤1 点击chrome浏览器左侧小锁图标，然后点击"证书"。

步骤2 点击"详细信息"，然后点击"复制到文件"。

步骤3 点击"下一步"。

选择"Base64 编码 X.509(.CER)(S)"，选择导出位置，点击"下一步"然后点击"完成"。

将导出的证书用文本编辑器打开后复制即可。

—-结束

在上一小节中，您已经成功准备好服务端API接口调用的准备工作，本小节您将尝试通过编写一个Demo完成这些API的调用，我们给您准备一个样例Demo，只需要下载跟着完成调试工作即可。

步骤1 首先将Demo文件夹下载到本地进行解压。

用IDEA以打开web项目的方式打开文件夹。

在com.huawei.macaw.client找到"ExportDemoApi"文件，文件中包含了API的测试demo。

步骤2 准备API调用的header部分。

分析服务的API调用都需要提供下面参数作为header部分：

x-product-id: 用户在AppGallery Connect上的ProductID
x-app-id: 用户在AppGallery Connect上的AppID
Authorization: 基于oauth2的Access Token

x-product-id需要开发者在AppGallery Connect官网上选择需要查看数据的项目，点击分析设置标签tab，然后产品ID即对应此参数。

x-app-id 需要开发者在AppGallery Connect官网上选择需要查看数据的应用，点击项目设置，其中APP ID即为此参数。

Authorization需要调用下方接口获取，开发者需要提供以下参数。


https://oauth-login.cloud.huawei.com/oauth2/v2/token

client_id 选择APP ID
grant_type固定填写client_credentials
client_secret即为项目设置中应用的APP SECRET

在Demo的类ExportDemoApi文件中，getToken函数用来获取Authorization，buildHeader函数获取调用的header。

开发者需要将准备好的参数进行替换。

步骤3 开发者可以通过下方接口导出用户侧上报的数据，步骤如下。


https://datacollector-drcn.dt.hicloud.com/analytics/export/raw_data_requests/v2

1、开发者在准备的回调接口中补充自己的业务逻辑，回调接口是用来获取导出任务的结果。

其中ExportDataCallbackReq包含以下内容：

request_id：请求ID

app_id：当前应用ID

status：导出状态

file_path：导出文件的下载路径（6小时有效）

status_time：接收回调时间

例如：Demo中我们直接打印回调参数中导出文件的下载路径。

开发完后需要重新根据准备工作步骤中打包部署的过程重新执行一遍，保证回调接口的有效性。

您需要根据您所在的站点，来替换对应的数据导出的接口URL。

站点	接口URL
中国	https://datacollector-drcn.dt.hicloud.com/analytics/export/raw_data_requests/v2
新加坡	https://datacollector-dra.dt.hicloud.com/analytics/export/raw_data_requests/v2
欧洲	https://datacollector-dre.dt.hicloud.com/analytics/export/raw_data_requests/v2
俄罗斯	https://datacollector-drru.dt.hicloud.com/analytics/export/raw_data_requests/v2

2、配置回调接口和回调证书。

当开发者您选择自己的项目后，进行分析设置，需要填写回调地址（即准备好https的post接口），https证书即准备工作中复制的cer.cer文件内容，全部粘贴到输入框中。

先测试回调接口的有效性。

显示测试回调成功后，即可提交完成。

3、根据Demo调用数据导出接口。

如上图所示，使用createRawDataExportTask函数的调用即可。任务创建需要一些固定的参数。例如下图中的时段和文件类型参数是必须上传的，您可以根据自己需要进行修改。

例如Demo文件中选择2020-8-10到8-11的数据进行导出，导出格式为csv。

当然如果开发者需要加一些筛选条件，我们可以添加以下条件作为过滤参数，例如下表：

属性名称	属性描述
app_ver	应用版本号。
device_maker	设备品牌。
device_name	设备型号。
region_cd	位置编码。
os_language	操作系统语言。
os_ver	操作系统版本。

例如，我们只想导出版本1.0和2.0的数据，只需要参照下方代码，然后添加到Demo函数图中位置即可。


Filter filter = new Filter() 
filter.setName("app_ver"); 
filter.setValues(Arrays.asList("1.0","2.0"); 
req.setFilters(Arrays.asList(filter));

如下图直接启动项目后即可完成调用过程。

4、AppGallery Connect查看任务创建状态

在数据导出标签页面下可以看到当前创建的导出任务，创建方式为接口调用即通过API获取，手动表示在界面中选择条件后进行导出。导出接口调用后会显示导出中。

5、查看回调结果。

导出任务执行结束大概需要2个小时，界面上会显示任务状态，显示已完成点击可以下载文件。

同样可以在回调接口处查看开发者自己的执行逻辑，例如Demo中是打印文件下载路径，在服务执行日志中有如下显示：

回调接口的返回的状态有下面几种：

EXPORTED：成功导出。

NO_DATA：没有符合条件的数据。

EXPORT_FAILED：导出失败，建议重试。

TOO_MANY_RECORDS：一次导出数据量太多，建议缩小数据导出范围后重新发起请求。

当然只有导出状态为EXPORTED才有file_path。

到这里，Analytics Kit采集数据导出任务API调用过程就全部完成了。

—-结束

1. 导出数据显示成功，回调接口并未执行逻辑的原因？

如果导出数据已经显示成功，回调接口没执行说明回调接口的服务器存在无法通信的情况。

2. 导出数据失败的原因？

导出事件数据有可能失败的原因会在导出状态回调接口中显示，原因详情如下：

NO_DATA：没有符合条件的数据。
EXPORT_FAILED：导出失败，建议重试。
TOO_MANY_RECORDS：一次导出数据量太多，建议缩小数据导出范围后重新发起请求。

干得好，你已经成功完成完成了Analytics Kit数据导出的codelab并学到了：如何使用Analytics Kit的API接口导出用户端上报的数据。

您可以阅读下面链接，了解更多相关的信息。
相关文档

GitHub上的示例代码：
https://github.com/HMS-Core/hms-analytics-demo-data-export/blob/master/README.md

您可以点击下方按钮下载源码：

源码下载

已复制代码