クイック スタート: Azure Data Explorer .NET Standard SDK (プレビュー) を使用してデータを取り込むQuickstart: Ingest data using the Azure Data Explorer .NET Standard SDK (Preview)

Azure Data Explorer (ADX) は、ログとテレメトリ データのための高速で非常にスケーラブルなデータ探索サービスです。Azure Data Explorer (ADX) is a fast and highly scalable data exploration service for log and telemetry data. ADX では、.NET Standard 用のクライアント ライブラリとして、取り込みライブラリデータ ライブラリの 2 つが用意されています。ADX provides two client libraries for .NET Standard: an ingest library and a data library. これらのライブラリを使用すると、クラスターにデータを取り込み (読み込み)、コードからデータのクエリを行うことができます。These libraries enable you to ingest (load) data into a cluster and query data from your code. このクイック スタートではまず、テスト クラスター内にテーブルとデータ マッピングを作成します。In this quickstart, you first create a table and data mapping in a test cluster. その後、クラスターに対するインジェストをキューに入れて、結果を検証します。You then queue an ingestion to the cluster and validate the results.

前提条件Prerequisites

取り込みライブラリをインストールするInstall the ingest library

Install-Package Microsoft.Azure.Kusto.Ingest.NETStandard

AuthenticationAuthentication

Azure データ エクスプ ローラーでは、アプリケーションを認証するために AAD テナント ID が使用されます。To authenticate an application, Azure Data Explorer uses your AAD tenant ID. テナント ID を検索するには、次の URL を使用し、ドメインを YourDomain に置き換えます。To find your tenant ID, use the following URL, substituting your domain for YourDomain.

https://login.windows.net/<YourDomain>/.well-known/openid-configuration/

たとえば、ドメインが contoso.com の場合、URL は https://login.windows.net/contoso.com/.well-known/openid-configuration/ になります。For example, if your domain is contoso.com, the URL is: https://login.windows.net/contoso.com/.well-known/openid-configuration/. 結果を表示するには、この URL をクリックします。最初の行は次のとおりです。Click this URL to see the results; the first line is as follows.

"authorization_endpoint":"https://login.windows.net/6babcaad-604b-40ac-a9d7-9fd97c0b779f/oauth2/authorize"

この場合のテナント ID は 6babcaad-604b-40ac-a9d7-9fd97c0b779f です。The tenant ID in this case is 6babcaad-604b-40ac-a9d7-9fd97c0b779f.

この例では、クラスターにアクセスするための認証に AAD ユーザーとパスワードを使用します。This example uses an AAD user and password for authentication to access the cluster. AAD アプリケーション証明書と AAD アプリケーション キーを使用することもできます。You can also use AAD application certificate and AAD application key. このコードを実行する前に、tenantIduserpassword を実際の値に設定します。Set the your values for tenantId, user, and password before running this code.

var tenantId = "<TenantId>";
var user = "<User>";
var password = "<Password>";

接続文字列を作成するConstruct the connection string

では、接続文字列を作成します。Now construct the connection string. ターゲット テーブルとマッピングは後のステップで作成します。You create the destination table and mapping in a later step.

var kustoUri = "https://<ClusterName>.<Region>.kusto.windows.net:443/";
var database = "<DatabaseName>";

var kustoConnectionStringBuilder =
    new KustoConnectionStringBuilder(kustoUri)
    {
        FederatedSecurity = true,
        InitialCatalog = database,
        UserID = user,
        Password = password,
        Authority = tenantId
    };

ソース ファイルの情報を設定するSet source file information

ソース ファイルのパスを設定します。Set the path for the source file. この例では、Azure Blob Storage でホストされているサンプル ファイルを使います。This example uses a sample file hosted on Azure Blob Storage. StormEventsサンプル データ セットには、 National Centers for Environmental Information から入手した気象関連データが含まれていますThe StormEvents sample data set contains weather-related data from the National Centers for Environmental Information.

var blobPath = "https://kustosamplefiles.blob.core.windows.net/samplefiles/StormEvents.csv?st=2018-08-31T22%3A02%3A25Z&se=2020-09-01T22%3A02%3A00Z&sp=r&sv=2018-03-28&sr=b&sig=LQIbomcKI8Ooz425hWtjeq6d61uEaq21UVX7YrM61N4%3D";

テスト クラスターにテーブルを作成するCreate a table on your test cluster

StormEvents.csv ファイル内のデータのスキーマと一致する、StormEvents という名前のテーブルを作成します。Create a table named StormEvents that matches the schema of the data in the StormEvents.csv file.

var table = "StormEvents";
using (var kustoClient = KustoClientFactory.CreateCslAdminProvider(kustoConnectionStringBuilder))
{
    var command =
        CslCommandGenerator.GenerateTableCreateCommand(
            table,
            new[]
            {
                Tuple.Create("StartTime", "System.DateTime"),
                Tuple.Create("EndTime", "System.DateTime"),
                Tuple.Create("EpisodeId", "System.Int32"),
                Tuple.Create("EventId", "System.Int32"),
                Tuple.Create("State", "System.String"),
                Tuple.Create("EventType", "System.String"),
                Tuple.Create("InjuriesDirect", "System.Int32"),
                Tuple.Create("DeathsDirect", "System.Int32"),
                Tuple.Create("DeathsIndirect", "System.Int32"),
                Tuple.Create("DamageProperty", "System.Int32"),
                Tuple.Create("DamageCrops", "System.Int32"),
                Tuple.Create("Source", "System.String"),
                Tuple.Create("BeginLocation", "System.String"),
                Tuple.Create("EndLocation", "System.String"),
                Tuple.Create("BeginLat", "System.Double"),
                Tuple.Create("BeginLon", "System.Double"),
                Tuple.Create("EndLat", "System.Double"),
                Tuple.Create("EndLon", "System.Double"),
                Tuple.Create("EpisodeNarrative", "System.String"),
                Tuple.Create("EventNarrative", "System.String"),
                Tuple.Create("StormSummary", "System.Object"),
            });

    kustoClient.ExecuteControlCommand(command);
}

インジェストのマッピングを定義するDefine ingestion mapping

受信した CSV データを、テーブル作成時に使用される列名にマップします。Map the incoming CSV data to the column names used when creating the table. CSV 列マッピング オブジェクトをそのテーブルにプロビジョニングするProvision a CSV column mapping object on that table

var tableMapping = "StormEvents_CSV_Mapping";
using (var kustoClient = KustoClientFactory.CreateCslAdminProvider(kustoConnectionStringBuilder))
{
    var command =
        CslCommandGenerator.GenerateTableCsvMappingCreateCommand(
            table,
            tableMapping,
            new[]
            {
                new CsvColumnMapping { ColumnName = "StartTime", Ordinal = 0 },
                new CsvColumnMapping { ColumnName = "EndTime", Ordinal = 1 },
                new CsvColumnMapping { ColumnName = "EventId", Ordinal = 3 },
                new CsvColumnMapping { ColumnName = "State", Ordinal = 4 },
                new CsvColumnMapping { ColumnName = "InjuriesDirect", Ordinal = 6 },
                new CsvColumnMapping { ColumnName = "InjuriesIndirect", Ordinal = 7 },
                new CsvColumnMapping { ColumnName = "DeathsDirect", Ordinal = 8 },
                new CsvColumnMapping { ColumnName = "DeathsIndirect", Ordinal = 9 },
                new CsvColumnMapping { ColumnName = "DamageProperty", Ordinal = 10 },
                new CsvColumnMapping { ColumnName = "DamageCrops", Ordinal = 11 },
                new CsvColumnMapping { ColumnName = "Source", Ordinal = 12 },
                new CsvColumnMapping { ColumnName = "BeginLocation", Ordinal = 13 },
                new CsvColumnMapping { ColumnName = "EndLocation", Ordinal = 14 },
                new CsvColumnMapping { ColumnName = "BeginLat", Ordinal = 16 },
                new CsvColumnMapping { ColumnName = "BeginLon", Ordinal = 17 },
                new CsvColumnMapping { ColumnName = "EndLat", Ordinal = 18 },
                new CsvColumnMapping { ColumnName = "EndLon", Ordinal = 19 },
                new CsvColumnMapping { ColumnName = "EpisodeNarrative", Ordinal = 20 },
                new CsvColumnMapping { ColumnName = "EventNarrative", Ordinal = 21 },
                new CsvColumnMapping { ColumnName = "StormSummary", Ordinal = 22 },
            });

    kustoClient.ExecuteControlCommand(command);
}

取り込みのためにメッセージをキューに入れるQueue a message for ingestion

BLOB ストレージからデータをプルし、そのデータを ADX に取り込むために、メッセージをキューに入れます。Queue a message to pull data from blob storage and ingest that data into ADX.

var ingestUri = "https://ingest-<ClusterName>.<Region>.kusto.windows.net:443/";
var ingestConnectionStringBuilder =
    new KustoConnectionStringBuilder(ingestUri)
    {
        FederatedSecurity = true,
        InitialCatalog = database,
        UserID = user,
        Password = password,
        Authority = tenantId
    };

using (var ingestClient = KustoIngestFactory.CreateQueuedIngestClient(ingestConnectionStringBuilder))
{
    var properties =
        new KustoQueuedIngestionProperties(database, table)
        {
            Format = DataSourceFormat.csv,
            CSVMappingReference = tableMapping,
            IgnoreFirstRecord = true
        };

    ingestClient.IngestFromSingleBlob(blobPath, deleteSourceOnSuccess: false, ingestionProperties: properties);
}

データがテーブルに取り込まれたことを確認するValidate data was ingested into the table

キューに入れられたインジェストが取り込みをスケジュールされて、ADX にデータが読み込まれるまで、5 から 10 分待ちます。Wait for five to ten minutes for the queued ingestion to schedule the ingest and load the data into ADX. その後、次のコードを実行して、StormEvents テーブル内のレコードの数を取得します。Then run the following code to get the count of records in the StormEvents table.

using (var cslQueryProvider = KustoClientFactory.CreateCslQueryProvider(kustoConnectionStringBuilder))
{
    var query = $"{table} | count";

    var results = cslQueryProvider.ExecuteQuery<long>(query);
    Console.WriteLine(results.Single());
}

トラブルシューティングのクエリを実行するRun troubleshooting queries

https://dataexplorer.azure.com にサインインして、クラスターに接続します。Sign in to https://dataexplorer.azure.com and connect to your cluster. データベースで次のコマンドを実行し、過去 4 時間以内にインジェスト エラーがあったかどうかを調べます。Run the following command in your database to see if there were any ingestion failures in the last four hours. 実行する前にデータベース名を置き換えてください。Replace the database name before running.

.show ingestion failures
| where FailedOn > ago(4h) and Database == "<DatabaseName>"

次のコマンドを実行し、過去 4 時間以内のすべてのインジェスト操作の状態を表示します。Run the following command to view the status of all ingestion operations in the last four hours. 実行する前にデータベース名を置き換えてください。Replace the database name before running.

.show operations
| where StartedOn > ago(4h) and Database == "<DatabaseName>" and Operation == "DataIngestPull"
| summarize arg_max(LastUpdatedOn, *) by OperationId

リソースのクリーンアップClean up resources

他のクイック スタートやチュートリアルを行う場合は、作成したリソースをそのままにします。If you plan to follow our other quickstarts and tutorials, keep the resources you created. 行わない場合は、データベースで次のコマンドを実行して、StormEvents テーブルをクリーンアップします。If not, run the following command in your database to clean up the StormEvents table.

.drop table StormEvents

次の手順Next steps