事件上报接口规范2.0

本文档提供Quick Audience事件上报开放接口,当您采用自主接入的事件上报方式时可使用。

完整的自主接入事件数据上报流程,请参见自主接入上报流程

说明

当前仅提供Java语言的SDK。

安装Java SDK

操作步骤:

  1. 安装阿里云Java核心库,请参见安装Alibaba Cloud SDK for Java

    SDK使用说明,请参见Java示例

  2. 访问Aliyun Java SDK Retailadvqa Public,下载并安装Quick Audience Java SDK。

  3. 下载quicka-openapi-sdk-4.4.0-SNAPSHOT.jar,加入项目目录。

  4. 在项目目录下的pom.xml文件中,添加以下Maven依赖。

<dependency>
        <groupId>com.aliyun.quicka</groupId>
        <artifactId>quicka-openapi-sdk</artifactId>
        <version>4.4.0-SNAPSHOT</version>
        <scope>system</scope>
        <!--以下替换为quicka-openapi-sdk-4.4.0-SNAPSHOT的目录地址-->
        <systemPath>/Users/fin-13921/Documents/project/qa-second/Abc/quicka-openapi-sdk-4.4.0-SNAPSHOT.jar</systemPath>
    </dependency>

    <dependency>
    <groupId>com.aliyun.api.gateway</groupId>
    <artifactId>sdk-core-java</artifactId>
    <version>1.1.6</version>
</dependency>

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <optional>true</optional>
    <version>[4.5.6,5.0.0)</version>
</dependency>

获取接口通用参数

调用开放接口前需要获取几个通用参数:

参数名称

含义

获取方法

endpoint

Quick Audience开放接口的访问地址。

公共云Quick Audience开放接口的访问地址为:

  • 张家口:quicka-public.cn-zhangjiakou.aliyuncs.com

  • 上海:quicka-public.cn-shanghai.aliyuncs.com

  • 深圳:quicka-public.cn-shenzhen.aliyuncs.com

accessId

您的Quick Audience的组织ID。

组织管理员账号登录Quick Audience后,选择管理中心>组织管理>组织系统配置,页面展示的AccessKey ID即为组织ID,您可以单击复制按钮进行复制。

workspaceId

事件归属的工作空间ID。

选填。若不传入,当不同空间有多个相同事件编码的事件时,多个事件均将获得上报的数据。

组织管理员账号登录Quick Audience后,选择管理中心>组织管理>工作空间管理,在列表中查询工作空间对应的ID。

ACCESS_KEY_ID、ACCESS_SECRET

具有Quick Audience访问权限的RAM用户的AccessKey ID、AccessKey Secret。

具有Quick Audience访问权限的RAM用户登录RAM控制台,创建并获取AccessKey ID、AccessKey Secret,请参见创建AccessKey

阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。

强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。

本示例以将AccessKey 和 AccessKeySecret 保存在环境变量为例说明。

SDK demo示例

import com.alibaba.fastjson.JSON;
import com.aliyuncs.AcsRequest;
import com.aliyuncs.AcsResponse;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.retailadvqa_public.client.QAHttpApiClient;
import com.aliyuncs.retailadvqa_public.client.constants.enums.GatewayType;
import com.aliyuncs.retailadvqa_public.client.constants.enums.InvokerType;
import com.aliyuncs.retailadvqa_public.client.model.event.ClientEventMessageModel;
import com.aliyuncs.retailadvqa_public.client.model.event.CustomerIdModel;
import com.aliyuncs.retailadvqa_public.client.param.PopClientBuilderParam;
import com.aliyuncs.retailadvqa_public.model.v20200515.ReceiveEventMessageRequest;
import com.aliyuncs.retailadvqa_public.model.v20200515.ReceiveEventMessageResponse;
import org.junit.Before;
import org.junit.Test;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashMap;


public class EventCenterPopTest {
    /**
     *组织ID
     */
    private final static String accessId = "78e8f4b4***5ae16b59b";

    /**
     * ************ pop网关参数 ****************
     */

    /**
     * quicka-public.[RegionId].aliyuncs.com
     */
    protected final static String ENDPOINT = "quicka-public.cn-shanghai.aliyuncs.com";
    protected final static String REGION_ID = "cn-shanghai";
    protected final static String ENDPOINT_NAME = "retailadvqa-public";
    protected final static String PRODUCT = "retailadvqa-public";
    /**
     *工作空间ID,选填
     */
    String workspaceId = "f35f12d7****ccdf9da93ad3";

    @Before
    public void init() throws ClientException {
      /**
       * 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
       * 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
       * 本示例以将AccessKey 和 AccessKeySecret 保存在环境变量为例说明。
       * 保存环境变量的方法参考如下:
       * Linux和macOS系统配置方法
       * 执行以下命令:
       * export SCA_AK_ENV=<access_key_id>
       * export SCA_SK_ENV=<access_key_secret>
       * <access_key_id>替换为已准备好的AccessKey ID,<access_key_secret>替换为AccessKey Secret。
       */
      	PopClientBuilderParam popClientBuilderParam = PopClientBuilderParam.builder()
                .endpointName(ENDPOINT_NAME)
                .endpoint(ENDPOINT)
                .accessKeyId(System.getenv("SCA_AK_ENV"))
                .accessSecret(System.getenv("SCA_SK_ENV"))
                .regionId(REGION_ID)
                .product(PRODUCT).build();
        QAHttpApiClient.initPopInstance(popClientBuilderParam);
    }


    /**
     * 事件数据上报消息明细
     */
    @Test
    public void receiveMessage() {
        ReceiveEventMessageRequest request = new ReceiveEventMessageRequest();
        // 组织ID
        request.setAccessId(accessId);
        ClientEventMessageModel clientEventMessageModel = new ClientEventMessageModel();
        // 工作空间ID,选填
        clientEventMessageModel.setWorkspaceId(workspaceId);
        // 事件编码
        clientEventMessageModel.setEventCode("testEventCode");
        // 事件属性,包含属性编码和属性值
        clientEventMessageModel.setExtendAttributes(new HashMap<String, String>(){{
            this.put("occur_time_default", "1658112165000");
            this.put("attr_code", "attr_value");
        }});
        // 用户在您自有体系中的用户ID
        clientEventMessageModel.setCustomerId("100001");
        // 是否是交易数据,0 (不是) / 1 (是)
        clientEventMessageModel.setIsOrder(0);
        // 事件发生时间
        clientEventMessageModel.setEventTime(System.currentTimeMillis());
        // Quick Audience空间支持的用户ID,必填
        clientEventMessageModel.setCustomerIdList(new ArrayList<CustomerIdModel>(){{
            this.add(new CustomerIdModel("188****5531", "MOBILE"));
        }});

        request.setEventMessageModelListJson(JSON.toJSONString(Arrays.asList(clientEventMessageModel)));
        
        try {
            ReceiveEventMessageResponse acsResponse = (ReceiveEventMessageResponse) invoke(request);
            if (acsResponse.getSuccess()) {
                System.out.println("success");
                System.out.println(JSON.toJSONString(acsResponse));
            } else {
                System.out.println(JSON.toJSONString(acsResponse));
            }

        } catch (ClientException e) {
            e.printStackTrace();
        }
    }

    private AcsResponse invoke(AcsRequest request) throws ClientException {
        return QAHttpApiClient.invoke(request, GatewayType.POP, InvokerType.OTHER);
    }
    
}

事件数据上报接口

接口描述

用于发送事件数据实时上报消息,自主接入方式。

URL

openapi/event/detail/receive?=accessId

请求方式

post

参数名

数据类型

参数类型

是否必填

说明

1.accessId

string

body

AccessKey ID,您的Quick Audience的组织ID。

2.eventMessageModelListStr

string

详细见下面的事件模型ClientEventMessageModel

状态码

说明

200

接口请求成功

其他

请求失败

返回属性名

类型

说明

1.traceId

string

请求的唯一ID,用于定位链路上的问题。

2.success

boolean

服务器处理是否成功。

3.errorCode

string

错误码。

4.errorDesc

string

错误描述。

示例

请求参数

curl --location --request POST 'https://endpoint/openapi/event/detail/receive?accessId=7*****65ae16b59b' \ --form 'eventMessageModelListJson="[{\"comeFrom\":\"test\",\"customerId\":\"100001\",\"customerIdList\":[{\"customerId\":\"188****5531\",\"idMapping\":\"MOBILE\"}],\"eventCode\":\"testEventCode\",\"eventTime\":1658226007958,\"extendAttributes\":{\"attr_code\":\"attr_value\",\"occur_time_default\":\"1658112165000\"}}]"'

返回值

{

"errorCode": null,

"errorDesc": null,

"success": true,

"traceId": "ff0f996e-6c63-412d-a4cd-acf5d007****"

}

事件模型ClientEventMessageModel

@Data
public class ClientEventMessageModel {

    /**
     * 组织ID,必填
     */
    String organizationId;

    /**
     * 空间ID,选填
     */
    String workspaceId;

    /**
     * 用户在您自有体系中的用户ID,必填
     */
    String customerId;

    /**
     * 事件编码,必填
     */
    String eventCode;

    /**
     * 事件发生时间,必填
     */
    Long eventTime;

    /**
     * 事件属性,是否必填取决于事件定义中对属性的设置
     */
    Map<String, String> extendAttributes = new HashMap<>();

    /**
     * Quick Audience空间支持的用户ID,若之前同一个customerId上报过customerIdList,则选填
     */
    List<CustomerIdModel> customerIdList = new ArrayList<>();

    /**
     * 是否是交易数据,0 (不是) / 1 (是)
     */
    String isOrder;
}

@Data
public class CustomerIdModel {
    String customerId;
    String idMapping;
    public CustomerIdModel() {
    }
    public CustomerIdModel(String customerId, String idMapping) {
        this.customerId = customerId;
        this.idMapping = idMapping;
    }
}

CustomerIdModel:

public class CustomerIdModel {
    @ApiModelProperty(required = true, value = "实际用户ID,如手机号类型的139****0000")
    String customerId;
    @ApiModelProperty(required = true, value = "用户ID类型,如手机号,请参见下面的用户ID类型说明")
    String idMapping;
}

用户ID类型说明:

Quick Audience空间支持的用户ID类型包括本空间的ID类型管理页面中所有已启用状态的ID类型,请在代码中使用ID类型编码作为ID类型的名称。

  • 系统预置ID的ID类型编码,请查阅系统预置ID列表

  • 自定义ID的ID类型编码,请单击ID对应的编辑按钮进行查看。