Consultar resposta HTTP V2

Alterne os serviços usando a lista suspensa De versão . Saiba mais sobre navegação.
Aplica-se a: ✅ Microsoft Fabric ✅ Azure Data Explorer

Linha de status de resposta HTTP

Se a solicitação for bem-sucedida, o código de status de resposta HTTP será 200 OK. O corpo da resposta HTTP é uma matriz JSON, conforme explicado abaixo.

Se a solicitação falhar, o código de status de resposta HTTP será um erro ou 4xx um 5xx erro. A frase de motivo incluirá informações adicionais sobre a falha. O corpo da resposta HTTP é um objeto JSON, conforme explicado abaixo.

Observação

A solicitação pode retornar um código de status, mas o corpo da 200 OKresposta HTTP indicará um erro. Isso pode acontecer quando o erro é gerado depois que a linha de status HTTP já é retornada. Espera-se que o leitor verifique explicitamente essa condição.

Os cabeçalhos da resposta HTTP

Independentemente do êxito/falha da solicitação, dois cabeçalhos HTTP personalizados são incluídos com a resposta:

  1. x-ms-client-request-id: o serviço retorna uma cadeia de caracteres opaca que identifica o par de solicitação/resposta para fins de correlação. Se a solicitação incluir uma ID de solicitação do cliente, seu valor será exibido aqui; caso contrário, alguma cadeia de caracteres aleatória será retornada.

  2. x-ms-activity-id: o serviço retorna uma cadeia de caracteres opaca que identifica exclusivamente o par de solicitação/resposta para fins de correlação. Diferentemente x-ms-client-request-iddisso, esse identificador não é afetado por nenhuma informação na solicitação e é exclusivo por resposta.

Corpo da resposta HTTP (em falha de solicitação)

Em caso de falha na solicitação, o corpo da resposta HTTP será um documento JSON formatado de acordo OneApiErrors com as regras. Para obter uma descrição do formato, consulte a OneApiErrors seção 7.10.2 aqui. Veja abaixo um exemplo para essa falha.

{
    "error": {
        "code": "General_BadRequest",
        "message": "Request is invalid and cannot be executed.",
        "@type": "Kusto.Data.Exceptions.KustoBadRequestException",
        "@message": "Request is invalid and cannot be processed: Semantic error: SEM0100: 'table' operator: Failed to resolve table expression named 'aaa'",
        "@context": {
            "timestamp": "2023-04-18T12:59:27.4855445Z",
            "serviceAlias": "HELP",
            "machineName": "KEngine000000",
            "processName": "Kusto.WinSvc.Svc",
            "processId": 12580,
            "threadId": 10260,
            "clientRequestId": "Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404",
            "activityId": "9dcc4522-7b51-41db-a7ae-7c1bfe0696b2",
            "subActivityId": "d0f30c8c-e6c6-45b6-9275-73dd6b379ecf",
            "activityType": "DN.FE.ExecuteQuery",
            "parentActivityId": "6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84",
            "activityStack": "(Activity stack: CRID=Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404 ARID=9dcc4522-7b51-41db-a7ae-7c1bfe0696b2 > KD.Query.Client.ExecuteQueryAsKustoDataStream/8191428e-7139-4c5d-9da7-839a0f21c5b9 > P.WCF.Service.ExecuteQueryAsKustoDataStream..IInterNodeCommunicationQueryContract/6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84 > DN.FE.ExecuteQuery/d0f30c8c-e6c6-45b6-9275-73dd6b379ecf)"
        },
        "@permanent": true,
        "@text": "aaa",
        "@database": "Samples",
        "@ClientRequestLogger": "",
        "innererror": {
            "code": "SEM0100",
            "message": "'table' operator: Failed to resolve table expression named 'aaa'",
            "@type": "Kusto.Data.Exceptions.SemanticException",
            "@message": "Semantic error: SEM0100: 'table' operator: Failed to resolve table expression named 'aaa'",
            "@context": {
                "timestamp": "2023-04-18T12:59:27.4855445Z",
                "serviceAlias": "HELP",
                "machineName": "KEngine000000",
                "processName": "Kusto.WinSvc.Svc",
                "processId": 12580,
                "threadId": 10260,
                "clientRequestId": "Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404",
                "activityId": "9dcc4522-7b51-41db-a7ae-7c1bfe0696b2",
                "subActivityId": "d0f30c8c-e6c6-45b6-9275-73dd6b379ecf",
                "activityType": "DN.FE.ExecuteQuery",
                "parentActivityId": "6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84",
                "activityStack": "(Activity stack: CRID=Kusto.Cli;b90f4260-4eac-4574-a27a-3f302db21404 ARID=9dcc4522-7b51-41db-a7ae-7c1bfe0696b2 > KD.Query.Client.ExecuteQueryAsKustoDataStream/8191428e-7139-4c5d-9da7-839a0f21c5b9 > P.WCF.Service.ExecuteQueryAsKustoDataStream..IInterNodeCommunicationQueryContract/6e3c8dab-0aaf-4df5-85b5-fc20b0b29a84 > DN.FE.ExecuteQuery/d0f30c8c-e6c6-45b6-9275-73dd6b379ecf)"
            },
            "@permanent": true,
            "@errorCode": "SEM0100",
            "@errorMessage": "'table' operator: Failed to resolve table expression named 'aaa'"
        }
    }
}

Corpo da resposta HTTP (com êxito na solicitação)

Após o êxito da solicitação, o corpo da resposta HTTP será uma matriz JSON que codifica os resultados da solicitação.

Logicamente, a resposta V2 descreve um objeto DataSet que contém qualquer número de Tabelas. Essas tabelas podem representar os dados reais solicitados pela solicitação ou informações adicionais sobre a execução da solicitação (como uma contabilidade dos recursos consumidos pela solicitação). Além disso, a solicitação real pode realmente falhar (devido a várias condições), mesmo que um 200 OK status seja retornado e, nesse caso, a resposta incluirá dados parciais de resposta mais uma indicação dos erros.

Fisicamente, a matriz JSON do corpo da resposta é uma lista de objetos JSON, cada um deles chamado de quadro. O objeto DataSet é codificado em dois quadros: DataSetHeader e DataSetCompletion. O primeiro é sempre o primeiro quadro e o segundo é sempre o último quadro. Em "entre" eles, é possível encontrar os quadros que descrevem os objetos Table.

Os objetos Table podem ser codificados de duas maneiras:

  1. Como um único quadro: DataTable. Esse é o padrão.

  2. Como alternativa, como uma "mistura" de quatro tipos de quadros: TableHeader (que vem primeiro e descreve a tabela), TableFragment (que descreve os dados de uma tabela), TableProgress (que é opcional e fornece uma estimativa de quão longe estamos nos dados da tabela) e TableCompletion (que é o último quadro da tabela).

O segundo caso é chamado de "modo progressivo" e só será exibido se a propriedade de solicitação results_progressive_enabled do cliente estiver definida como true. Nesse caso, cada quadro TableFragment descreve uma atualização para os dados acumulados por todos os quadros anteriores da tabela, como uma operação de acréscimo ou como uma operação de substituição. (Este último é usado, por exemplo, quando algum cálculo de agregação de execução longa é executado no "nível superior" da consulta, de modo que um resultado de agregação inicial é substituído por resultados mais precisos posteriormente.)

DataSetHeader

O DataSetHeader quadro é sempre o primeiro no conjunto de dados e aparece exatamente uma vez.

{
    "Version": string,
    "IsProgressive": Boolean
}

Where:

  • Version é a versão do protocolo. A versão atual é v2.0.

  • IsProgressive é um sinalizador booliano que indica se esse conjunto de dados contém quadros progressivos. Um quadro progressivo é um dos seguintes:

    Moldura Description
    TableHeader Contém informações gerais sobre a tabela
    TableFragment Contém um fragmento de dados retangular da tabela
    TableProgress Contém o progresso em porcentagem (0-100)
    TableCompletion Indica que esse quadro é o último

    Os quadros acima descrevem uma tabela. Se o IsProgressive sinalizador não for definido como true, todas as tabelas do conjunto serão serializadas usando um único quadro:

  • DataTable: contém todas as informações de que o cliente precisa sobre uma única tabela no conjunto de dados.

TableHeader

As consultas feitas com a opção results_progressive_enabled definida como true podem incluir esse quadro. Seguindo esta tabela, os clientes podem esperar uma sequência de intercalação TableFragment e TableProgress quadros. O quadro final da tabela é TableCompletion.

{
    "TableId": Number,
    "TableKind": string,
    "TableName": string,
    "Columns": Array,
}

Where:

  • TableId é a ID exclusiva da tabela.

  • TableKind é um dos seguintes:

    • PrimaryResult
    • QueryCompletionInformation
    • QueryTraceLog
    • QueryPerfLog
    • TableOfContents
    • QueryProperties
    • QueryPlan
    • Unknown

  • TableName é o nome da tabela.

  • Columns é uma matriz que descreve o esquema da tabela.

{
    "ColumnName": string,
    "ColumnType": string,
}

Os tipos de coluna com suporte são descritos aqui.

TableFragment

O TableFragment quadro contém um fragmento de dados retangulares da tabela. Além dos dados reais, esse quadro também contém uma TableFragmentType propriedade que informa ao cliente o que fazer com o fragmento. O fragmento acrescentado a fragmentos existentes ou substituí-los.

{
    "TableId": Number,
    "FieldCount": Number,
    "TableFragmentType": string,
    "Rows": Array
}

Where:

  • TableId é a ID exclusiva da tabela.

  • FieldCount é o número de colunas na tabela.

  • TableFragmentType descreve o que o cliente deve fazer com esse fragmento. TableFragmentType é um dos seguintes:

    • DataAppend
    • DataReplace

  • Rows é uma matriz bidimensional que contém os dados do fragmento.

TableProgress

O TableProgress quadro pode se intercalar com o TableFragment quadro descrito acima. Sua única finalidade é notificar o cliente sobre o progresso da consulta.

{
    "TableId": Number,
    "TableProgress": Number,
}

Where:

  • TableId é a ID exclusiva da tabela.
  • TableProgress é o progresso em porcentagem (0-100).

TableCompletion

O TableCompletion quadro marca o final da transmissão da tabela. Não serão enviados mais quadros relacionados a essa tabela.

{
    "TableId": Number,
    "RowCount": Number,
}

Where:

  • TableId é a ID exclusiva da tabela.
  • RowCount é o número total de linhas na tabela.

DataTable

As consultas emitidas com o EnableProgressiveQuery sinalizador definido como false não incluirão nenhum dos quadros (TableHeader, TableFragment, TableProgresse TableCompletion). Em vez disso, cada tabela no conjunto de dados será transmitida usando o DataTable quadro que contém todas as informações necessárias ao cliente para ler a tabela.

{
    "TableId": Number,
    "TableKind": string,
    "TableName": string,
    "Columns": Array,
    "Rows": Array,
}

Where:

  • TableId é a ID exclusiva da tabela.

  • TableKind é um dos seguintes:

    • PrimaryResult
    • QueryCompletionInformation
    • QueryTraceLog
    • QueryPerfLog
    • QueryProperties
    • QueryPlan
    • Unknown

  • TableName é o nome da tabela.

  • Columns é uma matriz que descreve o esquema da tabela e inclui:

{
    "ColumnName": string,
    "ColumnType": string,
}
  • Rows é uma matriz bidimensional que contém os dados da tabela.

O significado das tabelas na resposta

  • PrimaryResult - O resultado tabular principal da consulta. Para cada instrução de expressão tabular, uma ou mais tabelas são geradas em ordem, representando os resultados produzidos pela instrução. Pode haver várias dessas tabelas devido a lotes e operadores de bifurcação.
  • QueryCompletionInformation - Fornece informações adicionais sobre a execução da consulta em si, como se ela foi concluída com êxito ou não, e quais foram os recursos consumidos pela consulta (semelhante à tabela QueryStatus na resposta v1).
  • QueryProperties - Fornece valores adicionais, como instruções de visualização do cliente (emitidas, por exemplo, para refletir as informações no operador de renderização) e informações do cursor de banco de dados .
  • QueryTraceLog - As informações de log de rastreamento de desempenho (retornadas quando perftrace as propriedades da solicitação do cliente são definidas como true).

DataSetCompletion

O DataSetCompletion quadro é o último no conjunto de dados.

{
    "HasErrors": Boolean,
    "Cancelled": Boolean,
    "OneApiErrors": Array,
}

Where:

  • HasErrors é true se houver erros ao gerar o conjunto de dados.
  • Cancelled será true se a solicitação que levou à geração do conjunto de dados tiver sido cancelada antes da conclusão.
  • OneApiErrors só será retornado se HasErrors for verdadeiro. Para obter uma descrição do formato, consulte a OneApiErrors seção 7.10.2 aqui.
  • Last updated on