Kusto.Ingest betöltési állapotjelentés

  • Cikk

Ez a cikk bemutatja, hogyan használhatja az IKustoQueuedIngestClient funkciókat a betöltési kérések állapotának nyomon követésére.

Leírási osztályok

Ezek a leírási osztályok fontos részleteket tartalmaznak a betöltendő forrásadatokról, és ezeket a betöltési műveletben kell használni.

  • SourceDescription
  • DataReaderDescription
  • StreamDescription
  • FileDescription
  • BlobDescription

Az osztályok mindegyike az absztrakt osztályból SourceDescriptionszármazik, és az egyes adatforrások egyedi azonosítójának példányosítására szolgálnak. Ezután a rendszer minden azonosítót az állapotkövetéshez használ, és az adott művelethez kapcsolódó összes jelentésben, nyomkövetésben és kivételben megjelenik.

Osztály SourceDescription

A nagyméretű adathalmazok 1 GB-os adattömbökre lesznek felosztva, és minden rész külön lesz betöltve. Ugyanez a SourceId lesz alkalmazva az azonos adatkészletből származó összes betöltési műveletre.

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

DataReaderDescription osztály

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

Osztály streamleírója

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

FileDescription osztály

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

BlobDescription osztály

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; }
}

Betöltési eredmények ábrázolása

IKustoIngestionResult interfész

Ez az interfész egyetlen várólistán lévő betöltési művelet eredményét rögzíti, és a segítségével SourceIdlekérhető.

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();
}

IngestionStatus osztály

Az IngestionStatus egyetlen betöltési művelet teljes állapotát tartalmazza.

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; }
}

Állapot számbavétele

Érték Értelmezés Ideiglenes/állandó
Függőben Az érték a betöltés során változhat a betöltési művelet eredménye alapján Ideiglenes
Sikeres Az adatok betöltése sikerült Állandó
Sikertelen A betöltés nem sikerült Állandó
Várólistán Az adatok betöltési várólistára kerültek Állandó
Kihagyva Nem lett megadva adat, és a betöltési művelet ki lett hagyva Állandó
RészlegesenSucceeded Az adatok egy része sikeresen betöltődött, míg néhány sikertelen volt Állandó

Betöltési állapot nyomon követése (KustoQueuedIngestClient)

Az IKustoQueuedIngestClient egy "fire-and-forget" ügyfél. Az ügyféloldali betöltési művelet úgy ér véget, hogy üzenetet küld egy Azure-üzenetsorba. A feladást követően az ügyfélfeladat befejeződik. Az ügyfélfelhasználó kényelme érdekében a KustoQueuedIngestClient egy mechanizmust biztosít az egyes betöltési állapot nyomon követéséhez. Ez a mechanizmus nem a nagy átviteli sebességű betöltési folyamatok tömegfelhasználására szolgál. Ez a mechanizmus a pontosság betöltésére vonatkozik, ha a sebesség viszonylag alacsony, és a követési követelmények szigorúak.

Figyelmeztetés

A nagy mennyiségű adatstreamek betöltési kérelmeinek pozitív értesítéseit el kell kerülni, mivel ez rendkívüli terhelést okoz a mögöttes xStore-erőforrásokra, ami megnövekedett betöltési késéshez, sőt a fürt teljes nem válaszképességéhez vezethet.

Az alábbi tulajdonságok (a KustoQueuedIngestionProperties beállítással) szabályozzák a sikeres vagy sikertelen betöltési értesítések szintjét és átvitelét.

IngestionReportLevel enumerálás

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

IngestionReportMethod enumerálás

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

A betöltés állapotának nyomon követéséhez adja meg az alábbiakat annak az IKustoQueuedIngestClientnek , amellyel a betöltési műveletet hajtja végre:

  1. Állítsa be IngestionReportLevela tulajdonságot a jelentés szükséges szintjére. Vagy FailuresOnly (amely az alapértelmezett érték) vagy FailuresAndSuccesses. Ha a értékre Nonevan állítva, a betöltés végén semmi sem lesz jelentve.
  2. Adja meg a , Tablea vagy QueueAndTableaQueueIngestionReportMethod - értéket.

A használati példa a Kusto.Ingest Példák oldalán található.

Betöltési állapot az Azure-táblázatban

Az IKustoIngestionResult egyes betöltési műveletekből visszaadott felület olyan függvényeket tartalmaz, amelyek a betöltési állapot lekérdezésére használhatók. Különös figyelmet kell fordítani a Status visszaadott IngestionStatus objektumok tulajdonságára:

  • Pending azt jelzi, hogy a forrás várólistára lett helyezve a betöltéshez, és még nem frissítendő. A forrás állapotának lekérdezése a függvénnyel
  • Succeeded azt jelzi, hogy a forrás betöltése sikeresen megtörtént
  • Failed azt jelzi, hogy a forrás betöltése nem sikerült

Megjegyzés

Az állapot lekérése Queued azt jelzi, hogy az IngestionReportMethod alapértelmezett "Queue" értéken maradt. Ez egy állandó állapot, és a vagy GetIngestionStatusCollection függvény ismételt meghívása GetIngestionStatusBySourceId mindig ugyanazt a "Várólistán" állapotot eredményezi. Egy Azure-táblában lévő betöltés állapotának ellenőrzéséhez a betöltés előtt ellenőrizze, hogy a IngestionReportMethodKustoQueuedIngestionProperties tulajdonsága értékre Tablevan-e állítva. Ha azt is szeretné, hogy a betöltési állapot egy üzenetsorba legyen jelentve, állítsa az állapotot értékre QueueAndTable.

Betöltési állapot az Azure-üzenetsorban

A IKustoIngestionResult metódusok csak az Azure-táblák állapotának ellenőrzéséhez szükségesek. Az Azure-üzenetsorba jelentett állapotok lekérdezéséhez használja az alábbi IKustoQueuedIngestClient metódusokat.

Metódus Cél
PeekTopIngestionFailures Aszinkron metódus, amely információkat ad vissza azokról a legkorábbi betöltési hibákról, amelyek még nem lettek elvetve a kért üzenetek korlátja miatt
GetAndDiscardTopIngestionFailures Aszinkron metódus, amely visszaadja és elveti azokat a legkorábbi betöltési hibákat, amelyek még nem lettek elvetve a kért üzenetek korlátja miatt
GetAndDiscardTopIngestionSuccesses Aszinkron metódus, amely visszaadja és elveti azokat a legkorábbi betöltési sikereket, amelyek még nem lettek elvetve a kért üzenetek korlátja miatt. Ez a módszer csak akkor releváns, ha a IngestionReportLevel értéke FailuresAndSuccesses

Az Azure-üzenetsorból lekért betöltési hibák

A betöltési hibákat az IngestionFailure objektum jelöli, amely hasznos információkat tartalmaz a hibáról.

Tulajdonság Értelmezés
Adatbázis-& tábla A kívánt adatbázis- és táblanevek
IngestionSourcePath A betöltött blob elérési útja. A fájl betöltésekor az eredeti fájlnevet fogja tartalmazni. Véletlenszerű lesz, ha a DataReader betöltve van
FailureStatus Permanent (nem lesz újrapróbálkozás végrehajtva), Transient (újrapróbálkozás lesz végrehajtva), vagy Exhausted (több újrapróbálkozás sem sikerült)
OperationId & RootActivityId A betöltés műveletazonosítója és RootActivity azonosítója (további hibaelhárításhoz hasznos)
FailedOn A hiba UTC-időpontja. Nagyobb lesz, mint a betöltési módszer meghívásának időpontja, mivel az adatok összesítése a betöltési folyamat futtatása előtt történik
Részletek A hibával kapcsolatos egyéb részletek (ha vannak ilyenek)
ErrorCode IngestionErrorCode enumerálás, a betöltési hibakódot jelöli, ha hiba történt