Condividi tramite

Eseguire query sulla risposta HTTP V2

Cambiare i servizi usando l'elenco a discesa Version .Switch services using the Version drop-down list. Altre informazioni sulla navigazione.
Si applica a: ✅ Esplora dati di Azure in Microsoft Fabric ✅

Riga di stato della risposta HTTP

Se la richiesta ha esito positivo, il codice di stato della risposta HTTP è 200 OK. Il corpo della risposta HTTP è una matrice JSON, come illustrato di seguito.

Se la richiesta ha esito negativo, il codice di stato della risposta HTTP è un 4xx errore o 5xx . La frase motivo includerà informazioni aggiuntive sull'errore. Il corpo della risposta HTTP è un oggetto JSON, come illustrato di seguito.

Annotazioni

La richiesta può restituire un codice di stato di 200 OK, ma il corpo della risposta HTTP indicherà un errore. Questo problema può verificarsi quando l'errore viene generato dopo che la riga di stato HTTP è già stata restituita. È previsto che il lettore verifichi in modo esplicito la presenza di tale condizione.

Intestazioni di risposta HTTP

Indipendentemente dall'esito positivo/negativo della richiesta, con la risposta vengono incluse due intestazioni HTTP personalizzate:

  1. x-ms-client-request-id: il servizio restituisce una stringa opaca che identifica la coppia richiesta/risposta a scopo di correlazione. Se la richiesta includeva un ID richiesta client, il relativo valore verrà visualizzato qui; in caso contrario, viene restituita una stringa casuale.

  2. x-ms-activity-id: il servizio restituisce una stringa opaca che identifica in modo univoco la coppia richiesta/risposta a scopo di correlazione. A differenza di x-ms-client-request-id, questo identificatore non è interessato da alcuna informazione nella richiesta ed è univoco per risposta.

Corpo della risposta HTTP (in caso di errore della richiesta)

In caso di errore della richiesta, il corpo della risposta HTTP sarà un documento JSON formattato in base alle OneApiErrors regole. Per una descrizione del OneApiErrors formato, vedere la sezione 7.10.2 qui. Di seguito è riportato un esempio di errore di questo tipo.

{
    "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 della risposta HTTP (in caso di esito positivo della richiesta)

In caso di esito positivo della richiesta, il corpo della risposta HTTP sarà una matrice JSON che codifica i risultati della richiesta.

Logicamente, la risposta V2 descrive un oggetto DataSet che contiene un numero qualsiasi di tabelle. Queste tabelle possono rappresentare i dati effettivi richiesti dalla richiesta o informazioni aggiuntive sull'esecuzione della richiesta, ad esempio una contabilità delle risorse utilizzate dalla richiesta. Inoltre, la richiesta effettiva potrebbe effettivamente non riuscire (a causa di varie condizioni) anche se viene restituito uno 200 OK stato e in tal caso la risposta includerà dati di risposta parziali più un'indicazione degli errori.

Fisicamente, la matrice JSON del corpo della risposta è un elenco di oggetti JSON, ognuno dei quali è denominato frame. L'oggetto DataSet viene codificato in due frame: DataSetHeader e DataSetCompletion. Il primo è sempre il primo fotogramma e il secondo è sempre l'ultimo fotogramma. In "between" è possibile trovare i fotogrammi che descrivono gli oggetti Table.

Gli oggetti Table possono essere codificati in due modi:

  1. Come singolo frame: DataTable. Si tratta dell'impostazione predefinita.

  2. In alternativa, come "combinazione" di quattro tipi di frame: TableHeader (che viene prima e descrive la tabella), TableFragment (che descrive i dati di una tabella), TableProgress (facoltativo e fornisce una stima sulla distanza dei dati della tabella) e TableCompletion (che è l'ultimo frame della tabella).

Il secondo caso viene chiamato "modalità progressiva" e viene visualizzato solo se la proprietà results_progressive_enabled della richiesta client è impostata su true. In questo caso, ogni frame TableFragment descrive un aggiornamento dei dati accumulati da tutti i frame precedenti per la tabella, come operazione di accodamento o come operazione di sostituzione. Quest'ultimo viene usato, ad esempio, quando viene eseguito un calcolo di aggregazione a esecuzione prolungata al "livello superiore" della query, quindi un risultato di aggregazione iniziale viene sostituito da risultati più accurati in un secondo momento.

DataSetHeader

Il DataSetHeader frame è sempre il primo nel set di dati e viene visualizzato esattamente una volta.

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

Where:

  • Version è la versione del protocollo. La versione corrente è v2.0.

  • IsProgressive è un flag booleano che indica se questo set di dati contiene frame progressivi. Un frame progressivo è uno dei seguenti:

    Cornice Description
    TableHeader Contiene informazioni generali sulla tabella
    TableFragment Contiene una partizione di dati rettangolare della tabella
    TableProgress Contiene lo stato di avanzamento in percentuale (0-100)
    TableCompletion Indica che questo frame è l'ultimo

    I frame precedenti descrivono una tabella. Se il IsProgressive flag non è impostato su true, ogni tabella del set verrà serializzata usando un singolo frame:

  • DataTable: contiene tutte le informazioni necessarie al client relative a una singola tabella nel set di dati.

TableHeader

Le query eseguite con l'opzione results_progressive_enabled impostata su true possono includere questo frame. Seguendo questa tabella, i client possono prevedere una sequenza di interleaving di TableFragment e TableProgress frame. Il frame finale della tabella è TableCompletion.

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

Where:

  • TableId è l'ID univoco della tabella.

  • TableKind è uno dei seguenti:

    • PrimaryResult
    • QueryCompletionInformation
    • QueryTraceLog
    • QueryPerfLog
    • TableOfContents
    • Proprietà query
    • QueryPlan
    • Sconosciuto

  • TableName è il nome della tabella.

  • Columns è una matrice che descrive lo schema della tabella.

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

I tipi di colonna supportati sono descritti qui.

TableFragment

La TableFragment cornice contiene un frammento di dati rettangolare della tabella. Oltre ai dati effettivi, questo frame contiene anche una TableFragmentType proprietà che indica al client cosa fare con il frammento. Frammento accodato a frammenti esistenti o sostituirli.

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

Where:

  • TableId è l'ID univoco della tabella.

  • FieldCount è il numero di colonne nella tabella.

  • TableFragmentType descrive le operazioni che il client deve eseguire con questo frammento. TableFragmentType è uno dei seguenti:

    • DataAppend
    • DataReplace

  • Rows è una matrice bidimensionale che contiene i dati del frammento.

TableProgress

Il TableProgress fotogramma può interleaversi con la TableFragment cornice descritta in precedenza. L'unico scopo è notificare al client lo stato di avanzamento della query.

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

Where:

  • TableId è l'ID univoco della tabella.
  • TableProgress è lo stato di avanzamento in percentuale (0-100).

TableCompletion

La TableCompletion cornice contrassegna la fine della trasmissione della tabella. Non verranno inviati altri frame correlati a tale tabella.

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

Where:

  • TableId è l'ID univoco della tabella.
  • RowCount è il numero totale di righe nella tabella.

DataTable

Le query eseguite con il EnableProgressiveQuery flag impostato su false non includeranno alcun frame (TableHeader, TableFragment, TableProgresse TableCompletion). Ogni tabella del set di dati verrà invece trasmessa usando il DataTable frame che contiene tutte le informazioni necessarie al client per leggere la tabella.

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

Where:

  • TableId è l'ID univoco della tabella.

  • TableKind è uno dei seguenti:

    • PrimaryResult
    • QueryCompletionInformation
    • QueryTraceLog
    • QueryPerfLog
    • Proprietà query
    • QueryPlan
    • Sconosciuto

  • TableName è il nome della tabella.

  • Columns è una matrice che descrive lo schema della tabella e include:

{
    "ColumnName": string,
    "ColumnType": string,
}
  • Rows è una matrice bidimensionale che contiene i dati della tabella.

Significato delle tabelle nella risposta

  • PrimaryResult - Risultato tabulare principale della query. Per ogni istruzione di espressione tabulare, vengono generate una o più tabelle in ordine, che rappresentano i risultati generati dall'istruzione . Possono essere presenti più tabelle a causa di batch e operatori fork.
  • QueryCompletionInformation - Fornisce informazioni aggiuntive sull'esecuzione della query stessa, ad esempio se è stata completata correttamente o meno, e sulle risorse utilizzate dalla query (analogamente alla tabella QueryStatus nella risposta v1).
  • QueryProperties - Fornisce valori aggiuntivi, ad esempio le istruzioni di visualizzazione client (generate, ad esempio, per riflettere le informazioni nell'operatore di rendering) e le informazioni sul cursore del database .
  • QueryTraceLog - Informazioni sul log di traccia delle prestazioni (restituite quando perftrace nelle proprietà della richiesta client è impostato su true).

DataSetCompletion

Il DataSetCompletion frame è l'ultimo nel set di dati.

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

Where:

  • HasErrors è true se si sono verificati errori durante la generazione del set di dati.
  • Cancelled è true se la richiesta che ha portato alla generazione del set di dati è stata annullata prima del completamento.
  • OneApiErrors viene restituito solo se HasErrors è true. Per una descrizione del OneApiErrors formato, vedere la sezione 7.10.2 qui.
  • Last updated on