QUERY V2 HTTP-antwoord
Http-antwoordstatusregel
Als de aanvraag slaagt, is 200 OK
de 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 OK
het 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:
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.x-ms-activity-id
: de service retourneert een ondoorzichtige tekenreeks die het aanvraag-/antwoordpaar uniek identificeert voor correlatiedoeleinden. In tegenstelling totx-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:
Als één frame: Gegevenstabel. Dit is de standaardinstelling.
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 isv2.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
, TableProgress
en 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 wanneerperftrace
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 alsHasErrors
waar is. Zie sectie 7.10.2 voor een beschrijving van deOneApiErrors
indeling.
Feedback
https://aka.ms/ContentUserFeedback.
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie:Feedback verzenden en weergeven voor