数据 API 生成器 1.6 中的新增功能

2025-10-21

此增量版本侧重于多层缓存、扩展日志记录和可观测性、机密管理和查询/分页改进。

简介：级别 2 （分布式）缓存

数据 API 生成器长期以来支持级别 1（L1）内存中缓存以及与缓存相关的 HTTP 请求标头，例如 no-store、no-cache 和 only-if-cached，以影响缓存行为。

在此版本中，我们添加了级别 2 （L2）分布式缓存。

全局运行时配置：

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 30,
      "level-2": {
        "enabled": true,
        "provider": "redis",
        "connection-string": "localhost:6379",
        "partition": "prod-api"
      }
    }
  }
}

特定于实体的替代：

{
  "entities": {
    "Products": {
      "source": "dbo.Products",
      "cache": { "enabled": true, "ttl-seconds": 120, "level": "L1L2" }
    },
    "Orders": {
      "source": "dbo.Orders",
      "cache": { "enabled": true, "level": "L1" }
    }
  }
}

缓存级别 `L1L2`

TL;DRL1L2 = 请求 → L1 → L2 → DB → L2 → L1 → 响应

默认情况下，启用了缓存的实体使用级别 L1L2。 L1 是针对每个进程的内存缓存。 L2 是分布式缓存层（当前使用 Redis）以及用于实现跨实例一致性的背板。使用 L1L2时，缓存查找首先检查 L1。出现L1未命中时，它会检查L2二级缓存是否已全局启用并配置。如果条目不在任一层中，DAB 将执行数据库查询。结果存储在 L1 和 L2 中（双写）。同一实例上的将来请求从本地 L1提供服务。

其他实例上的请求可以拉取 L2 条目并将其提升为自己的 L1条目。如果本地容器被回收，L1 未命中后接着L2 命中，仍可以避免数据库往返，从而提供热（warm）的分布式缓存。如果 L2 不在全局范围内启用，则设置为 L1L2 的实体集会表现为 L1。可选的分区设置用于命名 Redis 键和背板通道，从而只有共享该分区的容器参与同一个分布式缓存空间。

简介：灵活的日志记录

在 1.5 版本之前，开发人员受到 DAB 系统中默认日志级别和硬编码筛选器的限制。现在，我们支持对引擎发出的日志进行可配置的过滤器和级别设置。

现在，在版本 1.6 中，我们将添加到接收器列表。数据 API 生成器现在不仅支持 Application Insights 和 OpenTelemetry 发布，还支持将文件和Azure Log Analytics作为目标。丰富、可配置的日志记录，随时随地满足您的需求。

{
  "telemetry": {
      "log-level": { },
      "open-telemetry": { },
      "application-insights": { },
      "azure-log-analytics": { }, // new!
      "file": { } // new!
    }
  }
}

文件存储端

以前，DAB 开发人员大多仅限于容器中的控制台日志。使用版本 1.6，您现在可以将日志导出到容器文件夹中的本地文件，以便使用您首选的监控解决方案系统地调试和观察 DAB 的行为。将容器卷装载为目标文件夹是跨容器生命周期保留日志的一种简单方法。

示例文件接收器配置：

{
  "runtime": {
    "telemetry": {
        "file": {
          "enabled": ...,               // Turn file logging on or off
          "path": ...,                  // Folder path for log files
          "rolling-interval": ...,      // How often a new log file is created
          "retained-file-count-limit": ..., // Max number of log files to keep
          "file-size-limit-bytes": ..., // Max size of a log file before rolling
        }
      }
    }
  }
}

Azure Log Analytics 日志终端

企业开发人员通常面临比本地调试更严格的要求。许多组织都要求集中日志记录、合规性审核并与公司监视解决方案集成。为了支持这些方案，数据 API 生成器与 Azure Log Analytics 集成。日志流向一个安全的集中式平台，该平台与企业的保留、治理和可观测性策略保持一致。

Azure Log Analytics 接收器配置示例：

{
  "telemetry": {
    "azure-log-analytics": {
      "enabled": ...,                 // Turn logging on or off
      "auth": {
        "workspace-id": ...,          // Workspace ID
        "dcr-immutable-id": ...,      // Data Collection Rule
        "dce-endpoint": ...           // Data Collection Endpoint
      },
      "dab-identifier": ...,          // Unique string to identify log source
      "flush-interval-seconds": ...   // How often logs are flushed
    }
  }
}

与 Application Insights 对比

Application Insights 侧重于应用性能监视（APM），Azure Log Analytics 提供更广泛的覆盖范围。它聚合来自应用、Azure 资源、VM、容器、网络和安全工具的日志。这些日志集中在用于 Kusto 查询语言 (KQL) 查询、关联和合规性的工作区中。

查询和分页增强功能

简介：IN 运算符（SQL 后端、GraphQL）

DAB 的新 IN 运算符有助于简化 GraphQL 查询中的多值筛选。它减少了串联的 OR 筛选器，生成更简洁的 SQL。此功能是 DAB GraphQL 语法的一部分，尚不在 DAB 的 REST $filter 语法中。

query {
  products(filter: { status: { in: ["ACTIVE", "PENDING"] } }) {
    items { id name status }
  }
}

简介：Relative nextLink

DAB 的新相对 nextLink 选项允许开发人员配置引擎以发出相对链接而不是绝对链接。此功能是一个社区频繁请求的功能，在反向代理和域重写方案中特别有用，因为相对链接可以防止主机名不匹配。

{
  "runtime": {
    "pagination": {
      "next-link-relative": true // default is false
    }
  }
}

当下一个链接相对是 true时， nextLink 将是相对的（从 /开头）。
如果false，它将是绝对URL。

健康检查

为了更快地提供综合状态，数据 API 构建器的健康检查现在并行运行。这可减少多源部署中的延迟，尤其是在涉及多个终结点时，运行状况检查用于确定 DAB 容器的部署状态，例如 .NET Aspire 应用程序主机中的部署状态。

健康 DOP 配置示例：

{
  "runtime": {
    "health": {
      "max-query-parallelism": 8 
    }
  }
}

配置	最小值	违约	最大值
`max-query-parallelism`	1	4	8

DWSQL 策略

数据 API 生成器始终允许开发人员配置 API 级策略。这些策略作为额外谓词追加到查询的 WHERE 子句中，并支持 @item 和 @claim 查询，提供高级行级安全性，而无需数据库更改。

使用版本 1.6 时，数据 API 生成器会将此功能扩展到 Azure SQL 数据仓库（dwsql），该数据源已受支持，但直到现在才没有策略集成。开发人员现在可以定义符合其他 SQL 数据库类型的 DWSQL 的策略。

具有策略配置的示例实体：

{
  "entities": {
    "Orders": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [ "read" ],
          "policy": "@item.Region = @claim.region"
        }
      ]
    }
  }
}

在此示例中，当authenticated用户查询Orders时，引擎会自动追加WHERE Region = <user's claim:region>。

反馈

此页面是否有帮助？