Segnalazione dello stato di inserimento di Kusto.Ingest

  • Articolo

Questo articolo illustra come usare le funzionalità IKustoQueuedIngestClient per tenere traccia dello stato di una richiesta di inserimento.

Classi di descrizione

Queste classi di descrizione contengono dettagli importanti sui dati di origine da inserire e devono essere usati nell'operazione di inserimento.

  • SourceDescription
  • DataReaderDescription
  • StreamDescription
  • FileDescription
  • BLOBDescription

Le classi sono tutte derivate dalla classe SourceDescriptionastratta e vengono usate per creare un'istanza di un identificatore univoco per ogni origine dati. Ogni identificatore verrà quindi usato per il rilevamento dello stato e verrà visualizzato in tutti i report, le tracce e le eccezioni correlate all'operazione pertinente.

Classe SourceDescription

I set di dati di grandi dimensioni verranno suddivisi in blocchi da 1 GB e ogni parte verrà inserita separatamente. Lo stesso SourceId verrà quindi applicato a tutte le operazioni di inserimento originati dallo stesso set di dati.

public abstract class SourceDescription
{
    public Guid? SourceId { get; set; }
}

Classe DataReaderDescription

public class DataReaderDescription : SourceDescription
{
    public  IDataReader DataReader { get; set; }
}

Classe StreamDescription

public class StreamDescription : SourceDescription
{
    public Stream Stream { get; set; }
}

Classe FileDescription

public class FileDescription : SourceDescription
{
    public string FilePath { get; set; }
}

Classe BLOBDescription

public class BlobDescription : SourceDescription
{
    public string BlobUri { get; set; }
    // Setting the Blob size here is important, as this saves the client the trouble of probing the blob for size
    public long? BlobSize { get; set; }
}

Rappresentazione dei risultati di inserimento

Interfaccia IKustoIngestionResult

Questa interfaccia acquisisce il risultato di un'operazione di inserimento in coda singola e può essere recuperata da SourceId.

public interface IKustoIngestionResult
{
    // Retrieves the detailed ingestion status of the ingestion source with the given sourceId.
    IngestionStatus GetIngestionStatusBySourceId(Guid sourceId);

    // Retrieves the detailed ingestion status of all data ingestion operations into Kusto associated with this IKustoIngestionResult instance.
    IEnumerable<IngestionStatus> GetIngestionStatusCollection();
}

Classe InserimentoStatus

InserimentoStatus contiene uno stato completo di un'operazione di inserimento singola.

public class IngestionStatus
{
    // The ingestion status returns from the service. Status remains 'Pending' during the ingestion process and
    // is updated by the service once the ingestion completes. When <see cref="IngestionReportMethod"/> is set to 'Queue' the ingestion status
    // will always be 'Queued' and the caller needs to query the report queues for ingestion status, as configured. To query statuses that were
    // reported to queue, see: <see href="https://learn.microsoft.com/azure/kusto/api/netfx/kusto-ingest-client-status#ingestion-status-in-azure-queue"/>.
    // When <see cref="IngestionReportMethod"/> is set to 'Table', call <see cref="IKustoIngestionResult.GetIngestionStatusBySourceId"/> or
    // <see cref="IKustoIngestionResult.GetIngestionStatusCollection"/> to retrieve the most recent ingestion status.
    public Status Status { get; set; }
    // A unique identifier representing the ingested source. Can be supplied during the ingestion execution.
    public Guid IngestionSourceId { get; set; }
    // The URI of the blob, potentially including the secret needed to access the blob.
    // This can be a filesystem URI (on-premises deployments only), or an Azure Blob Storage URI (including a SAS key or a semicolon followed by the account key)
    public string IngestionSourcePath { get; set; }
    // The name of the database holding the target table.
    public string Database { get; set; }
    // The name of the target table into which the data will be ingested.
    public string Table { get; set; }
    // The last updated time of the ingestion status.
    public DateTime UpdatedOn { get; set; }
    // The ingestion's operation Id.
    public Guid OperationId { get; set; }
    // The ingestion operation activity Id.
    public Guid ActivityId { get; set; }
    // In case of a failure - indicates the failure's error code.
    public IngestionErrorCode ErrorCode { get; set; }
    // In case of a failure - indicates the failure's status.
    public FailureStatus FailureStatus { get; set; }
    // In case of a failure - indicates the failure's details.
    public string Details { get; set; }
    // In case of a failure - indicates whether or not the failures originate from an Update Policy.
    public bool OriginatesFromUpdatePolicy { get; set; }
}

Enumerazione stato

Valore Significato Temporaneo/Permanente
In sospeso Il valore può cambiare durante il corso dell'inserimento, in base al risultato dell'operazione di inserimento Temporaneo
Completato I dati sono stati inseriti correttamente Permanente
Non riuscito Inserimento non riuscito Permanente
Queued I dati sono stati accodati per l'inserimento Permanente
Operazione ignorata Non sono stati forniti dati e l'operazione di inserimento è stata ignorata Permanente
Parzialmentesucceed Parte dei dati è stata inserita correttamente, mentre alcuni non sono riusciti Permanente

Stato inserimento rilevamento (KustoQueuedIngestClient)

IKustoQueuedIngestClient è un client "fire-and-forget". L'operazione di inserimento sul lato client termina pubblicando un messaggio a una coda di Azure. Dopo la registrazione, il processo client viene eseguito. Per praticità dell'utente client, KustoQueuedIngestClient offre un meccanismo per tenere traccia dello stato di inserimento individuale. Questo meccanismo non è destinato all'utilizzo di massa in pipeline di inserimento con velocità effettiva elevata. Questo meccanismo è per l'inserimento di precisione quando la frequenza è relativamente bassa e i requisiti di rilevamento sono rigorosi.

Avviso

L'attivazione di notifiche positive per ogni richiesta di inserimento per flussi di dati di volume di grandi dimensioni deve essere evitata, poiché questo inserisce un carico estremo sulle risorse xStore sottostanti, che potrebbe causare un aumento della latenza di inserimento e anche la velocità di risposta del cluster completa.

Le proprietà seguenti (impostate in KustoQueuedIngestionProperties) controllano il livello e il trasporto per l'operazione di inserimento o notifiche di errore.

Enumerazione IngestionReportLevel

public enum IngestionReportLevel
{
    FailuresOnly = 0,
    None,
    FailuresAndSuccesses
}

Enumerazione IngestionReportMethod

public enum IngestionReportMethod
{
    Queue = 0,
    Table,
    QueueAndTable
}

Per tenere traccia dello stato dell'inserimento, specificare quanto segue per IKustoQueuedIngestClient con cui si esegue l'operazione di inserimento:

  1. Impostare IngestionReportLevella proprietà sul livello necessario del report. FailuresOnly (ovvero il valore predefinito) o FailuresAndSuccesses. Se impostato su None, non verrà segnalato nulla alla fine dell'inserimento.
  2. Specificare , IngestionReportMethodTable - Queueo .QueueAndTable

È possibile trovare un esempio di utilizzo nella pagina Esempi di Kusto.Ingest .

Stato di inserimento nella tabella di Azure

L'interfaccia IKustoIngestionResult restituita da ogni operazione di inserimento contiene funzioni che possono essere usate per eseguire query sullo stato dell'inserimento. Prestare particolare attenzione alla Status proprietà degli oggetti restituiti IngestionStatus :

  • Pending indica che l'origine è stata accodata per l'inserimento ed è ancora da aggiornare. Usare di nuovo la funzione per eseguire una query sullo stato dell'origine
  • Succeeded indica che l'origine è stata inserita correttamente
  • Failed indica che l'origine non è riuscita a essere inserita

Nota

Ottenere uno Queued stato indica che l'oggetto IngestionReportMethod è stato lasciato al valore predefinito di 'Queue'. Questo è uno stato permanente e richiama GetIngestionStatusBySourceId le funzioni o GetIngestionStatusCollection , genera sempre lo stesso stato "Accodato". Per controllare lo stato di un inserimento in una tabella di Azure, prima di inserire, verificare che la IngestionReportMethod proprietà di KustoQueuedIngestionProperties sia impostata su Table. Se si vuole che lo stato di inserimento venga segnalato a una coda, impostare lo stato su QueueAndTable.

Stato di inserimento nella coda di Azure

I IKustoIngestionResult metodi sono rilevanti solo per controllare lo stato in una tabella di Azure. Per eseguire query su stati segnalati a una coda di Azure, usare i metodi IKustoQueuedIngestClient seguenti.

Metodo Scopo
PeekTopIngestionFailures Metodo asincrono che restituisce informazioni sui primi errori di inserimento che non sono già stati eliminati a causa del limite per i messaggi richiesti
GetAndDiscardTopIngestionFailures Metodo asincrono che restituisce ed elimina i primi errori di inserimento che non sono già stati eliminati a causa del limite per i messaggi richiesti
GetAndDiscardTopIngestionSuccesses Metodo asincrono che restituisce ed elimina i primi successi di inserimento che non sono già stati eliminati a causa del limite per i messaggi richiesti. Questo metodo è rilevante solo se l'oggetto IngestionReportLevel è impostato su FailuresAndSuccesses

Errori di inserimento recuperati dalla coda di Azure

Gli errori di inserimento sono rappresentati dall'oggetto che contiene informazioni utili sull'errore IngestionFailure .

Proprietà Significato
Tabella & database Nomi di database e tabelle previsti
InserimentoSourcePath Percorso del BLOB inserito. Conterrà il nome del file originale se il file viene inserito. Sarà casuale se DataReader viene inserito
FailureStatus Permanent (non verrà eseguito alcun nuovo tentativo), Transient (verrà eseguito un nuovo tentativo) o Exhausted (anche diversi tentativi non sono riusciti)
OperationId & RootActivityId ID operazione e ID RootActivity dell'inserimento (utile per altre operazioni di risoluzione dei problemi)
FailedOn Ora UTC dell'errore. Sarà maggiore del tempo in cui è stato chiamato il metodo di inserimento, poiché i dati vengono aggregati prima di eseguire l'inserimento
Dettagli Altri dettagli relativi all'errore (se presente)
ErrorCode IngestionErrorCode enumerazione, rappresenta il codice di errore di inserimento, se si è verificato un errore