# 创建adhoc直方图查询 - CreateHistogram #### 功能介绍 创建adhoc直方图查询，执行SQL并返回直方图查询的操作ID，用于后续获取直方图结果 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-secmaster/secmaster_03_0008.html)。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-secmaster/secmaster_03_0023.html)。 #### URI POST /v2/{project_id}/workspaces/{workspace_id}/siem/ad-hoc-queries/histograms 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释**： 项目ID，用于明确项目归属，配置后可通过该ID查询项目下资产，可以通过调用API获取，也可以从控制台获取。[获取项目ID](https://support.huaweicloud.com/api-secmaster/secmaster_03_0014.html) **约束限制**： 不涉及 **取值范围**： 不涉及 **默认取值**： 不涉及 | | workspace_id | 是 | String | **参数解释**： 工作空间ID，用于标识安全云脑中的工作空间，确定操作所属的工作空间范围。可以通过调用API获取，也可以从控制台获取。 **约束限制**： 不涉及 **取值范围**： 不涉及 **默认取值**： 不涉及 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释**： 用户Token，通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。[获取用户Token](https://support.huaweicloud.com/api-secmaster/secmaster_03_0010.html) **约束限制**： 不涉及 **取值范围**： 不涉及 **默认取值**： 不涉及 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | session_id | 否 | String | **参数解释**： 会话ID，用于标识一次adhoc查询会话。该参数用于关联查询请求和结果，支持心跳维持、结果分页获取等功能。 **约束限制**： 不涉及 **取值范围**： 由英文字母、数字及连字符组成，长度为36个字符，格式为xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx **默认取值**： 不涉及 | | query | 否 | String | **参数解释**： 具体查询语句，即要执行的SQL查询文本。支持标准SQL语法以及特定扩展选项（如时间范围限制、扫描大小限制等）。 **约束限制**： - 最大长度1024字符 - SQL必须符合目标表的查询规范 **取值范围**： 由标准SQL语法字符组成，最大长度1024个字符 **默认取值**： 不涉及 | | query_type | 否 | String | **参数解释**： 查询类型，决定查询的执行模式。 **约束限制**： 不同类型的表可能只支持特定的查询类型 **取值范围**： - AUTOMATIC：自动选择执行模式，系统根据查询特征自动选择流式或批处理方式 - STREAMING：仅使用流式处理，适用于实时数据查询场景 - BATCH：仅使用批处理，适用于大数据量离线分析场景 **默认取值**： AUTOMATIC | | from | 否 | Long | **参数解释**： 查询的起始时间戳（毫秒级Unix时间戳）。用于限定查询的数据时间范围起点。 **约束限制**： - 必须小于等于to值 - 不能晚于当前时间 - 与to的时间跨度受表类型限制： - 流式表(STREAMING): 最多3天 - 索引表(INDEX): 最多7天 - 其他表: 最多180天 **取值范围**： 0 \~ 9223372036854776000 (毫秒级时间戳) **默认取值**： 不涉及 | | to | 否 | Long | **参数解释**： 查询的终止时间戳（毫秒级Unix时间戳）。用于限定查询的数据时间范围终点。 **约束限制**： - 必须大于等于from值 - 与from的时间跨度受表类型限制： - 流式表(STREAMING): 最多3天 - 索引表(INDEX): 最多7天 - 其他表: 最多180天 **取值范围**： 0 \~ 9223372036854776000 (毫秒级时间戳) **默认取值**： 不涉及 | | script_params | 否 | Array of [ScriptParam] objects | **参数解释**： 脚本参数列表，用于向查询脚本传递自定义参数。每个ScriptParam对象包含key（参数名，由英文字母、数字及下划线组成，最长128字符）和value（参数值，由标准字符组成，最长128字符）。 **约束限制**： - 最多包含50个参数项 - key和value的最大长度均为128字符 **取值范围**： 不涉及 **默认取值**： 不涉及 | | time_zone | 否 | String | **参数解释**： 时区信息，指定查询使用的时区。影响时间相关函数的计算结果。 **约束限制**： 必须是合法的时区标识符 **取值范围**： 由英文字母、斜杠、下划线及连字符组成，最长64个字符，格式为区域/城市，如Asia/Shanghai、America/New_York、UTC等 **默认取值**： UTC（协调世界时） | | sql_render_from | 否 | Long | **参数解释**： SQL渲染起始时间戳（毫秒级Unix时间戳）。SQL渲染时间戳用于确定SQL中时间函数（如now()）的参考时间点，与from参数的数据查询时间范围不同。from/to控制查询数据的时间范围，sql_render_from/sql_render_to控制SQL中时间函数的计算基准时间。 **约束限制**： - 必须小于等于sql_render_to值 - 不能晚于当前时间 - 与sql_render_to的时间跨度受表类型限制： - 流式表(STREAMING): 最多3天 - 索引表(INDEX): 最多7天 - 其他表: 最多180天 **取值范围**： 0 \~ 9223372036854776000 (毫秒级时间戳) **默认取值**： 不涉及 | | sql_render_to | 否 | Long | **参数解释**： SQL渲染终止时间戳（毫秒级Unix时间戳）。SQL渲染时间戳用于确定SQL中时间函数（如now()）的参考时间点，与to参数的数据查询时间范围不同。from/to控制查询数据的时间范围，sql_render_from/sql_render_to控制SQL中时间函数的计算基准时间。 **约束限制**： - 必须大于等于sql_render_from值 - 与sql_render_from的时间跨度受表类型限制： - 流式表(STREAMING): 最多3天 - 索引表(INDEX): 最多7天 - 其他表: 最多180天 **取值范围**： 0 \~ 9223372036854776000 (毫秒级时间戳) **默认取值**： 不涉及 | | source_page | 否 | String | **参数解释**： 查询来源页面标识，用于区分不同业务场景下的查询请求。 **约束限制**： 不涉及 **取值范围**： - defaultSourcePage：默认通用查询场景 **默认取值**： defaultSourcePage | 表4ScriptParam | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 否 | String | **参数解释**： 脚本参数的键名 **约束限制**： 不涉及 **取值范围**： 由英文字母、数字及下划线组成，长度为0\~128个字符 **默认取值**： 不涉及 | | value | 否 | String | **参数解释**： 脚本参数的值 **约束限制**： 不涉及 **取值范围**： 由标准可打印字符组成，长度为0\~128个字符 **默认取值**： 不涉及 | #### 响应参数 **状态码：200** 表5响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | operate_id | String | **参数解释**： Ad-hoc查询操作ID。执行SQL查询后返回的操作唯一标识，用于后续获取查询结果、关闭查询操作等场景。 **取值范围**： 只能由英文字母、数字及连字符组成，且长度为1\~63个字符。 | **状态码：400** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码 **取值范围**： 不涉及 | | error_msg | String | **参数解释**： 错误描述 **取值范围**： 不涉及 | #### 请求示例 ``` { "session_id" : "AFBF91E7-6AF0-419C-8611-DB6F5D42057D", "query" : "SELECT * FROM s_afdasdf", "from" : 1768044252498, "to" : 1768045152498, "query_type" : "QUERY", "time_zone" : "Asia/Shanghai" } ``` #### 响应示例 **状态码：200** ``` { "operate_id" : "208915df-7150-47d9-a6f9-4aa575efd142" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 创建adhoc直方图查询响应体 | | 400 | 错误响应 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-secmaster/ErrorCode.html)。