Delen via

QUERY V2 HTTP-antwoord

  • Artikel

Http-antwoordstatusregel

Als de aanvraag slaagt, is 200 OKde http-antwoordstatuscode . De hoofdtekst van het HTTP-antwoord is een JSON-matrix, zoals hieronder wordt uitgelegd.

Als de aanvraag mislukt, is de statuscode van het HTTP-antwoord een 4xx of-fout 5xx . De redenzin bevat aanvullende informatie over de fout. De hoofdtekst van het HTTP-antwoord is een JSON-object, zoals hieronder wordt uitgelegd.

Notitie

De aanvraag retourneert mogelijk een statuscode van , maar de hoofdtekst van 200 OKhet HTTP-antwoord geeft een fout aan. Dit kan gebeuren wanneer de fout optreedt nadat de HTTP-statusregel al is geretourneerd. Van de lezer wordt verwacht dat hij expliciet controleert op een dergelijke voorwaarde.

HTTP-antwoordheaders

Ongeacht of de aanvraag is geslaagd of mislukt, worden er twee aangepaste HTTP-headers opgenomen in het antwoord:

  1. x-ms-client-request-id: de service retourneert een ondoorzichtige tekenreeks die het aanvraag-/antwoordpaar identificeert voor correlatiedoeleinden. Als de aanvraag een clientaanvraag-id bevat, wordt de waarde hier weergegeven; Anders wordt een willekeurige tekenreeks geretourneerd.

  2. x-ms-activity-id: de service retourneert een ondoorzichtige tekenreeks die het aanvraag-/antwoordpaar uniek identificeert voor correlatiedoeleinden. In tegenstelling tot x-ms-client-request-id, wordt deze id niet beïnvloed door informatie in de aanvraag en is deze uniek per antwoord.

HTTP-antwoordtekst (fout bij aanvraag)

Als de aanvraag mislukt, is de hoofdtekst van het HTTP-antwoord een JSON-document dat is opgemaakt volgens OneApiErrors regels. Zie sectie 7.10.2 voor een beschrijving van de OneApiErrors indeling. Hieronder ziet u een voorbeeld van een dergelijke fout.

{
    "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'"
        }
    }
}

HTTP-antwoordtekst (op aanvraag geslaagd)

Als de aanvraag is geslaagd, is de hoofdtekst van het HTTP-antwoord een JSON-matrix die de aanvraagresultaten codeert.

Logischerwijs beschrijft het V2-antwoord een DataSet-object dat een willekeurig aantal tabellen bevat. Deze tabellen kunnen de werkelijke gegevens vertegenwoordigen die door de aanvraag zijn aangevraagd, of aanvullende informatie over de uitvoering van de aanvraag (zoals een boekhouding van de resources die door de aanvraag worden gebruikt). Bovendien kan de werkelijke aanvraag daadwerkelijk mislukken (vanwege verschillende omstandigheden), zelfs als er een 200 OK status wordt geretourneerd. In dat geval bevat het antwoord gedeeltelijke antwoordgegevens plus een indicatie van de fouten.

Fysiek is de JSON-matrix van de antwoordtekst een lijst met JSON-objecten, die elk een frame worden genoemd. Het DataSet-object is gecodeerd in twee frames: DataSetHeader en DataSetCompletion. Het eerste is altijd het eerste frame en het tweede is altijd het laatste frame. Daartussen vindt u de frames die de Tabelobjecten beschrijven.

De tabelobjecten kunnen op twee manieren worden gecodeerd:

  1. Als één frame: Gegevenstabel. Dit is de standaardinstelling.

  2. Als een 'mix' van vier soorten frames: TableHeader (die als eerste komt en de tabel beschrijft), TableFragment (waarmee de gegevens van een tabel worden beschreven), TableProgress (wat optioneel is en een schatting geeft van hoe ver we in de gegevens van de tabel staan) en TableCompletion (het laatste frame van de tabel).

De tweede case wordt 'progressieve modus' genoemd en wordt alleen weergegeven als de clientaanvraageigenschap results_progressive_enabled is ingesteld op true. In dit geval beschrijft elk TableFragment-frame een update van de gegevens die zijn verzameld door alle voorgaande dergelijke frames voor de tabel, als een toevoegbewerking of als een vervangingsbewerking. (Dit laatste wordt bijvoorbeeld gebruikt wanneer een langlopende aggregatieberekening wordt uitgevoerd op het 'hoogste niveau' van de query, zodat een eerste aggregatieresultaat later wordt vervangen door nauwkeurigere resultaten.)

DataSetHeader

Het DataSetHeader frame is altijd het eerste in de gegevensset en wordt precies één keer weergegeven.

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

Waar:

  • Version is de protocolversie. De huidige versie is v2.0.

  • IsProgressive is een booleaanse vlag die aangeeft of deze gegevensset progressieve frames bevat. Een progressief frame is een van de volgende:

    Frame Description
    TableHeader Bevat algemene informatie over de tabel
    TableFragment Bevat een rechthoekige gegevensshard van de tabel
    TableProgress Bevat de voortgang in procenten (0-100)
    TableCompletion Geeft aan dat dit frame het laatste frame is

    In de bovenstaande frames wordt een tabel beschreven. Als de IsProgressive vlag niet is ingesteld op true, wordt elke tabel in de set geserialiseerd met behulp van één frame:

  • DataTable: bevat alle informatie die de client nodig heeft over één tabel in de gegevensset.

TableHeader

Query's die zijn gemaakt met de results_progressive_enabled optie ingesteld op true, kunnen dit frame bevatten. Na deze tabel kunnen clients een opeenvolging van TableFragment en TableProgress frames verwachten. Het laatste frame van de tabel is TableCompletion.

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

Waar:

  • TableId is de unieke id van de tabel.

  • TableKind heeft een van de volgende waarden:

    • PrimaryResult
    • QueryCompletionInformation
    • QueryTraceLog
    • QueryPerfLog
    • Tableofcontents
    • QueryEigenschappen
    • QueryPlan
    • Onbekend

  • TableName is de naam van de tabel.

  • Columns is een matrix die het schema van de tabel beschrijft.

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

Ondersteunde kolomtypen worden hier beschreven.

TableFragment

Het TableFragment frame bevat een rechthoekig gegevensfragment van de tabel. Naast de werkelijke gegevens bevat dit frame ook een TableFragmentType eigenschap die de client vertelt wat er met het fragment moet worden uitgevoerd. Het fragment dat aan bestaande fragmenten wordt toegevoegd of vervangen.

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

Waar:

  • TableId is de unieke id van de tabel.

  • FieldCount is het aantal kolommen in de tabel.

  • TableFragmentType beschrijft wat de client moet doen met dit fragment. TableFragmentType heeft een van de volgende waarden:

    • DataAppend
    • DataReplace

  • Rows is een tweedimensionale matrix die de fragmentgegevens bevat.

TableProgress

Het TableProgress frame kan worden gekoppeld aan het TableFragment hierboven beschreven frame. Het enige doel is om de client op de hoogte te stellen van de voortgang van de query.

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

Waar:

  • TableId is de unieke id van de tabel.
  • TableProgress is de voortgang in procent (0-100).

TableCompletion

Het TableCompletion frame markeert het einde van de tabeloverdracht. Er worden geen frames meer verzonden die betrekking hebben op die tabel.

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

Waar:

  • TableId is de unieke id van de tabel.
  • RowCount is het totale aantal rijen in de tabel.

Datatable

Query's die worden uitgegeven met de EnableProgressiveQuery vlag die is ingesteld op onwaar, bevatten geen frames (TableHeader, TableFragment, TableProgressen TableCompletion). In plaats daarvan wordt elke tabel in de gegevensset verzonden met behulp van het DataTable frame dat alle informatie bevat die de client nodig heeft om de tabel te lezen.

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

Waar:

  • TableId is de unieke id van de tabel.

  • TableKind heeft een van de volgende waarden:

    • PrimaryResult
    • QueryCompletionInformation
    • QueryTraceLog
    • QueryPerfLog
    • QueryEigenschappen
    • QueryPlan
    • Onbekend

  • TableName is de naam van de tabel.

  • Columns is een matrix die het schema van de tabel beschrijft en bevat:

{
    "ColumnName": string,
    "ColumnType": string,
}
  • Rows is een tweedimensionale matrix die de gegevens van de tabel bevat.

De betekenis van tabellen in het antwoord

  • PrimaryResult - Het belangrijkste tabellaire resultaat van de query. Voor elke tabellaire expressie-instructie worden een of meer tabellen op volgorde gegenereerd, die de resultaten vertegenwoordigen die door de instructie worden geproduceerd. Er kunnen meerdere dergelijke tabellen zijn vanwege batches en vorkoperators.
  • QueryCompletionInformation - Biedt aanvullende informatie over de uitvoering van de query zelf, zoals of deze is voltooid of niet, en wat de resources waren die door de query werden verbruikt (vergelijkbaar met de tabel QueryStatus in het v1-antwoord).
  • QueryProperties - Biedt aanvullende waarden, zoals instructies voor clientvisualisatie (verzonden, bijvoorbeeld om de informatie in de renderoperator weer te geven) en informatie over de databasecursor .
  • QueryTraceLog - De gegevens van het prestatietraceringslogboek (die worden geretourneerd wanneer perftrace de eigenschappen van de clientaanvraag worden weergegeven, zijn ingesteld op true).

DataSetCompletion

Het DataSetCompletion frame is het laatste frame in de gegevensset.

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

Waar:

  • HasErrors is waar als er fouten zijn opgetreden tijdens het genereren van de gegevensset.
  • Cancelled is waar als de aanvraag die tot het genereren van de gegevensset heeft geleid, is geannuleerd voordat deze is voltooid.
  • OneApiErrors wordt alleen geretourneerd als HasErrors waar is. Zie sectie 7.10.2 voor een beschrijving van de OneApiErrors indeling.