请求分类策略(预览)Request classification policy (Preview)

分类过程会根据请求的特征将传入请求分配到工作负荷组。The classification process assigns incoming requests to a workload group, based on the characteristics of the requests. 通过编写用户定义的函数来定制分类逻辑,作为群集级别请求分类策略的一部分。Tailor the classification logic by writing a user-defined function, as part of a cluster-level request classification policy.

如果没有启用请求分类策略,所有请求都将分类到 default 工作负荷组。In the absence of an enable request classification policy, all requests are classified into the default workload group.

策略对象Policy object

策略具有以下属性:The policy has the following properties:

  • IsEnabledbool - 指示是否启用策略。IsEnabled: bool - Indicates if the policy is enabled or not.
  • ClassificationFunctionstring - 用于对请求进行分类的函数主体。ClassificationFunction: string - The body of the function to use for classifying requests.

分类函数Classification function

根据用户定义的函数对传入请求进行分类。The classification of incoming requests is based on a user-defined function. 用于将请求分类到现有工作负荷组的函数的结果。The results of the function are used to classify requests into existing workload groups.

用户定义的函数具有以下特征和行为:The user-defined function has the following characteristics and behaviors:

  • 如果在策略中将 IsEnabled 设置为 true,则将为每个新请求评估用户定义函数。If IsEnabled is set to true in the policy, the user-defined function is evaluated for every new request.
  • 用户定义函数为请求的整个生存期提供请求的工作负荷组上下文。The user-defined function gives workload group context for the request for the full lifetime of the request.
  • 在以下情况中,将为请求提供 default 工作负荷组上下文:The request is given the default workload group context in the following situations:
    • 用户定义函数会返回空字符串、default 或不存在的工作负荷组的名称The user-defined function returns an empty string, default, or the name of non-existent workload group
    • 函数由于任何原因运行失败。The function fails for any reason.
  • 在任何给定时间只能指定一个用户定义函数。Only one user-defined function can be designated at any given time.

要求和限制Requirements and limitations

分类函数:A classification function:

  • 必须返回 string 类型的单个标量值,这是要向其分配请求的工作负荷组的名称。Must return a single scalar value of type string, that is the name of the workload group to assign the request to.

  • 不得引用其他任何实体(数据库、表或函数)。Must not reference any other entity (database, table, or function).

    • 具体而言,不得使用以下函数和运算符:Specifically - it may not use the following functions and operators:
      • cluster()
      • database()
      • table()
      • external_table()
      • externaldata
  • 有权访问特殊 dynamic 符号,即具有以下属性的 request_properties 属性包:Has access to a special dynamic symbol, a property-bag named request_properties, with the following properties:

    名称Name 类型Type 说明Description 示例Example
    current_databasecurrent_database string 请求数据库的名称。The name of the request database. "MyDatabase"
    current_applicationcurrent_application string 发送请求的应用程序的名称。The name of the application that sent the request. "Kusto.Explorer"
    current_principalcurrent_principal string 发送请求的主体标识的完全限定名称。The fully qualified name of the principal identity that sent the request. "aaduser=1793eb1f-4a18-418c-be4c-728e310c86d3;83af1c0e-8c6d-4f09-b249-c67a2e8fda65"
    query_consistencyquery_consistency string 在查询中,指查询的一致性(strongconsistencyweakconsistency)。For queries: the consistency of the query - strongconsistency or weakconsistency. 调用方可将此属性设置为请求的客户端请求属性的一部分:要设置的客户端请求属性为 queryconsistencyThis property can be set by the caller as part of the request's Client request properties: The client request property to set is: queryconsistency. "strongconsistency"
    request_descriptionrequest_description string 请求的作者可以包含的自定义文本。Custom text that the author of the request can include. 调用方可将此文本设置为请求的客户端请求属性的一部分:要设置的客户端请求属性为 request_descriptionThe text can be set by the caller as part of the request's Client request properties: The client request property to set is: request_description. "Some custom description"
    request_textrequest_text string 请求的混淆文本。The obfuscated text of the request. 查询文本中包含的混淆字符串字面量被多个星号 (*) 字符替换。Obfuscated string literals included in the query text are replaced by multiple of star (*) characters. ".show version"
    request_typerequest_type string 请求的类型(CommandQuery)。The type of the request - Command or Query. "Command"

示例Examples

单个工作负荷组A single workload group

iff(request_properties.current_application == "Kusto.Explorer" and request_properties.request_type == "Query",
    "Ad-hoc queries",
    "default")

多个工作负荷组Multiple workload groups

case(current_principal_is_member_of('aadgroup=somesecuritygroup@contoso.com'), "First workload group",
     request_properties.current_database == "MyDatabase" and request_properties.current_principal has 'aadapp=', "Second workload group",
     request_properties.current_application == "Kusto.Explorer" and request_properties.request_type == "Query", "Third workload group",
     request_properties.current_application == "Kusto.Explorer", "Third workload group",
     request_properties.current_application == "KustoQueryRunner", "Fourth workload group",
     request_properties.request_description == "this is a test", "Fifth workload group",
     hourofday(now()) between (17 .. 23), "Sixth workload group",
     "default")

控制命令Control commands

使用以下控制命令管理群集的请求分类。Use these control commands to manage a cluster's request classification.