Připojovací řetězce Kusto
Připojovací řetězce Kusto poskytují informace potřebné pro klientskou aplikaci Kusto k navázání připojení ke koncovému bodu služby Kusto. Připojovací řetězce Kusto se modelují podle ADO.NET připojovacích řetězců. To znamená, že připojovací řetězec je seznam párů parametrů název-hodnota oddělený středníkem, který má volitelně předponu jeden identifikátor URI.
Například následující připojovací řetězec Kusto začíná identifikátorem URI, který určuje koncový bod služby pro komunikaci: https://help.kusto.windows.net. Tento identifikátor URI je přiřazen vlastnosti Data Source . /Samples Dále v rámci připojovací řetězec představuje výchozí databázi a je přiřazena Initial Catalog k vlastnosti . A nakonec dvě další vlastnosti, Fed a Accept, poskytují další možnosti konfigurace nebo přizpůsobení připojení.
https://help.kusto.windows.net/Samples; Fed=true; Accept=true
Poznámka
- V názvech vlastností se nerozlišují malá a velká písmena.
- V hodnotách vlastností se rozlišují malá a velká písmena.
- Mezery mezi dvojicemi parametrů název-hodnota se ignorují.
- Hodnota vlastnosti, která obsahuje středník (
;), jednoduchou uvozovku (') nebo dvojitou uvozovku ("), musí být uzavřena mezi dvojitými uvozovkami.
Několik klientských nástrojů Kusto podporuje rozšíření přes předponu URI připojovací řetězec, které umožňuje zkrácený formát Názvu clusteru/@InitialCatalog. Tyto nástroje například přeloží připojovací řetězec @help/Samples na https://help.kusto.windows.net/Samples; Fed=true.
Třída jazyka C# Kusto.Data.KustoConnectionStringBuilder může prostřednictvím kódu programu analyzovat připojovací řetězce Kusto a manipulovat s nimi. Tato třída ověří všechny připojovací řetězce a v případě neúspěšného ověření vygeneruje výjimku za běhu. Tato funkce se nachází ve všech verzích sady Kusto SDK.
Důvěryhodné koncové body
Připojení ke koncovému bodu Kusto je možné navázat pouze v případě, že je tento koncový bod důvěryhodný.
Klient Kusto důvěřuje všem koncovým bodům, jejichž část názvu hostitele vydala služba.
Například koncové body, jejichž název hostitele DNS končí na kusto.windows.net.
Ve výchozím nastavení klient nenaváže připojení k jiným koncovým bodům. Pokud chcete povolit připojení k jiným koncovým bodům, pomocí Kusto.Data.Common.KustoTrustedEndpoints třídy přidejte koncové body do seznamu důvěryhodných koncových bodů. Slouží SetOverridePolicy k přepsání výchozích zásad a AddTrustedHosts k přidání nových položek do existujících zásad.
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),
}
);
Vlastnosti připojovacího řetězce
Následující tabulky uvádějí všechny možné vlastnosti, které je možné zahrnout do připojovací řetězec Kusto. Tabulky také poskytují názvy aliasů pro každou vlastnost. Kromě toho tabulky označují programové názvy přidružené ke každé vlastnosti, které představují název vlastnosti v objektu Kusto.Data.KustoConnectionStringBuilder .
Obecné vlastnosti
| Název vlastnosti | Programový název | Description |
|---|---|---|
| Verze klienta pro trasování | TraceClientVersion | Při trasování verze klienta použijte tuto vlastnost. |
| Aliasy zdroje dat: Addr, Address, Network Address, Server |
DataSource | Identifikátor URI určující koncový bod služby Kusto. Například, https://mycluster.kusto.windows.net. |
| Počáteční alias katalogu : Databáze |
InitialCatalog | Název databáze, která se má použít ve výchozím nastavení. Například, MyDatabase. |
| Alias konzistence dotazů: Konzistence dotazů |
Konzistence dotazů | Pokud chcete zjistit, jestli se má dotaz před spuštěním synchronizovat s metadaty, nastavte na hodnotu strongconsistency nebo weakconsistency . |
Vlastnosti ověřování uživatelů
| Název vlastnosti | Programový název | Description |
|---|---|---|
| Federované zabezpečení Microsoft Entra IDAliasy: Federované zabezpečení, federované, Fed, AADFed |
FederatedSecurity | Logická hodnota, která dává klientovi pokyn, aby provedl Microsoft Entra ověřování. |
| Alias ID autority: TenantId |
Autorita | Řetězcová hodnota, která poskytuje název nebo ID tenanta uživatele. Výchozí hodnota je microsoft.com. Další informace najdete v tématu Microsoft Entra autorita. |
| Vynucení aliasu MFA : MFA, EnforceMFA |
Vynucenífa | Volitelná logická hodnota, která dává klientovi pokyn k získání vícefaktorového ověřovacího tokenu. |
| Aliasy ID uživatele: UID, Uživatel |
UserID | Řetězcová hodnota, která dává klientovi pokyn, aby provedl ověření uživatele pomocí zadaného uživatelského jména. |
| Uživatelské jméno pro trasování | TraceUserName | Volitelná řetězcová hodnota, která službě oznámí, které uživatelské jméno se má použít při interním trasování požadavku. |
| Aliasy tokenů uživatele: UsrToken, UserToken |
Usertoken | Řetězcová hodnota, která dává klientovi pokyn, aby provedl ověření uživatele se zadaným nosným tokenem. Přepisuje ApplicationClientId, ApplicationKeya ApplicationToken. Pokud je zadaný, přeskočí skutečný tok ověřování klienta ve prospěch poskytnutého tokenu. |
Podporované kombinace vlastností pro ověřování uživatelů
Pro ověřování uživatelů zadejte AAD Federated Security jako true. Pak zvolte jeden z následujících režimů ověřování a zadejte příslušné vlastnosti pro tento režim.
| Režim ověřování | Názvy vlastností |
|---|---|
| ověřování výzvy uživatele Microsoft Entra | - ID uživatele (volitelné) – ID autority (volitelné) – Vynucení vícefaktorového ověřování (volitelné) – Uživatelské jméno pro trasování (volitelné) |
| ověřování pomocí tokenu uživatele Microsoft Entra | – Token uživatele – Vynucení vícefaktorového ověřování (volitelné) – Uživatelské jméno pro trasování (volitelné) |
Vlastnosti ověřování aplikací
| Název vlastnosti | Programový název | Description |
|---|---|---|
| Federované zabezpečení Microsoft Entra IDAliasy: Federované zabezpečení, federované, Fed, AADFed |
FederatedSecurity | Logická hodnota, která dává klientovi pokyn, aby provedl federované ověřování Microsoft Entra ID. |
| Aliasy certifikátu aplikace SendX5c : Odeslání veřejného certifikátu certifikátu aplikace, SendX5c |
ApplicationCertificateSendX5c | Logická hodnota, která dává klientovi pokyn, aby provedl ověřování na základě názvu subjektu a vystavitele. |
| Alias kryptografického otisku certifikátu aplikace: AppCert |
ApplicationCertificateThumbprint | Řetězcová hodnota, která poskytuje kryptografický otisk klientského certifikátu, který se má použít při použití toku ověřování klientského certifikátu aplikace. |
| Alias ID klienta aplikace: AppClientId |
Id klienta aplikace | Řetězcová hodnota, která poskytuje ID klienta aplikace, které se má použít při ověřování. |
| Alias klíče aplikace: AppKey |
ApplicationKey | Řetězcová hodnota, která poskytuje klíč aplikace, který se má použít při ověřování pomocí toku tajných kódů aplikace. |
| Název aplikace pro trasovací alias: TraceAppName |
ApplicationNameForTracing | Volitelná řetězcová hodnota, která oznamuje službě název aplikace, který se má použít při interním trasování požadavku. |
| Alias tokenu aplikace: AppToken |
ApplicationToken | Řetězcová hodnota, která dává klientovi pokyn, aby provedl ověření aplikace se zadaným nosným tokenem. |
| Alias ID autority: TenantId |
Autorita | Řetězcová hodnota, která poskytuje název nebo ID tenanta, ve kterém je aplikace zaregistrovaná. Výchozí hodnota je microsoft.com. Další informace najdete v tématu Microsoft Entra autorita. |
| Aliasy oblastí Azure: AzureRegion, Region |
Oblast Azure | Řetězcová hodnota, která poskytuje název oblasti Azure, ve které se má provést ověření. |
| Identita spravované služby | EmbeddedManagedIdentity | Řetězcová hodnota, která klientovi dává pokyn, jakou identitu aplikace má použít s ověřováním spravované identity. Slouží system k označení identity přiřazené systémem. Tuto vlastnost nelze nastavit pomocí připojovací řetězec, pouze programově. |
| Alias rozlišujícího názvu předmětu certifikátu aplikace: Předmět certifikátu aplikace |
ApplicationCertificateSubjectDistinguishedName | Řetězcová hodnota, která určuje rozlišující název předmětu certifikátu aplikace. |
| Alias rozlišujícího názvu vystavitele certifikátu aplikace: Vystavitel certifikátu aplikace |
ApplicationCertificateIssuerDistinguishedName | Řetězcová hodnota, která určuje rozlišující název vystavitele certifikátu aplikace. |
Podporované kombinace vlastností pro ověřování aplikací
Pro ověřování aplikací zadejte AAD Federated Security jako true. Pak zvolte jeden z následujících režimů ověřování a zadejte příslušné vlastnosti pro tento režim.
| Režim ověřování | Názvy vlastností |
|---|---|
| Microsoft Entra ověřování pomocí klíče aplikace | - Id klienta aplikace – Klíč aplikace – ID autority – Název aplikace pro trasování (volitelné) |
| Ověřování kryptografického otisku aplikace Microsoft Entra | - Id klienta aplikace – Kryptografický otisk certifikátu aplikace – ID autority – Název aplikace pro trasování (volitelné) |
| Microsoft Entra ověření vystavitele a předmětu aplikace | - Id klienta aplikace – Rozlišující název předmětu certifikátu aplikace – Rozlišující název vystavitele certifikátu aplikace – ID autority – Oblast Azure (volitelné) – Certifikát aplikace SendX5c (volitelné) – Název aplikace pro trasování (volitelné) |
| ověřování názvu subjektu aplikace Microsoft Entra | - Id klienta aplikace – Rozlišující název předmětu certifikátu aplikace – ID autority – a oblast Azure (volitelné) – Název aplikace pro trasování (volitelné) |
| Microsoft Entra ověřování pomocí tokenu aplikace | - Token aplikace – Název aplikace pro trasování (volitelné) |
Ověřování pomocí certifikátu aplikace
- Aplikace by měla být nakonfigurovaná tak, aby přijímala daný certifikát. Postup ověřování na základě certifikátu Microsoft Entra aplikace.
- Aplikace by měla být nakonfigurovaná jako autorizovaný objekt zabezpečení v příslušném clusteru Kusto.
- Certifikát musí být nainstalovaný v úložišti místního počítače nebo v úložišti aktuálního uživatele.
- Veřejný klíč certifikátu by měl obsahovat alespoň 2048 bitů.
Vlastnosti komunikace klienta
| Název vlastnosti | Programový název | Description |
|---|---|---|
| Přijmout | Přijmout | Logická hodnota, která vyžaduje podrobné chybové objekty, které mají být vráceny při selhání. |
| Streamování | Streamování | Logická hodnota, která vyžaduje, aby klient neshromažďovali data před jejich poskytnutím volajícímu. Jedná se o výchozí chování. |
| Nekomprimované | Nekomprimované | Logická hodnota, která vyžaduje, aby klient nepožaduje kompresi na úrovni přenosu. |
Poznámka
Streaming Když je příznak povolený (stejně jako výchozí nastavení), sada SDK neukládá všechna data odpovědí do vyrovnávací paměti. Místo toho si data "vyžádá" ze služby, když o ně volající požádá. Proto je nezbytné, aby v tomto případě volající po přečtení dat řádně vyhodil data (například IDataReader), protože síťové připojení ke službě je zbytečně otevřené.
Příklady
Federované ověřování Microsoft Entra ID pomocí aktuálně přihlášené identity uživatele (v případě potřeby se uživateli zobrazí výzva)
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}"
Federované ověřování Microsoft Entra ID s nápovědou k ID uživatele (v případě potřeby se uživateli zobrazí výzva)
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 ID federovaného ověřování aplikací pomocí Id klienta aplikace a klíče aplikace
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}"
Použití spravované identity přiřazené systémem
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadSystemManagedIdentity();
Použití spravované identity přiřazené uživatelem
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserManagedIdentity(managedIdentityClientId);
Federované ověřování Microsoft Entra ID pomocí tokenu uživatele nebo aplikace
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}"
Použití zpětného volání poskytovatele tokenu (bude vyvoláno pokaždé, když se token vyžaduje)
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);
Použití certifikátu X.509
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);
Použití certifikátu X.509 podle kryptografického otisku (klient se pokusí načíst certifikát z místního úložiště)
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}"
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro