Odpověď HTTP dotazu v2

Přepněte služby pomocí rozevíracího seznamu Verze . Přečtěte si další informace o navigaci.
Platí pro: ✅ Microsoft Fabric ✅ Azure Data Explorer

Stavový řádek odpovědi HTTP

Pokud požadavek proběhne úspěšně, stavový kód odpovědi HTTP je 200 OK. Text odpovědi HTTP je pole JSON, jak je vysvětleno níže.

Pokud požadavek selže, stavový kód odpovědi HTTP je nebo 4xx dojde k 5xx chybě. Fráze důvodu bude obsahovat další informace o selhání. Tělo odpovědi HTTP je objekt JSON, jak je vysvětleno níže.

Poznámka:

Požadavek může vrátit stavový 200 OKkód , ale text odpovědi HTTP bude indikovat chybu. K tomu může dojít, když se chyba vyvolá po vrácení stavového řádku HTTP. Očekává se, že čtenář explicitně zkontroluje takovou podmínku.

Hlavičky odpovědi HTTP

Bez ohledu na úspěch/selhání požadavku jsou součástí odpovědi dvě vlastní hlavičky HTTP:

x-ms-client-request-id: Služba vrátí neprůhlený řetězec, který identifikuje dvojici požadavků a odpovědí pro účely korelace. Pokud požadavek obsahoval ID požadavku klienta, zobrazí se zde jeho hodnota; v opačném případě se vrátí nějaký náhodný řetězec.
x-ms-activity-id: Služba vrátí neprůhlený řetězec, který jednoznačně identifikuje dvojici požadavků a odpovědí pro účely korelace. Na rozdíl od x-ms-client-request-idtohoto identifikátoru nejsou ovlivněny žádné informace v požadavku a jsou jedinečné pro každou odpověď.

Text odpovědi HTTP (při selhání požadavku)

V případě selhání požadavku bude text odpovědi HTTP dokument JSON formátovaný podle OneApiErrors pravidel. OneApiErrors Popis formátu najdete v části 7.10.2 zde. Níže je příklad takového selhání.

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

Text odpovědi HTTP (při úspěchu požadavku)

Při úspěchu požadavku bude text odpovědi HTTP pole JSON, které zakóduje výsledky požadavku.

Odpověď V2 logicky popisuje objekt DataSet , který obsahuje libovolný počet tabulek. Tyto tabulky mohou představovat skutečná data, o která žádost žádá, nebo další informace o provedení požadavku (například účet prostředků spotřebovaných žádostí). Kromě toho může skutečná žádost ve skutečnosti selhat (z důvodu různých podmínek), i když 200 OK se vrátí stav, a v takovém případě odpověď bude obsahovat částečná data odpovědi a indikaci chyb.

Fyzicky je pole JSON těla odpovědi seznam objektů JSON, z nichž každý se nazývá rámec. Objekt DataSet je kódován do dvou snímků: DataSetHeader a DataSetCompletion. První je vždy první rámec a druhý je vždy posledním snímkem. Mezi nimi lze najít rámce popisující objekty Table.

Objekty Table lze kódovat dvěma způsoby:

Jako jeden rámec: DataTable. Toto je výchozí hodnota.
Alternativně jako "mix" čtyř typů rámců: TableHeader (který je první a popisuje tabulku), TableFragment (který popisuje data tabulky), TableProgress (což je nepovinný a poskytuje odhad toho, jak daleko v datech tabulky jsme) a TableCompletion (což je poslední rámec tabulky).

Druhý případ se nazývá "progresivní režim" a zobrazí se pouze v případě, že je vlastnost results_progressive_enabled požadavku klienta nastavena na true. V tomto případě každý rámec TableFragment popisuje aktualizaci dat shromážděných všemi předchozími jednotlivými snímky tabulky, buď jako operaci připojení, nebo jako operaci nahrazení. (Druhá možnost se používá například v případě, že se na nejvyšší úrovni dotazu provede nějaký dlouhotrvající výpočet agregace, takže počáteční výsledek agregace se později nahradí přesnějšími výsledky.)

DataSetHeader

Rámec DataSetHeader je vždy první v datové sadě a zobrazí se přesně jednou.

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

Where:

Version je verze protokolu. Aktuální verze je v2.0.

IsProgressive je logický příznak, který označuje, jestli tato datová sada obsahuje progresivní rámce. Progresivní rámec je jedním z těchto:

Rámec	Description
`TableHeader`	Obsahuje obecné informace o tabulce.
`TableFragment`	Obsahuje obdélníkové datové horizontální oddíly tabulky.
`TableProgress`	Obsahuje průběh v procentech (0–100).
`TableCompletion`	Označuje, že tento rámec je posledním rámcem.

Výše uvedené rámce popisují tabulku. IsProgressive Pokud příznak není nastavený na hodnotu true, bude každá tabulka v sadě serializována pomocí jednoho rámce:

DataTable: Obsahuje všechny informace, které klient potřebuje o jedné tabulce v datové sadě.

TableHeader

Dotazy, které jsou provedeny s možností nastavenou results_progressive_enabled na true, mohou zahrnovat tento rámec. Po této tabulce mohou klienti očekávat prokládání posloupnosti TableFragment a TableProgress rámců. Poslední rámec tabulky je TableCompletion.

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

Where:

TableId je jedinečné ID tabulky.
TableKind je jedna z těchto možností:
- PrimaryResult
- QueryCompletionInformation
- QueryTraceLog
- QueryPerfLog
- TableOfContents
- QueryProperties
- QueryPlan
- Neznámý
TableName je název tabulky.
Columns je pole popisující schéma tabulky.

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

Podporované typy sloupců jsou popsané tady.

TableFragment

Rámec TableFragment obsahuje obdélníkový datový fragment tabulky. Kromě skutečných dat obsahuje tento rámec také TableFragmentType vlastnost, která klientovi řekne, co má s fragmentem dělat. Fragment připojený k existujícím fragmentům nebo je nahraďte.

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

Where:

TableId je jedinečné ID tabulky.
FieldCount je počet sloupců v tabulce.
TableFragmentType popisuje, co má klient s tímto fragmentem dělat. TableFragmentType je jedna z těchto možností:
- DataAppend
- DataReplace
Rows je dvojrozměrné pole, které obsahuje data fragmentu.

TableProgress

TableProgress Rámeček se může prokládání s rámečkem TableFragment popsaným výše. Jediným účelem je informovat klienta o průběhu dotazu.

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

Where:

TableId je jedinečné ID tabulky.
TableProgress je průběh v procentech (0–-100).

TableCompletion

Rám TableCompletion označuje konec přenosu tabulky. Nebudou odeslány žádné další rámce související s danou tabulkou.

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

Where:

TableId je jedinečné ID tabulky.
RowCount je celkový počet řádků v tabulce.

Datová tabulka

Dotazy vydané s příznakem EnableProgressiveQuery nastaveným na false nebudou obsahovat žádné snímky (TableHeader, TableFragment, TableProgress, a TableCompletion). Místo toho se každá tabulka v datové sadě přenese pomocí DataTable rámce, který obsahuje všechny informace, které klient potřebuje, ke čtení tabulky.

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

Where:

TableId je jedinečné ID tabulky.
TableKind je jedna z těchto možností:
- PrimaryResult
- QueryCompletionInformation
- QueryTraceLog
- QueryPerfLog
- QueryProperties
- QueryPlan
- Neznámý
TableName je název tabulky.
Columns je pole popisující schéma tabulky a zahrnuje:

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

Rows je dvojrozměrné pole, které obsahuje data tabulky.

Význam tabulek v odpovědi

PrimaryResult – Hlavní tabulkový výsledek dotazu. Pro každý příkaz tabulkového výrazu se vygeneruje jedna nebo více tabulek v pořadí, které představují výsledky vytvořené příkazem. Kvůli dávkám a forkům může existovat více takových tabulek.
QueryCompletionInformation – Poskytuje další informace o provádění samotného dotazu, například o tom, jestli byl úspěšně dokončen nebo ne, a o tom, jaké prostředky dotaz spotřeboval (podobně jako tabulka QueryStatus v odpovědi v1).
QueryProperties – Poskytuje další hodnoty, jako jsou pokyny pro vizualizaci klienta (vygenerované například tak, aby odrážely informace v operátoru vykreslování) a informace o kurzoru databáze .
QueryTraceLog – Informace protokolu trasování výkonu (vrácené ve perftracevlastnostech požadavku klienta jsou nastaveny na hodnotu true).

DataSetCompletion

Rámec DataSetCompletion je posledním rámcem v datové sadě.

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

Where:

HasErrors je true, pokud při generování datové sady došlo k chybám.
Cancelled je true, pokud požadavek, který vedl ke generování datové sady, byl zrušen před dokončením.
OneApiErrors je vrácena pouze v případě, že HasErrors je true. OneApiErrors Popis formátu najdete v části 7.10.2 zde.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-02-05

Odpověď HTTP dotazu v2

Stavový řádek odpovědi HTTP

Hlavičky odpovědi HTTP

Text odpovědi HTTP (při selhání požadavku)

Text odpovědi HTTP (při úspěchu požadavku)

DataSetHeader

TableHeader

TableFragment

TableProgress

TableCompletion

Datová tabulka

Význam tabulek v odpovědi

DataSetCompletion

Váš názor

Další materiály