Kusto kapcsolati sztringek

  • Cikk

A Kusto kapcsolati sztringjei biztosítják a Kusto-ügyfélalkalmazások számára a Kusto szolgáltatásvégponthoz való csatlakozáshoz szükséges információkat. A Kusto-kapcsolati sztringek a ADO.NET kapcsolati sztringek után modelleződnek. Ez azt jelzi, hogy a kapcsolati karakterlánc a név-érték paraméterpárok pontosvesszővel tagolt listája, amelyet opcionálisan egyetlen URI előtaggal előtagolnak.

A következő Kusto kapcsolati karakterlánc például egy URI-val kezdődik, amely megadja a szolgáltatásvégpontot a kommunikációhoz: https://help.kusto.windows.net. Ez az URI hozzá van rendelve a Data Source tulajdonsághoz. Ezután a kapcsolati karakterlánc az alapértelmezett adatbázist jelöli, /Samples és hozzá van rendelve a Initial Catalog tulajdonsághoz. Végül két másik tulajdonság Fed , és Accepta további konfigurációs vagy testreszabási lehetőségeket biztosít a kapcsolathoz.

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

Megjegyzés

  • A tulajdonságnevek nem különböztetik meg a kis- és nagybetűket.
  • A tulajdonságértékek megkülönböztetik a kis- és nagybetűket.
  • A név-érték paraméterpárok közötti szóközök figyelmen kívül lesznek hagyva.
  • A pontosvesszőt (), egyetlen idézőjelet (;') vagy dupla idézőjelet (") tartalmazó tulajdonságértéket a kettős idézőjelek közé kell tenni.

Számos Kusto-ügyféleszköz támogatja a kapcsolati karakterlánc URI-előtagján keresztüli bővítményt, amely lehetővé teszi a ClusterName/InitialCatalog rövidített formátumát@. Ezek az eszközök például a kapcsolati karakterlánc @help/Samples a következőre fordítják: https://help.kusto.windows.net/Samples; Fed=true.

A C# Kusto.Data.KustoConnectionStringBuilder osztály programozott módon elemezheti és módosíthatja a Kusto kapcsolati sztringeket. Ez az osztály ellenőrzi az összes kapcsolati sztringet, és futásidejű kivételt hoz létre, ha az ellenőrzés sikertelen. Ez a funkció a Kusto SDK minden ízében megtalálható.

Megbízható végpontok

Kusto-végponttal csak akkor lehet kapcsolatot létesíteni, ha az adott végpont megbízható. A Kusto-ügyfél megbízik minden olyan végpontban, amelynek állomásnév részét a szolgáltatás bocsátja ki. Például azok a végpontok, amelyeknek a DNS-állomásneve a következővel kusto.windows.netvégződik: .

Alapértelmezés szerint az ügyfél nem létesít kapcsolatokat más végpontokkal. A más végpontokhoz való csatlakozás engedélyezéséhez a Kusto.Data.Common.KustoTrustedEndpoints osztály használatával adjon hozzá végpontokat a megbízható végpontok listájához. Ezzel SetOverridePolicy felülbírálhatja az alapértelmezett szabályzatot, és AddTrustedHosts új bejegyzéseket adhat hozzá a meglévő szabályzathoz.

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

Kapcsolati sztring tulajdonságai

Az alábbi táblázatok felsorolják a Kusto-kapcsolati karakterlánc tartalmazható összes lehetséges tulajdonságot. A táblák aliasneveket is biztosítanak az egyes tulajdonságokhoz. Ezenkívül a táblák az egyes tulajdonságokhoz társított programozott neveket jelölik, amelyek az objektum tulajdonságának Kusto.Data.KustoConnectionStringBuilder nevét jelölik.

Általános tulajdonságok

Tulajdonság neve Programozott név Description
Ügyfélverzió nyomkövetéshez TraceClientVersion Az ügyfélverzió nyomon követésekor használja ezt a tulajdonságot.
Adatforrás-aliasok

: Addr, Address, Network Address, Server		 Datasource A Kusto-szolgáltatásvégpontot meghatározó URI. Például: https://mycluster.kusto.windows.net.
Kezdetikatalógusalias

: Adatbázis		 InitialCatalog Az alapértelmezés szerint használni kívánt adatbázis neve. Például: MyDatabase.
Lekérdezéskonzisztenciaaliasa

: QueryConsistency		 QueryConsistency Állítsa vagy értékre strongconsistencyweakconsistency annak meghatározásához, hogy a lekérdezésnek szinkronizálnia kell-e a metaadatokkal a futtatás előtt.

Felhasználói hitelesítési tulajdonságok

Tulajdonság neve Programozott név Description
Microsoft Entra azonosító összevont biztonsága

Aliasok: Összevont biztonság, Összevont, Fed, AADFed		 Összevont biztonság Logikai érték, amely arra utasítja az ügyfelet, hogy végezzen Microsoft Entra hitelesítést.
Szolgáltatóazonosító

aliasa: TenantId		 Authority Egy sztringérték, amely a felhasználó bérlőjének nevét vagy azonosítóját adja meg. Az alapértelmezett érték microsoft.com. További információ: Microsoft Entra szolgáltató.
MFA-alias

kényszerítése: MFA, EnforceMFA		 EnforceMfa Nem kötelező logikai érték, amely arra utasítja az ügyfelet, hogy szerezzen be egy többtényezős hitelesítési jogkivonatot.
Felhasználói azonosító

aliasai: UID, Felhasználó		 UserID Egy sztringérték, amely arra utasítja az ügyfelet, hogy végezzen felhasználói hitelesítést a megadott felhasználónévvel.
Felhasználónév a nyomkövetéshez TraceUserName Nem kötelező sztringérték, amely a szolgáltatásnak jelenti, hogy melyik felhasználónevet használja a kérés belső nyomon követésekor.
Felhasználói jogkivonat-aliasok

: UsrToken, UserToken		 UserToken Egy sztringérték, amely arra utasítja az ügyfelet, hogy végezzen felhasználói hitelesítést a megadott tulajdonosi jogkivonattal.

Felülbírálások ApplicationClientId, ApplicationKey, és ApplicationToken. Ha meg van adva, kihagyja a tényleges ügyfél-hitelesítési folyamatot a megadott jogkivonat javára.

Támogatott tulajdonságkombinációk felhasználói hitelesítéshez

A felhasználói hitelesítéshez adja meg AAD Federated Security a következőt: true. Ezután válasszon az alábbi hitelesítési módok közül, és adja meg az adott mód megfelelő tulajdonságait.

Hitelesítési módszer Tulajdonságnevek
Microsoft Entra felhasználó parancssori hitelesítése - Felhasználói azonosító (nem kötelező)
- Szolgáltató azonosítója (nem kötelező)
- MFA kényszerítése (nem kötelező)
- Felhasználónév nyomkövetéshez (nem kötelező)
felhasználói jogkivonat-hitelesítés Microsoft Entra - Felhasználói jogkivonat
– MFA kényszerítése (nem kötelező)
– Felhasználónév a nyomkövetéshez (nem kötelező)

Alkalmazáshitelesítés tulajdonságai

Tulajdonság neve Programozott név Description
Microsoft Entra azonosító összevont biztonsága

Aliasok: Összevont biztonság, Összevont, Fed, AADFed		 Összevont biztonság Logikai érték, amely arra utasítja az ügyfelet, hogy Microsoft Entra azonosítót összevont hitelesítést hajtson végre.
Application Certificate SendX5c

Aliases: Application Certificate Send Public Certificate, SendX5c		 ApplicationCertificateSendX5c Logikai érték, amely arra utasítja az ügyfelet, hogy végezzen tulajdonosnevet és kiállítóalapú hitelesítést.
Alkalmazástanúsítvány ujjlenyomat-aliasa

: AppCert		 ApplicationCertificateThumbprint Egy sztringérték, amely biztosítja az ügyféltanúsítvány ujjlenyomatát, amelyet az alkalmazásügyfél tanúsítványhitelesítési folyamatának használatakor használhat.
Alkalmazásügyfél-azonosító

aliasa: AppClientId		 ApplicationClientId Egy sztringérték, amely megadja az alkalmazásügyfél-azonosítót, amelyet a hitelesítéshez használni kell.
Alkalmazáskulcs

aliasa: AppKey		 ApplicationKey Egy sztringérték, amely biztosítja az alkalmazáskulcsot, amelyet az alkalmazás titkos kódjának folyamatával történő hitelesítéshez használhat.
Nyomkövetési

alias alkalmazásneve: TraceAppName		 ApplicationNameForTracing Opcionális sztringérték, amely a szolgáltatásnak jelenti, hogy melyik alkalmazásnevet használja a kérés belső nyomon követésekor.
Alkalmazásjogkivonat

aliasa: AppToken		 ApplicationToken Egy sztringérték, amely arra utasítja az ügyfelet, hogy végezzen alkalmazáshitelesítést a megadott tulajdonosi jogkivonattal.
Szolgáltatóazonosító

aliasa: TenantId		 Authority Sztringérték, amely annak a bérlőnek a nevét vagy azonosítóját adja meg, amelyben az alkalmazás regisztrálva van. Az alapértelmezett érték microsoft.com. További információ: Microsoft Entra szolgáltató.
Azure-régió

aliasai: AzureRegion, Régió		 AzureRegion Sztringérték, amely annak az Azure-régiónak a nevét adja meg, amelyben hitelesíteni szeretne.
ManagedServiceIdentity EmbeddedManagedIdentity Egy sztringérték, amely arra utasítja az ügyfelet, hogy melyik alkalmazás-identitást használja a felügyelt identitás hitelesítésével. A rendszer által hozzárendelt identitás jelzésére használható system .

Ez a tulajdonság nem állítható be kapcsolati karakterlánc, csak programozott módon.
Alkalmazástanúsítvány tulajdonosának megkülönböztető neve

aliasa: Alkalmazástanúsítvány tárgya		 ApplicationCertificateSubjectDistinguishedName Sztringérték, amely meghatározza az alkalmazástanúsítvány tulajdonosának megkülönböztető nevét.
Alkalmazástanúsítvány-kiállító megkülönböztető név

aliasa: Alkalmazástanúsítvány-kiállító		 ApplicationCertificateIssuerDistinguishedName Sztringérték, amely meghatározza az alkalmazástanúsítvány kiállítójának megkülönböztető nevét.

Támogatott tulajdonságkombinációk alkalmazáshitelesítéshez

Az alkalmazáshitelesítéshez adja meg AAD Federated Security a következőt: true. Ezután válasszon az alábbi hitelesítési módok közül, és adja meg az adott mód megfelelő tulajdonságait.

Hitelesítési módszer Tulajdonságnevek
Microsoft Entra alkalmazáskulcs-hitelesítés - Alkalmazásügyfél azonosítója
– Alkalmazáskulcs
– Szolgáltató azonosítója
– Alkalmazás neve a nyomkövetéshez (nem kötelező)
Microsoft Entra alkalmazás ujjlenyomat-hitelesítése - Alkalmazásügyfél azonosítója
– Alkalmazástanúsítvány
ujjlenyomata – Szolgáltató azonosítója
– Alkalmazás neve a nyomkövetéshez (nem kötelező)
Microsoft Entra alkalmazás tulajdonosának és kiállítói hitelesítésének - Alkalmazásügyfél azonosítója
– Alkalmazástanúsítvány tulajdonosának megkülönböztető neve
– Alkalmazástanúsítvány kiállítójának megkülönböztető neve
– Szolgáltató azonosítója
– Azure-régió (nem kötelező)
- Alkalmazástanúsítvány SendX5c (nem kötelező)
– Alkalmazás neve a nyomkövetéshez (nem kötelező)
Microsoft Entra alkalmazás tulajdonosnevének hitelesítése - Alkalmazásügyfél azonosítója
– Alkalmazástanúsítvány tulajdonosának megkülönböztető neve
– Szolgáltató azonosítója
és Azure-régiója (nem kötelező)
– Alkalmazás neve a nyomkövetéshez (nem kötelező)
alkalmazásjogkivonat-hitelesítés Microsoft Entra - Alkalmazás jogkivonata
– Alkalmazás neve a nyomkövetéshez (nem kötelező)

Hitelesítés alkalmazástanúsítvánnyal

  1. Az alkalmazást úgy kell konfigurálni, hogy fogadja el a megadott tanúsítványt. Az alkalmazás tanúsítványán alapuló hitelesítés Microsoft Entra.
  2. Az alkalmazást a megfelelő Kusto-fürtön engedélyezett rendszernévként kell konfigurálni.
  3. A tanúsítványt a Helyigép-tárolóban vagy az Aktuális felhasználói tárolóban kell telepíteni.
  4. A tanúsítvány nyilvános kulcsának legalább 2048 bitesnek kell lennie.

Ügyfélkommunikációs tulajdonságok

Tulajdonság neve Programozott név Description
Elfogadás Elfogadás Logikai érték, amely részletes hibaobjektumok visszaadását kéri a hiba esetén.
Streamelés Streamelés Egy logikai érték, amely arra kéri az ügyfelet, hogy ne gyűjtse össze az adatokat, mielőtt megadja azokat a hívónak. Ez az alapértelmezett viselkedés.
Tömörítetlen Tömörítetlen Egy logikai érték, amely azt kéri az ügyféltől, hogy ne kérjen átviteli szintű tömörítést.

Megjegyzés

Ha a Streaming jelző engedélyezve van (ahogy az alapértelmezett), az SDK nem puffereli az összes válaszadatot a memóriában, hanem "lekéri" az adatokat a szolgáltatásból, amikor a hívó kéri. Ezért elengedhetetlen, hogy ebben az esetben a hívó megfelelően ártalmatlanítsa az adatokat (például IDataReader) az adatok beolvasása után, mivel a szolgáltatáshoz való hálózati kapcsolat szükségtelenül nyitva van.

Példák

Microsoft Entra azonosító összevont hitelesítése az aktuálisan bejelentkezett felhasználói identitással (szükség esetén a rendszer kérni fogja a felhasználót)

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
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}"

Microsoft Entra azonosító összevont hitelesítése felhasználói azonosítóval (szükség esetén a rendszer kérni fogja a felhasználót)

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
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}"

Microsoft Entra azonosító összevont alkalmazáshitelesítés az ApplicationClientId és az ApplicationKey használatával

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
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}"

Rendszer által hozzárendelt felügyelt identitás használata

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadSystemManagedIdentity();

Felhasználó által hozzárendelt felügyelt identitás használata

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadUserManagedIdentity(managedIdentityClientId);

Microsoft Entra azonosító összevont hitelesítés felhasználói/alkalmazás-jogkivonattal

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
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}"

Jogkivonat-szolgáltatói visszahívás használata (a rendszer minden alkalommal meghívja, amikor jogkivonatra van szükség)

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
Func<string> tokenProviderCallback; // User-defined method to retrieve the access token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadTokenProviderAuthentication(tokenProviderCallback);

X.509-tanúsítvány használata

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
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);

X.509-tanúsítvány használata ujjlenyomattal (az ügyfél megpróbálja betölteni a tanúsítványt a helyi tárolóból)

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
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}"