Freigeben über

Abfragen einer V2-HTTP-Antwort

  • Artikel

HTTP-Antwort status Zeile

Wenn die Anforderung erfolgreich ist, lautet 200 OKdie HTTP-Antwort status Code . Der HTTP-Antworttext ist ein JSON-Array, wie unten erläutert.

Wenn die Anforderung fehlschlägt, ist die HTTP-Antwort status Code ein 4xx - oder 5xx -Fehler. Der Grundausdruck enthält zusätzliche Informationen zum Fehler. Der HTTP-Antworttext ist ein JSON-Objekt, wie unten erläutert.

Hinweis

Die Anforderung gibt möglicherweise einen status Code von 200 OKzurück, aber der HTTP-Antworttext weist auf einen Fehler hin. Dies kann der Fall sein, wenn der Fehler ausgelöst wird, nachdem die HTTP-status Zeile bereits zurückgegeben wurde. Es wird erwartet, dass der Leser explizit nach einer solchen Bedingung sucht.

HTTP-Antwortheader

Unabhängig vom Erfolg/Fehler der Anforderung sind zwei benutzerdefinierte HTTP-Header in der Antwort enthalten:

  1. x-ms-client-request-id: Der Dienst gibt eine undurchsichtige Zeichenfolge zurück, die das Anforderungs-Antwort-Paar zu Korrelationszwecken identifiziert. Wenn die Anforderung eine Clientanforderungs-ID enthält, wird ihr Wert hier angezeigt. Andernfalls wird eine zufällige Zeichenfolge zurückgegeben.

  2. x-ms-activity-id: Der Dienst gibt eine undurchsichtige Zeichenfolge zurück, die das Anforderungs-Antwort-Paar zu Korrelationszwecken eindeutig identifiziert. Im Gegensatz zu x-ms-client-request-idist dieser Bezeichner nicht von Informationen in der Anforderung betroffen und pro Antwort eindeutig.

HTTP-Antworttext (bei Anforderungsfehler)

Bei einem Anforderungsfehler ist der HTTP-Antworttext ein JSON-Dokument, das gemäß OneApiErrors Regeln formatiert ist. Eine Beschreibung des OneApiErrors Formats finden Sie hier in Abschnitt 7.10.2. Im Folgenden finden Sie ein Beispiel für einen solchen Fehler.

{
    "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-Antworttext (bei erfolgreicher Anforderung)

Bei erfolgreicher Anforderung ist der HTTP-Antworttext ein JSON-Array, das die Anforderungsergebnisse codiert.

Logischerweise beschreibt die V2-Antwort ein DataSet-Objekt , das eine beliebige Anzahl von Tabellen enthält. Diese Tabellen können die tatsächlichen Daten darstellen, die von der Anforderung angefordert werden, oder zusätzliche Informationen zur Ausführung der Anforderung (z. B. eine Abrechnung der von der Anforderung verbrauchten Ressourcen). Darüber hinaus kann die tatsächliche Anforderung (aufgrund verschiedener Bedingungen) tatsächlich fehlschlagen, obwohl ein 200 OK status zurückgegeben wird. In diesem Fall enthält die Antwort Teilantwortdaten sowie einen Hinweis auf die Fehler.

Physisch ist das JSON-Array des Antworttexts eine Liste von JSON-Objekten, von denen jedes als Frame bezeichnet wird. Das DataSet-Objekt wird in zwei Frames codiert: DataSetHeader und DataSetCompletion. Der erste ist immer der erste Frame, und der zweite ist immer der letzte Frame. In "dazwischen" finden Sie die Frames, die die Table-Objekte beschreiben.

Die Table-Objekte können auf zwei Arten codiert werden:

  1. Als einzelner Frame: DataTable. Dies ist die Standardoption.

  2. Alternativ als "Mischung" aus vier Frames: TableHeader (der zuerst kommt und die Tabelle beschreibt), TableFragment (beschreibt die Daten einer Tabelle), TableProgress (ist optional und bietet eine Schätzung, wie weit wir in den Daten der Tabelle sind) und TableCompletion (das ist der letzte Frame der Tabelle).

Der zweite Fall wird als "progressiver Modus" bezeichnet und wird nur angezeigt, wenn die Clientanforderungseigenschaft results_progressive_enabled auf truefestgelegt ist. In diesem Fall beschreibt jeder TableFragment-Frame eine Aktualisierung der Daten, die von allen vorherigen Frames für die Tabelle gesammelt wurden, entweder als Anfügevorgang oder als Ersetzungsvorgang. (Letzteres wird beispielsweise verwendet, wenn eine lange Aggregationsberechnung auf der "obersten Ebene" der Abfrage ausgeführt wird, sodass ein anfängliches Aggregationsergebnis später durch genauere Ergebnisse ersetzt wird.)

DataSetHeader

Der DataSetHeader Frame ist immer der erste im Dataset und wird genau einmal angezeigt.

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

Hierbei gilt:

  • Version ist die Protokollversion. Die aktuelle Version ist v2.0.

  • IsProgressive ist ein boolesches Flag, das angibt, ob dieses Dataset progressive Frames enthält. Ein progressiver Frame ist einer der folgenden:

    Frame BESCHREIBUNG
    TableHeader Enthält allgemeine Informationen zur Tabelle.
    TableFragment Enthält einen rechteckigen Datenshard der Tabelle.
    TableProgress Enthält den Fortschritt in Prozent (0-100)
    TableCompletion Gibt an, dass es sich bei diesem Frame um den letzten Frame handelt.

    Die obigen Frames beschreiben eine Tabelle. Wenn das IsProgressive Flag nicht auf true festgelegt ist, wird jede Tabelle in der Gruppe mit einem einzelnen Frame serialisiert:

  • DataTable: Enthält alle Informationen, die der Client zu einer einzelnen Tabelle im Dataset benötigt.

TableHeader

Abfragen, die mit der results_progressive_enabled auf true festgelegten Option durchgeführt werden, können diesen Frame enthalten. Nach dieser Tabelle können Clients eine ineinandergreifende Sequenz von TableFragment - und TableProgress -Frames erwarten. Der letzte Rahmen der Tabelle ist TableCompletion.

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

Hierbei gilt:

  • TableId ist die eindeutige ID der Tabelle.

  • TableKind ist einer dieser Werte:

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

  • TableName ist der Name der Tabelle.

  • Columns ist ein Array, das das Schema der Tabelle beschreibt.

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

Unterstützte Spaltentypen werden hier beschrieben.

TableFragment

Der TableFragment Rahmen enthält ein rechteckiges Datenfragment der Tabelle. Zusätzlich zu den tatsächlichen Daten enthält dieser Frame auch eine TableFragmentType Eigenschaft, die dem Client mitteilt, was mit dem Fragment zu tun ist. Das Fragment, das an vorhandene Fragmente angefügt oder ersetzt wird.

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

Hierbei gilt:

  • TableId ist die eindeutige ID der Tabelle.

  • FieldCount ist die Anzahl der Spalten in der Tabelle.

  • TableFragmentType beschreibt, was der Client mit diesem Fragment tun sollte. TableFragmentType ist einer dieser Werte:

    • DataAppend
    • DataReplace

  • Rows ist ein zweidimensionales Array, das die Fragmentdaten enthält.

TableProgress

Der TableProgress Frame kann sich mit dem TableFragment oben beschriebenen Frame verzahnen. Der einzige Zweck besteht darin, den Client über den Fortschritt der Abfrage zu informieren.

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

Hierbei gilt:

  • TableId ist die eindeutige ID der Tabelle.
  • TableProgress ist der Fortschritt in Prozent (0--100).

TableCompletion

Der TableCompletion Frame markiert das Ende der Tabellenübertragung. Es werden keine weiteren Frames im Zusammenhang mit dieser Tabelle gesendet.

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

Hierbei gilt:

  • TableId ist die eindeutige ID der Tabelle.
  • RowCount ist die Gesamtanzahl der Zeilen in der Tabelle.

DataTable

Abfragen, die mit dem EnableProgressiveQuery auf false festgelegten Flag ausgegeben werden, enthalten keine der Frames (TableHeader, , TableFragmentTableProgressund TableCompletion). Stattdessen wird jede Tabelle im Dataset mithilfe des Frames übertragen, der DataTable alle Informationen enthält, die der Client zum Lesen der Tabelle benötigt.

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

Hierbei gilt:

  • TableId ist die eindeutige ID der Tabelle.

  • TableKind ist einer dieser Werte:

    • PrimaryResult
    • QueryCompletionInformation
    • QueryTraceLog
    • QueryPerfLog
    • QueryProperties
    • QueryPlan
    • Unbekannt

  • TableName ist der Name der Tabelle.

  • Columns ist ein Array, das das Schema der Tabelle beschreibt, und umfasst Folgendes:

{
    "ColumnName": string,
    "ColumnType": string,
}
  • Rows ist ein zweidimensionales Array, das die Daten der Tabelle enthält.

Die Bedeutung von Tabellen in der Antwort

  • PrimaryResult– Das Standard tabellenbasiertes Ergebnis der Abfrage. Für jede tabellenbasierte Ausdrucksanweisung werden eine oder mehrere Tabellen in der Reihenfolge generiert, die die von der -Anweisung erzeugten Ergebnisse darstellen. Aufgrund von Batches und Fork-Operatoren können mehrere solche Tabellen vorhanden sein.
  • QueryCompletionInformation – Stellt zusätzliche Informationen zur Ausführung der Abfrage selbst bereit, z. B. ob sie erfolgreich abgeschlossen wurde oder nicht, und welche Ressourcen von der Abfrage genutzt wurden (ähnlich der QueryStatus-Tabelle in der v1-Antwort).
  • QueryProperties – Stellt zusätzliche Werte bereit, z. B. Clientvisualisierungsanweisungen (ausgegeben, um die Informationen im Renderoperator widerzuspiegeln) und Datenbankcursorinformationen .
  • QueryTraceLog – Die Leistungsablaufverfolgungsprotokollinformationen (zurückgegeben, wenn perftrace in Clientanforderungseigenschaften auf true festgelegt sind).

DataSetCompletion

Der DataSetCompletion Frame ist der letzte im Dataset.

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

Hierbei gilt:

  • HasErrors ist true, wenn beim Generieren des Datasets Fehler aufgetreten sind.
  • Cancelled ist true, wenn die Anforderung, die zur Generierung des Datasets geführt hat, vor Abschluss abgebrochen wurde.
  • OneApiErrors wird nur zurückgegeben, wenn HasErrors true ist. Eine Beschreibung des OneApiErrors Formats finden Sie hier in Abschnitt 7.10.2.