嵌入分析-阿里云帮助中心

本文为您介绍三方嵌入的API接口。

生成报表嵌入Ticket

接口路径：/openapi/v2/embed/ticket/create（POST）
接口描述：用于生成ticket方案三方嵌入时的票据ticket信息。
起始版本：独立部署4.2.1

接口参数：content-type:application/x-www-form-urlencoded;charset=UTF-8，参数以表单提交

参数	类型	描述	是否必选
worksId	String	开通嵌入的报表ID，目前支持仪表板、电子表格、数据大屏、自助取数、即席分析和数据填报。	是
cmptId	String	组件ID，为以上报表中某个组件的ID。	否
ticketNum	Integer	ticket的票据数量。默认值为1。建议值为1。	否
userId	String	Quick BI的用户ID。说明 userId和accountName只填一个即可，不填时默认绑定报表的Owner。	否
accountName	String	用户的账号名称。说明 userId和accountName只填一个即可，不填时默认绑定报表的Owner。	否
accountType	Integer	用户的账号类型。 1：阿里云主账号 3：Quick BI 自建账号。 4：钉钉 5：RAM账号 6：三方账号（SAML、OAuth等协议对接的账号） 9：企业微信 10：飞书说明 accountName不为空，则accountType不能为空。	否
expireTime	Integer	过期时间。单位：分钟最大值：240。即，4小时说明独立部署4.2.2及后续版本中，没有最大值限制。默认值：240	否
watermarkParam	String	报表的水印参数。不得超过50个字符。 SDK调用若带中文字符，必须URLEncoder后传参。如果包含空格，需要在URLEncoder之前转为%20	否
globalParam	String	报表过滤条件的全局参数。 JSON格式的字符串。 SDK调用若带中文字符，必须URLEncoder后传参。如果包含空格，需要在URLEncoder之前转为%20	否

传参样例：

说明

SDK调用时，如果水印参数或全局参数中带上了中文符号，必须进行URLEncoder.encode(GLOBAL_PARAM, "UTF-8")后进行传参，encode前的参数形式如下： watermarkParam = "Ticket三方嵌入"; globalParam="[{"paramKey":"price","joinType":"and","conditionList":[{"operate":">","value":"0"}]}]";

如果包含空格，需要在URLEncoder之前转为%20，例如：

watermarkParam = "Ticket%20三方嵌入";

globalParam="[{"paramKey":"price","joinType":"and","conditionList":[{"operate":">","value":"%20"}]}]"

{
    "worksId": "ccd3428c-dd23-****-a608-26bae29dffee",
    "cmptId": "07f65a0d-d786-****-b180-357767383538",
          "ticketNum": 1,
                 "userId": "1365****23238860",
    "userId": "07f65a0d-d786-****-b180-357767383538",
          "accountName": null,
          "accountType": null,
          "expireTime": 240,
          "watermarkParam": "Ticket%E4%B8%89%E6%96%B9%E5%B5%8C%E5%85%A5",
          "globalParam": "%5B%7B%22paramKey%22%3A%22price%22%2C%22joinType%22%3A%22and%22%2C%22conditionList%22%3A%5B%7B%22operate%22%3A%22%3E%22%2C%22value%22%3A%220%22%7D%5D%7D%5D%0A"
}

返回参数说明（SDK调用时，仅返回data部分）：

参数	类型	描述
traceId	string	请求ID。
code	string	抛错码。取值范围： 0：调用成功 AE或OE开头的异常码：调用失败
message	string	抛错信息。取值范围： success：调用成功其他信息：调用失败时的提示
success	boolean	是否请求成功。取值范围： true：请求成功 false：请求失败
data	string	返回生成的嵌入ticket值。

返回参数：

{
    "traceId":"d3f913a6-84ec-****-b30f-fd7540f3bdeb",   // 请求日志traceId
    "code":"0",
    "message":"success",
    "data": "ccd3428c-dd23-****-a608-26bae29dffee",     // 生成的票据
    "success":true                                      // 请求是否成功
}

JAVA SDK 示例：

public static void generateEmbedTicket() throws SDKException {
    HttpRequest request = HttpRequest.build()
        .setUri("/openapi/v2/embed/ticket/create")
        .setMethod(HttpMethod.POST)
        .setHttpContentType(FormatType.FORM);
    request.addParameter("worksId","xxx");
    // 非必填参数
    // request.addParameter("cmptId","xxx");
    // request.addParameter("ticketNum","xxx");
    // request.addParameter("userId","xxx");
    // request.addParameter("accountName","xxx");
    // request.addParameter("accountType","xxx");
    // request.addParameter("expireTime","xxx");
    // request.addParameter("watermarkParam", URLEncoder.encode("你好中国","utf-8"));
    // String globalParam = "[{"paramKey":"menu_name","joinType":"and","conditionList":[{"operate":"=","value":"C_中文"}]}]";
    // globalParam = URLEncoder.encode(globalParam,"utf-8"));
    // request.addParameter("globalParam", JSONObject.parseArray(globalParam));
    String result = openApiClient.syncExecute(request);
    System.out.println(result);
}

查询嵌入报表Ticket详情

接口路径：/openapi/v2/embed/ticket/info（GET）
接口描述：根据Ticket查询当前票据的相关信息。
起始版本：独立部署4.2.1
接口参数：
参数
类型
描述
是否必选
ticket
String
三方嵌入的票据值，即URL中的accessTicket值。
是

传参样例：

{
    "ticket": "a27a9aec-e069-****-bd40-1a21ea41d7c5",
}

返回参数说明（SDK调用时，仅返回data部分）：

参数	类型	描述
traceId	string	请求ID。
code	string	抛错码。取值范围： 0：调用成功 AE或OE开头的异常码：调用失败
message	string	抛错信息。取值范围： success：调用成功其他信息：调用失败时的提示
success	boolean	是否请求成功。取值范围： true：请求成功 false：请求失败
data	boolean	ticket的详细信息。
accessTicket	string	票据。
organizationId	string	组织ID。
userId	string	用户ID。
usedTicketNum	integer	已消费的票据数。
maxTicketNum	integer	最大支持的票据数。
registerTime	string	ticket的注册时间。
invalidTime	string	ticket的失效时间。
worksId	string	报表ID。
cmptId	string	报表组件ID。
globalParam	string	全局参数。 globalParam为JSON形式的字符串，获取到时需要进行html实体解码
watermarkParam	string	水印参数。

返回参数：

{
    "traceId":"d3f913a6-84ec-****-b30f-fd7540f3bdeb",   // 请求日志traceId
    "code":"0",
    "message":"success",
    "data": {
      "accessTicket" : "a27a9aec-e069-****-bd40-1a21ea41d7c5",
            "organizationId" : "2fe4fbd8-588f-****-b3e1-e92c7af083ea",
            "userId" : "974e50e160c44275****25e029033f46",
            "usedTicketNum" : 47,
            "maxTicketNum" : 9999,
            "registerTime" : "2022-01-09 22:23:49",
            "invalidTime" : "2022-01-30 03:03:49",
            "worksId" : "ccd3428c-dd23-****-a608-26bae29dffee",
            "componentId" : null,
            "globalParam" : "[{&quot;paramKey&quot;:&quot;price&quot;,&quot;joinType&quot;:&quot;and&quot;,&quot;conditionList&quot;:[{&quot;operate&quot;:&quot;&gt;&quot;,&quot;value&quot;:&quot;0&quot;}]},{&quot;paramKey&quot;:&quot;product_type&quot;,&quot;joinType&quot;:&quot;and&quot;,&quot;conditionList&quot;:[{&quot;operate&quot;:&quot;in&quot;,&quot;value&quot;:[&quot;办公用品&quot;,&quot;家具产品&quot;]}]}]\n",
            "watermarkParam" : "Ticket三方嵌入XXXXXX"
    
    },    
    "success":true                                      // 请求是否成功
}

// 其中globalParam由于为JSON形式的字符串，获取到时需要进行html实体解码

JAVA SDK 示例：

public static void queryEmbedTicketInfo() throws SDKException {
    HttpRequest request = HttpRequest.build()
        .setUri("/openapi/v2/embed/ticket/info")
        .setMethod(HttpMethod.GET);
    request.addParameter("ticket","xxx");
    String result = openApiClient.syncExecute(request);
    System.out.println(result);
}

删除嵌入Ticket

接口路径：/openapi/v2/embed/ticket/delete（DELETE）
接口描述：根据Ticket删除票据的相关信息。
起始版本：独立部署4.2.1
接口参数：
参数
类型
描述
是否必选
ticket
String
三方嵌入的票据值，即URL中的accessTicket值。
是

传参样例：

{
    "ticket": "a27a9aec-e069-****-bd40-1a21ea41d7c5",
}

返回参数说明（SDK调用时，仅返回data部分）：

参数	类型	描述
traceId	string	请求ID。
code	string	抛错码。取值范围： 0：调用成功 AE或OE开头的异常码：调用失败
message	string	抛错信息。取值范围： success：调用成功其他信息：调用失败时的提示
success	boolean	是否请求成功。取值范围： true：请求成功 false：请求失败
data	boolean	是否执行成功。取值范围： true：执行成功 false：执行失败

返回参数：

{
    "traceId":"d3f913a6-84ec-****-b30f-fd7540f3bdeb",   // 请求日志traceId
    "code":"0",
    "message":"success",
    "data": true,    
    "success":true                                      // 请求是否成功
}

// 其中globalParam由于为JSON形式的字符串，获取到时需要进行html实体解码

JAVA SDK 示例：

public static void deleteEmbedTicket() throws SDKException {
    HttpRequest request = HttpRequest.build()
        .setUri("/openapi/v2/embed/ticket/delete")
        .setMethod(HttpMethod.DELETE)
        .setHttpContentType(FormatType.FORM);
    request.addParameter("ticket","xxx");
    String result = openApiClient.syncExecute(request);
    System.out.println(result);
}

更新嵌入Ticket的票据数量

接口路径：/openapi/v2/embed/ticket/updateTicketNum（POST）
接口描述：更新嵌入报表的Ticket票据数量，仅在当前票据还有剩余票据时才允许更新；当无票据剩余张数时，直接新建即可。
起始版本：独立部署4.2.1
接口参数：content-type:application/x-www-form-urlencoded;charset=UTF-8，参数以表单提交
参数
类型
描述
是否必选
ticket
String
三方嵌入的票据值，即URL中的accessTicket值。
是
ticketNum
Integer
更新的票据值必须在1~99999之间。
是

传参样例：

{
    "ticket": "a27a9aec-e069-****-bd40-1a21ea41d7c5",
    "ticketNum" : 10
}

返回参数说明（SDK调用时，仅返回data部分）：

参数	类型	描述
traceId	string	请求ID。
code	string	抛错码。取值范围： 0：调用成功 AE或OE开头的异常码：调用失败
message	string	抛错信息。取值范围： success：调用成功其他信息：调用失败时的提示
success	boolean	是否请求成功。取值范围： true：请求成功 false：请求失败
data	boolean	是否执行成功。取值范围： true：执行成功 false：执行失败

返回参数：

{
    "traceId":"d3f913a6-84ec-****-b30f-fd7540f3bdeb",   // 请求日志traceId
    "code":"0",
    "message":"success",
    "data": true,    
    "success":true                                      // 请求是否成功
}

JAVA SDK 示例：

public static void updateEmbedTicketNum() throws SDKException {
    HttpRequest request = HttpRequest.build()
        .setUri("/openapi/v2/embed/ticket/updateTicketNum")
        .setMethod(HttpMethod.POST)
        .setHttpContentType(FormatType.FORM);
    request.addParameter("ticket","xxx");
    request.addParameter("ticketNum","xxx");
    String result = openApiClient.syncExecute(request);
    System.out.println(result);
}

更新嵌入Ticket的失效时间

接口路径：/openapi/v2/embed/ticket/delayExpireTime（POST）
接口描述：更新嵌入报表的Ticket的失效时间。前提为当前票据ticket还在有效期内；当前还必须有剩余票据数，否则延期无意义。
起始版本：独立部署4.2.1

接口参数：content-type:application/x-www-form-urlencoded;charset=UTF-8，参数以表单提交

参数	类型	描述	是否必选
ticket	String	三方嵌入的票据值，即URL中的accessTicket值。	是
expireTime	Integer	延期时间在0~240分钟之间。说明独立部署4.2.2及后续版本中，没有这个区间限制。	是

传参样例：

{
    "ticket": "a27a9aec-e069-****-bd40-1a21ea41d7c5",
    "ticketNum" : 180
}

返回参数说明（SDK调用时，仅返回data部分）：

参数	类型	描述
traceId	string	请求ID。
code	string	抛错码。取值范围： 0：调用成功 AE或OE开头的异常码：调用失败
message	string	抛错信息。取值范围： success：调用成功其他信息：调用失败时的提示
success	boolean	是否请求成功。取值范围： true：请求成功 false：请求失败
data	boolean	是否执行成功。取值范围： true：执行成功 false：执行失败

返回参数：

{
    "traceId":"d3f913a6-84ec-****-b30f-fd7540f3bdeb",   // 请求日志traceId
    "code":"0",
    "message":"success",
    "data": true,    
    "success":true                                      // 请求是否成功
}

JAVA SDK 示例：

public static void delayEmbedTicketExpireTime() throws SDKException {
    HttpRequest request = HttpRequest.build()
        .setUri("/openapi/v2/embed/ticket/delayExpireTime")
        .setMethod(HttpMethod.POST)
        .setHttpContentType(FormatType.FORM);
    request.addParameter("ticket","xxx");
    request.addParameter("expireTime","xxx");
    String result = openApiClient.syncExecute(request);
    System.out.println(result);
}

生成智能小Q 嵌入Ticket

接口路径：/openapi/v2/embed/ticket/create4Copilot（POST）
接口描述：用于生成智能小Q嵌入Ticket
起始版本：公共云 5.1.1 独立部署版本5.2.2

接口参数：(content-type:application/x-www-form-urlencoded;charset=UTF-8，参数以表单提交)

参数名称	类型	参数描述	是否必需
copilotId	String	开通嵌入的智能小Q 模块 ID	是
ticketNum	Integer	ticket的票据数量。默认值为1。建议值为1。最大值为99999。每次使用票据访问后，Ticket的票据数量减1。	否
userId	String	Quick BI的UserId。您可以调用【3.1.7 根据三方账号获取用户具体信息】或者其他接口获取。注意：userId和accountName只填一个即可，不填时默认绑定报表的owner，访问报表时将以该用户身份访问。	否
accountName	String	用户的账号名称。注意：userId和accountName只填一个即可，不填时默认绑定报表的owner，访问报表时将以该用户身份访问。	否
accountType	Integer	用户的账号类型。 1：阿里云主账号 3：Quick BI 自建账号 4：钉钉 5：阿里云RAM账号 6：三方账号（SAML、OAuth等协议对接的账号） 9：企业微信 10：飞书注意：accountName不为空，则accountType不能为空。	否
expireTime	Integer	过期时间。单位分钟，最大240（4小时）。默认240。 since4.2.2 开始取消最大值约束。	否

传参样例：

{
    "copilotId": "ccd3428c-dd23-****-a608-26bae29dffee",
  	"ticketNum": 1,
    "userId": "07f65a0d-d786-****-b180-357767383538",
  	"accountName": null,
  	"accountType": null,
  	"expireTime": 240
}

返回参数说明（SDK调用时，仅返回data部分）：

参数	类型	描述
traceId	string	请求ID。
code	string	抛错码。取值范围： 0：调用成功 AE或OE开头的异常码：调用失败
message	string	抛错信息。取值范围： success：调用成功其他信息：调用失败时的提示
success	boolean	是否请求成功。取值范围： true：请求成功 false：请求失败
data	string	Ticket票据。

返回参数：

{
    "traceId":"d3f913a6-84ec-****-b30f-fd7540f3bdeb",
    "code":"0",
    "message":"success",
    "data": "ccd3428c-dd23-****-a608-26bae29dffee",
    "success":true
}

JAVA SDK 示例：

  public static void testCreateTicket4Copilot() throws SDKException, UnsupportedEncodingException {
      HttpRequest request = HttpRequest.build()
              .setUri("/openapi/v2/embed/ticket/create4Copilot")
              .setMethod(HttpMethod.POST)
              .setHttpContentType(FormatType.FORM);
      request.addParameter("copilotId", "bb3676ad-b846-488d-8a97-67becf047ef0");
      request.addParameter("ticketNum", 10000);
      request.addParameter("expireTime", 24000);
      String result = CLIENT.syncExecute(request);
      System.out.println(result);
  }

修改智能问数嵌入配置

接口路径：/openapi/v2/copilot/modifyCopilotEmbedConfig（POST）
接口描述：修改智能问数嵌入配置。
起始版本：独立部署5.2

接口参数：（content-type:application/JSON;charset=UTF-8，参数以JSON对象格式附录在http body中）

参数名称	类型	参数描述	是否必需
copilotId	String	需要修改的嵌入配置ID	是
dataRange	object	数据范围对象	否
allTheme	Boolean	是否全部分析主题注意传了该参数，表示生效全部分析主题，包括后续新增也会生效，该参数与allCube只能传一个。	否
allCube	Boolean	是否全部问数资源注意传了该参数，表示生效全部问数资源，包括后续新增也会生效，该参数与allTheme只能传一个。	否
themes	List<String>	分析主题ID列表注意分析主题与问数资源只能2选1，如果allTheme有值，以allTheme为准	否
llmCubes	List<String>	问数资源ID列表注意分析主题与问数资源只能2选1，如果allCube有值，以allCube为准	否
moduleName	String	模块名称	否
agentName	String	机器人昵称	否

传参样例：

{
    "copilotId": "121223****3453423423423523534634637c5",
    "dataRange" : {
                    "themes":
                       [
                           "22222",
                           "23234345"
                        ]
                  },
    "moduleName": "wkbTest",
    "agentName" : "test",
}

返回参数说明（SDK调用时，仅返回data部分）：

参数	类型	描述
traceId	string	请求ID。
code	string	抛错码。取值范围： 0：调用成功 AE或OE开头的异常码：调用失败
message	string	抛错信息。取值范围： success：调用成功其他信息：调用失败时的提示
success	boolean	是否请求成功。取值范围： true：请求成功 false：请求失败
data	boolean	成功则返回true

返回参数：

{
    "traceId":"d3f913a6-84ec-****-b30f-fd7540f3bdeb",
    "code":"0",
    "message":"success",
    "data": "1212235****453423423423523534634637c5",    
    "success":true
}

JAVA SDK 示例：

    @Test
    public void modifyCopilotEmbedConfig() throws SDKException {
        HttpRequest request = HttpRequest.build()
                .setUri("/openapi/v2/copilot/modifyCopilotEmbedConfig")
                .setMethod(HttpMethod.POST).setHttpContentType(FormatType.JSON);
        request.addParameter("copilotId", "3dd5axxxxxxx0b78aef7ed27");
        Map<String,Object> objectMap =new HashMap<>();
        objectMap.put("themes",Lists.newArrayList("22222","23234345"));
        request.addParameter("dataRange",objectMap);
        request.addParameter("moduleName", "阿松大");
        request.addParameter("agentName", "test");
        String result = getOpenApiClient("eee").syncExecute(request);
        System.out.println(result);
    }

获取开通小Q嵌入的配置列表

接口路径：/openapi/v2/copilot/queryCopilotEmbedConfig（GET）
接口描述：获取开通小Q嵌入的配置列表。
起始版本：独立部署5.2
接口参数：
参数名称
类型
参数描述
是否必需
keyword
String
嵌入配置模块名称，模糊搜索。
否

返回参数说明（SDK调用时，仅返回data部分）：

参数	类型	描述
traceId	string	请求ID。
code	string	抛错码。取值范围： 0：调用成功 AE或OE开头的异常码：调用失败
message	string	抛错信息。取值范围： success：调用成功其他信息：调用失败时的提示
success	boolean	是否请求成功。取值范围： true：请求成功 false：请求失败
data	object[]	嵌入配置数组
copilotId	string	嵌入ID
showName	string	嵌入模块名称
dataRange	object	数据范围对象
allTheme	Boolean	是否全选分析主题
allCube	Boolean	是否全选问数资源
themes	List<String>	分析主题的ID集合
llmCubes	List<String>	数据集ID集合
createUser	string	创建人
createUserName	string	创建人的昵称
modifyUser	string	修改人
moduleName	string	模块名称
agentName	string	机器人昵称

返回参数：

{
    "traceId":"d3f913a6-84ec-****-b30f-fd7540f3bdeb",
    "code":"0",
    "message":"success",
    "data": "121223****3453423423423523534634637c5",    
    "success":true
}

JAVA SDK 示例：

   @Test
    public void queryCopilotEmbedConfig() throws SDKException {
        HttpRequest request = HttpRequest.build()
                .setUri("/openapi/v2/copilot/queryCopilotEmbedConfig")
                .setMethod(HttpMethod.GET).setHttpContentType(FormatType.FORM);
        request.addParameter("keyword", "");
        String result = getOpenApiClient("eee").syncExecute(request);
        System.out.println(result);
    }

获取数据范围目录列表

接口路径：/openapi/v2/copilot/queryDataRange（GET）
接口描述：获取数据范围目录列表。
起始版本：独立部署5.2
接口参数：
参数名称
类型
参数描述
是否必需
type
String
数据范围类型：
llmCube：问数资源。
llmCubeTheme：分析主题。
是
keyword
String
名称，模糊搜索。
否

返回参数说明（SDK调用时，仅返回data部分）：

参数	类型	描述
traceId	string	请求ID。
code	string	抛错码。取值范围： 0：调用成功 AE或OE开头的异常码：调用失败
message	string	抛错信息。取值范围： success：调用成功其他信息：调用失败时的提示
success	boolean	是否请求成功。取值范围： true：请求成功 false：请求失败
data	object	数据范围model
apiCopilotCubeModels	object[]	问数资源数组
llmCubeId	string	问数ID
alias	string	问数资源别名
createUser	string	创建人昵称
apiCopilotThemeModels	object[]	分析主题数组
themeId	string	分析主题ID
themeName	string	分析主题昵称
createUser	string	创建人昵称
apiCopilotLlmCubeModels	object[]	问数资源数组
llmCubeId	string	问数ID
alias	string	问数资源别名
createUser	string	创建人昵称

返回参数：

{
    "traceId":"d3f913a6-84ec-****-b30f-fd7540f3bdeb",
    "code":"0",
    "message":"success",
    "data": "121223****3453423423423523534634637c5",    
    "success":true
}

JAVA SDK 示例：

    @Test
    public void queryDataRange() throws SDKException {
        HttpRequest request = HttpRequest.build()
                .setUri("/openapi/v2/copilot/queryDataRange")
                .setMethod(HttpMethod.GET).setHttpContentType(FormatType.FORM);
        request.addParameter("type", "llmCube");
//        request.addParameter("keyword", "wu");
        String result = getOpenApiClient("eee").syncExecute(request);
        System.out.println(result);
    }