azure-monitor-query-java

用途

Azure Monitor Query SDK for Java 是 Azure SDK for Java 中用于查询 Azure Monitor 日志与指标的客户端库。它让 Java 应用能够以编程方式执行两类查询：一是针对 Log Analytics 工作区使用 Kusto 查询语言（KQL）查询日志与性能数据；二是查询 Azure 资源在固定间隔采集的数值型时序指标。

弃用说明

该包已被弃用，官方建议迁移到以下两个包：

azure-monitor-query-logs — 用于 Log Analytics 日志查询
azure-monitor-query-metrics — 用于指标查询

资料中提供了日志迁移与指标迁移的迁移指南链接，但未给出具体迁移步骤内容。

安装

可通过 Maven 依赖引入：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-query</artifactId>
    <version>1.5.9</version>
</dependency>

或使用 Azure SDK BOM 统一管理版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-monitor-query</artifactId>
    </dependency>
</dependencies>

前置条件

Log Analytics 工作区（用于日志查询）
Azure 资源（用于指标查询）
具有相应权限的 TokenCredential

环境变量示例：

LOG_ANALYTICS_WORKSPACE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_RESOURCE_ID=/subscriptions/{sub}/resourceGroups/{rg}/providers/{provider}/{resource}

主要能力

客户端创建

库提供同步与异步两类客户端：LogsQueryClient / LogsQueryAsyncClient 用于日志查询，MetricsQueryClient / MetricsQueryAsyncClient 用于指标查询。均通过 Builder 配合 DefaultAzureCredential 构建。

主权云配置

支持为 Azure China Cloud 指定端点，例如日志端点 https://api.loganalytics.azure.cn/v1，指标端点 https://management.chinacloudapi.cn。

日志查询操作

基本查询：使用 queryWorkspace 传入工作区 ID、KQL 查询与 QueryTimeInterval 时间范围。
按资源 ID 查询：使用 queryResource。
结果映射到自定义模型：可将查询结果直接映射为自定义 Java 类列表。
批量查询：通过 LogsBatchQuery 将多个查询合并为一次请求，并可通过 LogsBatchQueryResultCollection 获取各查询结果，检查失败状态。
查询选项：可设置服务器超时、包含统计信息、包含可视化数据。
多工作区查询：通过 setAdditionalWorkspaces 指定额外工作区。

指标查询操作

基本指标查询：使用 queryResource 传入资源 URI 与指标名称列表。
带聚合的指标查询：可设置粒度与聚合类型（如 AVERAGE、COUNT）。
多资源指标查询：使用 MetricsClient 的 queryResources 同时查询多个资源与多个指标。

响应结构

日志响应 LogsQueryResult 包含 statistics、visualization、error 与 tables（含 columns 与 rows）。指标响应 MetricsQueryResult 包含 granularity、timeInterval、namespace、resourceRegion 与 metrics（含 timeSeries 与 values，values 含 timeStamp、count、average、total、maximum、minimum）。

错误处理

可捕获 HttpResponseException，并检查 LogsQueryResultStatus 中的 PARTIAL_FAILURE 状态以处理部分失败。

使用方式

典型流程为：配置环境变量与凭据 → 构建对应客户端 → 调用查询方法并传入工作区/资源标识、查询语句与时间范围 → 遍历结果表格行或指标时序数据 → 处理异常与部分失败状态。

适用场景

适用于需要在 Java 应用中读取 Azure Monitor 日志或指标数据的场景，例如将日志查询结果映射为业务模型、批量拉取多个查询、按资源查询指标并做聚合分析、跨多个工作区查询等。

限制

该包已弃用，官方建议迁移到 azure-monitor-query-logs 与 azure-monitor-query-metrics。
资料中未提供具体迁移步骤、收费、价格或性能效果数据。
使用前需具备 Log Analytics 工作区、Azure 资源与相应权限的 TokenCredential。
资料建议仅在与上述范围明确匹配的任务中使用，不应将输出视为环境特定验证、测试或专家评审的替代；若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。