请求属性和 ClientRequestPropertiesRequest properties and ClientRequestProperties

通过 .NET SDK 从 Kusto 发出请求时,请提供:When a request is made from Kusto through the .NET SDK, provide:

  • 连接字符串(指示要连接到的服务终结点)、身份验证参数,以及类似的与连接相关的信息。A connection string indicating the service endpoint to connect to, authentication parameters, and similar connection-related information. 连接字符串以编程方式通过 KustoConnectionStringBuilder 类提供。Programmatically, the connection string is represented via the KustoConnectionStringBuilderclass.

  • 数据库的名称,用来描述请求的“作用域”。The name of the database that is used to describe the "scope" of the request.

  • 请求(查询或命令)本身的文本。The text of the request (query or command) itself.

  • 客户端提供给服务并应用于请求的其他属性。Additional properties that the client provides to the service, and that are applied to the request. 这些属性以编程方式包含在名为 ClientRequestProperties 的类中。Programmatically, these properties are held by a class called ClientRequestProperties.

ClientRequestPropertiesClientRequestProperties

客户端请求属性有很多用途。The client request properties have many uses.

  • 使调试变得更轻松。Makes debugging easier. 例如,属性可以提供用于跟踪客户端/服务交互的相关字符串。For example, the properties may provide correlation strings that are used to track client/service interactions.
  • 影响应用于请求的限制和策略。Affects what limits and policies get applied to the request.
  • 使用查询参数,客户端应用程序可以基于用户输入将 Kusto 查询参数化。query parameters let client applications parameterize Kusto queries based on user input. 支持的属性的列表list of supported properties.

Kusto.Data.Common.ClientRequestProperties 类包含三种数据。The Kusto.Data.Common.ClientRequestProperties class holds three kinds of data.

  • 命名属性。Named properties.
  • 选项 - 选项名称到选项值的映射。Options - A mapping of an option name to an option value.
  • 参数 - 查询参数名称到查询参数值的映射。Parameters - A mapping of a query parameter name to a query parameter value.

备注

一些命名属性标记为“不使用”。Some named properties are marked "do not use". 此类属性不应由客户端指定,不会对服务造成任何影响。Such properties shouldn't be specified by clients, and have no effect on the service.

ClientRequestId (x-ms-client-request-id) 命名属性The ClientRequestId (x-ms-client-request-id) named property

此命名属性具有客户端指定的请求标识。This named property has the client-specified identity of the request. 客户端应当为其发送的每个请求指定唯一的每请求值。Clients should specify a unique per-request value with each request they send. 此值使得对失败进行调试更为容易,在某些情况下(例如在需要取消查询的情况下)也是必需的。This value makes debugging failures easier to do, and it's required in some scenarios, such as for query cancellation.

此属性的编程名称是 ClientRequestId,并且它将转换为 HTTP 标头 x-ms-client-request-idThe programmatic name of the property is ClientRequestId, and it translates into the HTTP header x-ms-client-request-id.

如果客户端未指定值,则 SDK 会将此属性设为一个(随机)值。This property will be set to a (random) value by the SDK if the client doesn't specify a value.

此属性的内容可以是任何可输出的唯一字符串,例如 GUID。The content of this property can be any printable unique string, such as a GUID. 但是,我们建议客户端使用:ApplicationName . ActivityName ; UniqueIdHowever, we recommend that clients use: ApplicationName . ActivityName ; UniqueId

  • ApplicationName 标识发出请求的客户端应用程序。ApplicationName identifies the client application that makes the request.
  • ActivityName 标识客户端应用程序发出客户端请求时所针对的活动类型。ActivityName identifies the kind of activity for which the client application issues the client request.
  • UniqueId 标识特定的请求。UniqueId identifies the specific request.

application (x-ms-app) 命名属性The application (x-ms-app) named property

Application (x-ms-app) 命名属性具有发出请求的客户端应用程序的名称,用于跟踪。The Application (x-ms-app) named property has the name of the client application that makes the request, and is used for tracing.

此属性的编程名称是 Application,并且它将转换为 HTTP 标头 x-ms-appThe programmatic name of this property is Application, and it translates into the HTTP header x-ms-app. 可以在 Kusto 连接字符串中将其指定为 Application Name for TracingIt can be specified in the Kusto connection string as Application Name for Tracing.

如果客户端未指定其自己的值,则此属性将设置为承载 SDK 的进程的名称。This property will be set to the name of the process hosting the SDK if the client doesn't specify its own value.

User (x-ms-user) 命名属性The User (x-ms-user) named property

User (x-ms-user) 命名属性具有发出请求的用户的标识,用于跟踪。The User (x-ms-user) named property has the identity of the user that makes the request, and is used for tracing.

此属性的编程名称是 User,并且它将转换为 HTTP 标头 x-ms-userThe programmatic name of this property is User, and it translates into the HTTP header x-ms-user. 可以在 Kusto 连接字符串中将其指定为 User Name for TracingIt can be specified in the Kusto connection string as User Name for Tracing.

使用 REST API 控制请求属性Controlling request properties using the REST API

向 Kusto 服务发出 HTTP 请求时,请在作为 POST 请求正文的 JSON 文档中使用 properties 槽来提供请求属性。When issuing an HTTP request to the Kusto service, use the properties slot in the JSON document that is the POST request body, to provide request properties.

备注

某些属性(例如“客户端请求 ID”,它是客户端向服务提供的用于标识请求的相关 ID)可以在 HTTP 标头中提供,也可以在使用 HTTP GET 的情况下设置。Some of the properties (such as the "client request ID", which is the correlation ID that the client provides to the service for identifying the request) can be provided in the HTTP header, and can also be set if HTTP GET is used. 有关详细信息,请参阅 Kusto REST API 请求对象For more information, see the Kusto REST API request object.

以请求属性的形式提供用于查询参数化的值Providing values for query parameterization as request properties

Kusto 查询可以通过在查询文本中使用专门的声明查询参数语句来引用查询参数。Kusto queries can refer to query parameters by using a specialized declare query-parameters statement in the query text. 此语句允许客户端应用程序以安全的方式基于用户输入将 Kusto 查询参数化,而无需担心注入式攻击。This statement lets client applications parameterize Kusto queries based on user input, in a secure manner, and without fear of injection attacks.

以编程方式使用 ClearParameterSetParameterHasParameter 方法设置属性值。Programmatically, set properties values by using the ClearParameter, SetParameter, and HasParameter methods.

在 REST API 中,查询参数与其他请求属性显示在相同的 JSON 编码字符串中。In the REST API, query parameters appear in the same JSON-encoded string as the other request properties.

用于使用请求属性的示例客户端代码Sample client code for using request properties

public static System.Data.IDataReader QueryKusto(
    Kusto.Data.Common.ICslQueryProvider queryProvider,
    string databaseName,
    string query)
{
    var queryParameters = new Dictionary<String, String>()
    {
        { "xIntValue", "111" },
        { "xStrValue", "abc" },
        { "xDoubleValue", "11.1" }
    };

    // Query parameters (and many other properties) are provided
    // by a ClientRequestProperties object handed alongside
    // the query:
    var clientRequestProperties = new Kusto.Data.Common.ClientRequestProperties(
        principalIdentity: null,
        options: null,
        parameters: queryParameters);

    // Having client code provide its own ClientRequestId is
    // highly recommended. It not only allows the caller to
    // cancel the query, but also makes it possible for the Kusto
    // team to investigate query failures end-to-end:
    clientRequestProperties.ClientRequestId
        = "MyApp.MyActivity;"
        + Guid.NewGuid().ToString();

    // This is an example for setting an option
    // ("notruncation", in this case). In most cases this is not
    // needed, but it's included here for completeness:
    clientRequestProperties.SetOption(
        Kusto.Data.Common.ClientRequestProperties.OptionNoTruncation,
        true);
 
    try
    {
        return queryProvider.ExecuteQuery(query, clientRequestProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine(
            "Failed invoking query '{0}' against Kusto."
            + " To have the Kusto team investigate this failure,"
            + " please open a ticket @ https://aka.ms/kustosupport,"
            + " and provide: ClientRequestId={1}",
            query, clientRequestProperties.ClientRequestId);
        return null;
    }
}

ClientRequestProperties 的列表List of ClientRequestProperties

  • debug_query_externaldata_projection_fusion_disabled (OptionDebugQueryDisableExternalDataProjectionFusion):如果设置了此项,则不要将投影融合到 ExternalData 运算符中。debug_query_externaldata_projection_fusion_disabled (OptionDebugQueryDisableExternalDataProjectionFusion): If set, don't fuse projection into ExternalData operator. [Boolean][Boolean]
  • debug_query_fanout_threads_percent_external_data (OptionDebugQueryFanoutThreadsPercentExternalData):要将执行扇出到的线程所占的百分比(对于外部数据节点)。debug_query_fanout_threads_percent_external_data (OptionDebugQueryFanoutThreadsPercentExternalData): The percentage of threads to fan out execution to, for external data nodes. [Int][Int]
  • deferpartialqueryfailures (OptionDeferPartialQueryFailures):如果为 true,则会禁止将部分查询失败报告为结果集的一部分。deferpartialqueryfailures (OptionDeferPartialQueryFailures): If true, disables the reports of partial query failures as part of the result set. [Boolean][Boolean]
  • max_memory_consumption_per_query_per_node (OptionMaxMemoryConsumptionPerQueryPerNode):替代整个查询可以为每个节点分配的默认最大内存量。max_memory_consumption_per_query_per_node (OptionMaxMemoryConsumptionPerQueryPerNode): Overrides the default maximum amount of memory that a whole query may allocate per node. [UInt64][UInt64]
  • maxmemoryconsumptionperiterator (OptionMaxMemoryConsumptionPerIterator):替代查询运算符可以分配的默认最大内存量。maxmemoryconsumptionperiterator (OptionMaxMemoryConsumptionPerIterator): Overrides the default maximum amount of memory that a query operator may allocate. [UInt64][UInt64]
  • maxoutputcolumns (OptionMaxOutputColumns):替代查询可以生成的默认最大列数。maxoutputcolumns (OptionMaxOutputColumns): Overrides the default maximum number of columns that a query may produce. [Long][Long]
  • norequesttimeout (OptionNoRequestTimeout):允许将请求超时设置为其最大值。norequesttimeout (OptionNoRequestTimeout): Enables setting the request timeout to its maximum value. [Boolean][Boolean]
  • notruncation (OptionNoTruncation):启用禁止截断返回给调用方的查询结果的功能。notruncation (OptionNoTruncation): Enables suppressing truncation of the query results returned to the caller. [Boolean][Boolean]
  • push_selection_through_aggregation (OptionPushSelectionThroughAggregation):如果为 true,则通过聚合推送简单的选择 [Boolean]push_selection_through_aggregation (OptionPushSelectionThroughAggregation): If true, pushes simple selection through aggregation [Boolean]
  • query_admin_super_slacker_mode (OptionAdminSuperSlackerMode):如果为 true,则将查询的执行委托给另一个节点 [Boolean]query_admin_super_slacker_mode (OptionAdminSuperSlackerMode): If true, delegate execution of the query to another node [Boolean]
  • query_bin_auto_at (QueryBinAutoAt):计算 bin_auto() 函数时要使用的起始值。query_bin_auto_at (QueryBinAutoAt): When evaluating the bin_auto() function, the start value to use. [LiteralExpression][LiteralExpression]
  • query_bin_auto_size (QueryBinAutoSize):计算 bin_auto() 函数时要使用的 bin 大小值。query_bin_auto_size (QueryBinAutoSize): When evaluating the bin_auto() function, the bin size value to use. [LiteralExpression][LiteralExpression]
  • query_cursor_after_default (OptionQueryCursorAfterDefault):在不使用参数的情况下调用时 cursor_after() 函数的默认参数值。query_cursor_after_default (OptionQueryCursorAfterDefault): The default parameter value of the cursor_after() function when called without parameters. [string][string]
  • query_cursor_before_or_at_default (OptionQueryCursorBeforeOrAtDefault):在不使用参数的情况下调用时 cursor_before_or_at() 函数的默认参数值。query_cursor_before_or_at_default (OptionQueryCursorBeforeOrAtDefault): The default parameter value of the cursor_before_or_at() function when called without parameters. [string][string]
  • query_cursor_current (OptionQueryCursorCurrent):替代 cursor_current() 或 current_cursor() 函数返回的游标值。query_cursor_current (OptionQueryCursorCurrent): Overrides the cursor value returned by the cursor_current() or current_cursor() functions. [string][string]
  • query_cursor_scoped_tables (OptionQueryCursorScopedTables):作用域应限定为 cursor_after_default 的表名称的列表。query_cursor_scoped_tables (OptionQueryCursorScopedTables): List of table names that should be scoped to cursor_after_default .. cursor_before_or_at_default(上限为可选)。cursor_before_or_at_default (upper bound is optional). [dynamic][dynamic]
  • query_datascope (OptionQueryDataScope):控制查询的 datascope,了解查询是应用于所有数据还是仅应用于它的一部分。query_datascope (OptionQueryDataScope): Controls the query's datascope, about whether the query applies to all data or just part of it. [“default”、“all”或“hotcache”]['default', 'all', or 'hotcache']
  • query_datetimescope_column (OptionQueryDateTimeScopeColumn):控制查询的日期/时间范围 (query_datetimescope_to / query_datetimescope_from) 的列名称。query_datetimescope_column (OptionQueryDateTimeScopeColumn): Controls the column name for the query's datetime scope (query_datetimescope_to / query_datetimescope_from). [String][String]
  • query_datetimescope_from (OptionQueryDateTimeScopeFrom):控制查询的日期/时间范围(最早)。query_datetimescope_from (OptionQueryDateTimeScopeFrom): Controls the query's datetime scope (earliest). 此值用作仅基于 query_datetimescope_column 的自动应用筛选器(如果已定义)。The value is used as an auto-applied filter on query_datetimescope_column only (if defined). [DateTime][DateTime]
  • query_datetime\scope_to (OptionQueryDateTimeScopeTo):控制查询的日期/时间范围(最新)。query_datetime\scope_to (OptionQueryDateTimeScopeTo): Controls the query's datetime scope (latest). 此值用作仅基于 query_datetimescope_column 的自动应用筛选器(如果已定义)。The value is used as an auto-applied filter on query_datetimescope_column only (if defined). [DateTime][DateTime]
  • query_distribution_nodes_span (OptionQueryDistributionNodesSpanSize):如果设置了此项,则它控制子查询合并的行为方式:执行节点将在查询层次结构中为每个节点子组引入一个附加级别。query_distribution_nodes_span (OptionQueryDistributionNodesSpanSize): If set, controls the way subquery merge behaves: the executing node will introduce an additional level in the query hierarchy for each subgroup of nodes. 此选项设置子组的大小。This option sets the size of the subgroup. [Int][Int]
  • query_fanout_nodes_percent (OptionQueryFanoutNodesPercent):要将执行扇出到的节点所占的百分比。query_fanout_nodes_percent (OptionQueryFanoutNodesPercent): The percentage of nodes to fan out execution to. [Int][Int]
  • query_fanout_threads_percent (OptionQueryFanoutThreadsPercent):要将执行扇出到的线程所占的百分比。query_fanout_threads_percent (OptionQueryFanoutThreadsPercent): The percentage of threads to fan out execution to. [Int][Int]
  • query_language (OptionQueryLanguage):控制解释查询文本的方式。query_language (OptionQueryLanguage): Controls how the query text is to be interpreted. [“csl”、“kql”或“sql”]['csl','kql' or 'sql']
  • query_max_entities_in_union (OptionMaxEntitiesToUnion):替代允许查询生成的默认最大列数。query_max_entities_in_union (OptionMaxEntitiesToUnion): Overrides the default maximum number of columns a query is allowed to produce. [Long][Long]
  • query_now (OptionQueryNow):替代 now(0s) 函数返回的日期/时间值。query_now (OptionQueryNow): Overrides the datetime value returned by the now(0s) function. [DateTime][DateTime]
  • query_python_debug (OptionDebugPython):如果设置了此项,则将为枚举的 python 节点(默认值为第一个)生成一个 python 调试查询。query_python_debug (OptionDebugPython): If set, generates a python debug query for the enumerated python node (default first). [Boolean 或 Int][Boolean or Int]
  • query_results_apply_getschema (OptionQueryResultsApplyGetSchema):如果设置了此项,则将检索查询结果中每个表格数据的架构而不检索数据本身。query_results_apply_getschema (OptionQueryResultsApplyGetSchema): If set, retrieves the schema of each tabular data in the results of the query instead of the data itself. [Boolean][Boolean]
  • query_results_cache_max_age (OptionQueryResultsCacheMaxAge):如果为正值,则控制 Kusto 可能返回的缓存查询结果的最长寿命 [TimeSpan]query_results_cache_max_age (OptionQueryResultsCacheMaxAge): If positive, controls the maximum age of the cached query results, which Kusto may return [TimeSpan]
  • query_results_progressive_row_count (OptionProgressiveQueryMinRowCountPerUpdate):告诉 Kusto 要在每个更新中发送多少条记录。query_results_progressive_row_count (OptionProgressiveQueryMinRowCountPerUpdate): Tells Kusto how many records to send in each update. 仅当设置了 OptionResultsProgressiveEnabled 时,此值才会生效The value takes effect only if OptionResultsProgressiveEnabled is set
  • query_results_progressive_update_period (OptionProgressiveProgressReportPeriod):告诉 Kusto 发送进度帧的频率。query_results_progressive_update_period (OptionProgressiveProgressReportPeriod): Tells Kusto how often to send progress frames. 仅当设置了 OptionResultsProgressiveEnabled 时,此值才会生效The value takes effect only if OptionResultsProgressiveEnabled is set
  • query_shuffle_broadcast_join (ShuffleBroadcastJoin):在广播联接上启用乱序。query_shuffle_broadcast_join (ShuffleBroadcastJoin): Enables shuffling over broadcast join.
  • query_take_max_records (OptionTakeMaxRecords):允许将查询结果限制为此数量的记录。query_take_max_records (OptionTakeMaxRecords): Enables limiting query results to this number of records. [Long][Long]
  • queryconsistency (OptionQueryConsistency):控制查询一致性。queryconsistency (OptionQueryConsistency): Controls query consistency. [“strongconsistency”或“normalconsistency”或“weakconsistency”]['strongconsistency' or 'normalconsistency' or 'weakconsistency']
  • request_callout_disabled (OptionRequestCalloutDisabled):如果指定了此项,则表示请求不能调用用户提供的服务。request_callout_disabled (OptionRequestCalloutDisabled): If specified, indicates that the request can't call-out to a user-provided service. [Boolean][Boolean]
  • request_description (OptionRequestDescription):请求创建者希望将其作为请求说明包括的任意文本。request_description (OptionRequestDescription): Arbitrary text that the author of the request wants to include as the request description. [String][String]
  • request_external_table_disabled (OptionRequestExternalTableDisabled):如果指定了此项,则表示请求无法调用 ExternalTable 中的代码。request_external_table_disabled (OptionRequestExternalTableDisabled): If specified, indicates that the request can't invoke code in the ExternalTable. [Boolean][Boolean]
  • request_readonly (OptionRequestReadOnly):如果指定了此项,则表示请求不能写入任何内容。request_readonly (OptionRequestReadOnly): If specified, indicates that the request can't write anything. [Boolean][Boolean]
  • request_remote_entities_disabled (OptionRequestRemoteEntitiesDisabled):如果指定了此项,则表示请求无法访问远程数据库和群集。request_remote_entities_disabled (OptionRequestRemoteEntitiesDisabled): If specified, indicates that the request can't access remote databases and clusters. [Boolean][Boolean]
  • request_sandboxed_execution_disabled (OptionRequestSandboxedExecutionDisabled):如果指定了此项,则表示请求无法调用沙盒中的代码。request_sandboxed_execution_disabled (OptionRequestSandboxedExecutionDisabled): If specified, indicates that the request can't invoke code in the sandbox. [Boolean][Boolean]
  • results_progressive_enabled (OptionResultsProgressiveEnabled):如果设置了此项,则会启用渐进式查询流results_progressive_enabled (OptionResultsProgressiveEnabled): If set, enables the progressive query stream
  • servertimeout (OptionServerTimeout):替代默认的请求超时。servertimeout (OptionServerTimeout): Overrides the default request timeout. [TimeSpan][TimeSpan]
  • truncationmaxrecords (OptionTruncationMaxRecords):替代查询可以返回给调用方的默认最大记录数(截断)。truncationmaxrecords (OptionTruncationMaxRecords): Overrides the default maximum number of records a query may return to the caller (truncation). [Long][Long]
  • truncationmaxsize (OptionTruncationMaxSize):替代允许查询返回给调用方的默认最大数据大小(截断)。truncationmaxsize (OptionTruncationMaxSize): Overrides the default maximum data size a query is allowed to return to the caller (truncation). [Long][Long]
  • validate_permissions (OptionValidatePermissions):验证用户执行查询的权限,但不运行查询本身。validate_permissions (OptionValidatePermissions): Validates the user's permissions to make the query and doesn't run the query itself. [Boolean][Boolean]