String koneksi Kusto

Beralih layanan menggunakan daftar drop-down Versi . Pelajari selengkapnya tentang navigasi.
Berlaku untuk: ✅ Microsoft Fabric ✅ Azure Data Explorer

Kusto string koneksi s memberikan informasi yang diperlukan bagi aplikasi klien Kusto untuk membuat koneksi ke titik akhir layanan Kusto. String koneksi Kusto dimodelkan setelah string koneksi ADO.NET. Artinya, string koneksi adalah daftar pasangan parameter nilai nama yang dibatasi titik koma, secara opsional diawali oleh satu URI.

Misalnya, string koneksi Kusto berikut dimulai dengan URI yang menentukan titik akhir layanan untuk komunikasi: https://help.kusto.windows.net. URI ini ditetapkan ke Data Source properti . Selanjutnya, /Samples dalam string koneksi mewakili database default dan ditetapkan ke Initial Catalog properti . Terakhir, dua properti lain, Fed dan Accept, menyediakan opsi konfigurasi atau kustomisasi lebih lanjut untuk koneksi.

https://help.kusto.windows.net/Samples; Fed=true; Accept=true

Catatan

• Nama properti tidak peka huruf besar/kecil.
• Nilai properti bersifat peka huruf besar/kecil.
• Spasi di antara pasangan parameter nilai-nama diabaikan.
• Nilai properti yang berisi titik koma (;), tanda kutip tunggal ('), atau tanda kutip ganda (") harus diapit tanda kutip ganda.

Secara terprogram, kelas C# Kusto.Data.KustoConnectionStringBuilder dapat mengurai dan memanipulasi string koneksi Kusto. Kelas ini memvalidasi semua string koneksi dan menghasilkan pengecualian runtime jika validasi gagal. Fungsionalitas ini hadir dalam semua rasa Kusto SDK.

Titik akhir tepercaya

Koneksi dengan titik akhir Kusto hanya dapat dibuat jika titik akhir tersebut tepercaya. Klien Kusto mempercayai semua titik akhir yang domain hostnya dikeluarkan oleh layanan. Misalnya, titik akhir yang nama host DNS-nya berakhir dengan kusto.windows.net.

Secara default, klien tidak membuat koneksi ke titik akhir lain. Untuk mengizinkan koneksi ke titik akhir lain, gunakan Kusto.Data.Common.KustoTrustedEndpoints kelas untuk menambahkan titik akhir ke daftar titik akhir tepercaya. Gunakan SetOverridePolicy untuk mengambil alih kebijakan default, dan AddTrustedHosts untuk menambahkan entri baru ke kebijakan yang ada.

KustoTrustedEndpoints.AddTrustedHosts(
    new[]
    {
        // Allow an explicit service address
        new FastSuffixMatcher<EndpointContext>.MatchRule("my-kusto.contoso.com", exact: true, new EndpointContext(EndpointType.Kusto)),
        // Allow services whose DNS name end with ".contoso.com"
        new FastSuffixMatcher<EndpointContext>.MatchRule(".contoso.com", exact: false, new EndpointContext(EndpointType.Kusto)),
    }
);

Untuk informasi selengkapnya tentang cara melewati jaringan terbatas, lihat Mengelola pembatasan jaringan klien.

Properti string koneksi

Tabel berikut mencantumkan semua properti yang mungkin dapat disertakan dalam string koneksi Kusto dan memberikan nama alias untuk setiap properti. Selain itu, tabel mencatat nama terprogram yang terkait dengan setiap properti, yang mewakili nama properti dalam Kusto.Data.KustoConnectionStringBuilder objek.

Properti umum

Nama properti	Nama terprogram	Deskripsi
Versi Klien untuk Pelacakan	TraceClientVersion	Properti yang digunakan saat melacak versi klien.
Alias Sumber Data: Addr, Alamat, Alamat Jaringan, Server	DataSource	URI yang menentukan titik akhir layanan Kusto. Contohnya,https://mycluster.kusto.windows.net.
Alias Katalog Awal: Database	InitialCatalog	Nama database default. Contohnya,MyDatabase.
Alias Konsistensi Kueri: QueryConsistency	QueryConsistency	Atur ke atau strongconsistencyweakconsistency untuk menentukan apakah kueri harus disinkronkan dengan metadata sebelum berjalan.

Properti autentikasi pengguna

Nama properti	Nama terprogram	Deskripsi
Alias Keamanan Federasi ID Microsoft Entra: Federated Security, Federated, Fed, AADFed	FederatedSecurity	Nilai boolean yang menginstruksikan klien untuk melakukan autentikasi Microsoft Entra.
Alias ID Otoritas: TenantId	Otoritas	Nilai string yang menyediakan nama atau ID penyewa pengguna. Nilai defaultnya adalah microsoft.com. Untuk informasi selengkapnya, lihat Otoritas Microsoft Entra.
Alias ID Pengguna: UID, Pengguna	ID Pengguna	Nilai string yang menginstruksikan klien untuk melakukan autentikasi pengguna dengan nama pengguna yang ditunjukkan.
Nama Pengguna untuk Pelacakan	TraceUserName	Nilai string opsional yang melaporkan ke layanan nama pengguna mana yang akan digunakan saat melacak permintaan secara internal.
Alias Token Pengguna: UsrToken, UserToken	UserToken	Nilai string yang menginstruksikan klien untuk melakukan autentikasi pengguna dengan token pembawa yang ditentukan. Mengambil alih ApplicationClientId, , ApplicationKeydan ApplicationToken. Jika ditentukan, lewati alur autentikasi klien aktual demi token yang disediakan.

Kombinasi properti yang didukung untuk autentikasi pengguna

Untuk autentikasi pengguna, tentukan AAD Federated Security sebagai true. Kemudian, pilih salah satu mode autentikasi berikut, dan tentukan properti yang relevan untuk mode tersebut.

Mode autentikasi	Nama properti
Autentikasi Permintaan pengguna Microsoft Entra	- ID Pengguna (opsional) - ID Otoritas (opsional) - Nama Pengguna untuk Pelacakan (opsional)
Autentikasi Token pengguna Microsoft Entra	- Token Pengguna - Nama Pengguna untuk Pelacakan (opsional)

Properti autentikasi aplikasi

Nama properti	Nama terprogram	Deskripsi
Alias Keamanan Federasi ID Microsoft Entra: Federated Security, Federated, Fed, AADFed	FederatedSecurity	Nilai boolean yang menginstruksikan klien untuk melakukan autentikasi federasi ID Microsoft Entra.
Sertifikat Aplikasi SendX5c Alias: Sertifikat Aplikasi Kirim Sertifikat Publik, SendX5c	ApplicationCertificateSendX5c	Nilai boolean yang menginstruksikan klien untuk melakukan nama subjek dan autentikasi berbasis penerbit.
Alias Thumbprint Sertifikat Aplikasi: AppCert	ApplicationCertificateThumbprint	Nilai string yang menyediakan thumbprint sertifikat klien untuk digunakan saat menggunakan alur autentikasi sertifikat klien aplikasi.
Alias ID Klien Aplikasi: AppClientId	ApplicationClientId	Nilai string yang menyediakan ID klien aplikasi untuk digunakan saat mengautentikasi.
Alias Kunci Aplikasi: AppKey	TombolAplikasi	Nilai string yang menyediakan kunci aplikasi untuk digunakan saat mengautentikasi menggunakan alur rahasia aplikasi.
Nama Aplikasi untuk Alias Pelacakan : TraceAppName	ApplicationNameForTracing	Nilai string opsional yang melaporkan ke layanan nama aplikasi mana yang akan digunakan saat melacak permintaan secara internal.
Alias Token Aplikasi: AppToken	ApplicationToken	Nilai string yang menginstruksikan klien untuk melakukan autentikasi aplikasi dengan token pembawa yang ditentukan.
Alias ID Otoritas: TenantId	Otoritas	Nilai string yang menyediakan nama atau ID penyewa tempat aplikasi terdaftar. Nilai defaultnya adalah microsoft.com. Untuk informasi selengkapnya, lihat Otoritas Microsoft Entra.
Alias Wilayah Azure: AzureRegion, Wilayah	AzureRegion	Nilai string yang menyediakan nama Wilayah Azure untuk mengautentikasi.
ManagedServiceIdentity	EmbeddedManagedIdentity	Nilai string yang menginstruksikan klien identitas aplikasi mana yang akan digunakan dengan autentikasi identitas terkelola. Gunakan system untuk menunjukkan identitas yang ditetapkan sistem. Properti ini tidak dapat diatur dengan string koneksi, hanya secara terprogram.
Subjek Sertifikat Aplikasi Dibedakan Nama Alias: Subjek Sertifikat Aplikasi	ApplicationCertificateSubjectDistinguishedName	Nilai string yang menentukan nama khusus subjek sertifikat aplikasi.
Alias Nama Khusus Penerbit Sertifikat Aplikasi: Penerbit Sertifikat Aplikasi	ApplicationCertificateIssuerDistinguishedName	Nilai string yang menentukan nama khusus penerbit sertifikat aplikasi.

Kombinasi properti yang didukung untuk autentikasi aplikasi

Untuk autentikasi aplikasi, tentukan AAD Federated Security sebagai true. Kemudian, pilih salah satu mode autentikasi berikut, dan tentukan properti yang relevan untuk mode tersebut.

Mode autentikasi	Nama properti
Autentikasi Kunci Aplikasi Microsoft Entra	- Id Klien Aplikasi- Kunci Aplikasi- Id Otoritas - Nama Aplikasi untuk Pelacakan (opsional)
Autentikasi Thumbprint Aplikasi Microsoft Entra	- Id Klien Aplikasi- Thumbprint Sertifikat Aplikasi- Id Otoritas - Nama Aplikasi untuk Pelacakan (opsional)
Subjek Aplikasi Microsoft Entra dan Autentikasi Penerbit	- Id Klien Aplikasi- Subjek Sertifikat Aplikasi Dibedakan Nama - Penerbit Sertifikat Aplikasi Dibedakan Nama - Id Otoritas- Wilayah Azure (opsional) - Sertifikat Aplikasi SendX5c (opsional) - Nama Aplikasi untuk Pelacakan (opsional)
Autentikasi Nama Subjek Aplikasi Microsoft Entra	- Id Klien Aplikasi- Subjek Sertifikat Aplikasi Dibedakan Nama - Id Otoritas- dan Wilayah Azure (opsional) - Nama Aplikasi untuk Pelacakan (opsional)
Autentikasi Token Aplikasi Microsoft Entra	- Token Aplikasi - Nama Aplikasi untuk Pelacakan (opsional)

Autentikasi dengan sertifikat aplikasi

1. Aplikasi harus dikonfigurasi untuk menerima sertifikat yang diberikan. Cara mengautentikasi berdasarkan sertifikat aplikasi Microsoft Entra.
2. Aplikasi harus dikonfigurasi sebagai prinsipal resmi di lingkungan Kusto yang relevan.
3. Sertifikat perlu diinstal di penyimpanan Komputer Lokal atau di penyimpanan Pengguna Saat Ini.
4. Kunci umum sertifikat harus berisi setidaknya 2.048 bit.

Properti komunikasi klien

Nama properti	Nama terprogram	Deskripsi
Terima	Terima	Nilai boolean yang meminta objek kesalahan terperinci untuk dikembalikan jika gagal.
Streaming	Streaming	Nilai boolean yang meminta klien segera memberikan data kepada pemanggil tanpa mengumpulkannya terlebih dahulu. Streaming adalah perilaku default.
Tidak dipadatkan	Tidak dipadatkan	Nilai boolean yang menginstruksikan klien untuk menghindari permintaan kompresi tingkat transportasi.

Catatan

Streaming Ketika bendera diaktifkan (default), SDK tidak menyangga semua data respons dalam memori; sebaliknya, bendera "menarik" data dari layanan ketika pemanggil memintanya. Dalam hal ini, pemanggil harus membuang data dengan benar, seperti IDataReader, setelah selesai membaca data, karena koneksi jaringan ke layanan ditahan terbuka secara tidak perlu.

Contoh

Contoh berikut menunjukkan cara menyiapkan koneksi menggunakan C#. Untuk contoh dalam bahasa lain, lihat metode autentikasi aplikasi .

Autentikasi federasi ID Microsoft Entra dengan identitas pengguna saat ini

Contoh berikut menunjukkan cara menyiapkan koneksi ke layanan Kusto menggunakan ID Microsoft Entra untuk autentikasi gabungan. Pengguna dimintai kredensial, jika perlu.

using Kusto.Data;

var kustoUri = "serviceURI";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadUserPromptAuthentication(authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;Authority Id={authority}"

Autentikasi federasi ID Microsoft Entra dengan petunjuk ID pengguna

Contoh berikut menunjukkan cara menyiapkan koneksi ke layanan Kusto menggunakan ID Microsoft Entra untuk autentikasi gabungan dan mengisi identitas pengguna menggunakan userID variabel . Pengguna dimintai kredensial, jika perlu.

using Kusto.Data;

var kustoUri = "serviceURI";
var authority = "contoso.com"; // Or the AAD tenant GUID
var userId = "johndoe@contoso.com";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
  .WithAadUserPromptAuthentication(authority, userId);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;Authority Id={authority};User ID={userId}"

Autentikasi aplikasi federasi ID Microsoft Entra dengan ApplicationClientId dan ApplicationKey

Contoh berikut menunjukkan cara mengautentikasi ke layanan Kusto menggunakan ID Microsoft Entra untuk autentikasi gabungan dengan ID dan kunci klien aplikasi.

using Kusto.Data;

var kustoUri = "serviceURI";
var appId = "<appId>";
var appKey = "<appKey>";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadApplicationKeyAuthentication(appId, appKey, authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;AppClientId={appId};AppKey={appKey};Authority Id={authority}"

Autentikasi federasi ID Microsoft Entra dengan token pengguna dan aplikasi

Contoh berikut menunjukkan cara menyiapkan koneksi ke layanan Kusto menggunakan ID Microsoft Entra dengan token akses pengguna atau token akses aplikasi.

using Kusto.Data;

var kustoUri = "serviceURI";
var userAccessToken = "<userAccessToken>";
var appAccessToken = "<appAccessToken>";
// AAD User token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadUserTokenAuthentication(userAccessToken);

// Equivalent Kusto connection string: "Data Source={kustoUri};Database=NetDefaultDB;Fed=True;UserToken={userAccessToken}"
// AAD Application token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadApplicationTokenAuthentication(appAccessToken);

// Equivalent Kusto connection string: "Data Source={kustoUri};Database=NetDefaultDB;Fed=True;ApplicationToken={appAccessToken}"

Autentikasi dengan panggilan balik penyedia token

Contoh berikut menunjukkan cara mengautentikasi ke layanan Kusto menggunakan ID Microsoft Entra dengan panggilan balik penyedia token kustom. Token dipanggil setiap kali token diperlukan.

using Kusto.Data;

var kustoUri = "serviceURI";
Func<string> tokenProviderCallback; // User-defined method to retrieve the access token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadTokenProviderAuthentication(tokenProviderCallback);

Autentikasi dengan sertifikat X.509

Contoh berikut menunjukkan cara mengautentikasi ke layanan Kusto menggunakan ID Microsoft Entra untuk autentikasi gabungan dengan sertifikat aplikasi.

using Kusto.Data;

var kustoUri = "serviceURI";
var appId = "<appId>";
X509Certificate2 appCert;
var authority = "contoso.com"; // Or the AAD tenant GUID
bool sendX5c; // Set to 'True' to use Trusted Issuer feature of AAD
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadApplicationCertificateAuthentication(appId, appCert, authority, sendX5c);

Autentikasi dengan thumbprint sertifikat X.509

Contoh berikut menunjukkan cara menyiapkan koneksi ke layanan Kusto menggunakan ID Microsoft Entra dengan thumbprint sertifikat aplikasi. Klien mencoba memuat sertifikat dari penyimpanan lokal.

using Kusto.Data;

var kustoUri = "serviceURI";
var appId = "<appId>";
var appCert = "<appCert>";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadApplicationThumbprintAuthentication(appId, appCert, authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;AppClientId={appId};AppCert={appCert};Authority Id={authority}"

Konten terkait

• gambaran umum string Koneksi
• API Kusto
• Bahasa Kueri Kusto (KQL)