Parametry połączenia z aplikacją Kusto
Parametry połączenia usługi Kusto udostępniają informacje niezbędne do nawiązania połączenia z punktem końcowym usługi Kusto przez aplikację kliencką Kusto. Parametry połączenia usługi Kusto są modelowane po parametrach połączenia ADO.NET. Oznacza to, że parametry połączenia jest rozdzieloną średnikami listą par parametrów name-value, opcjonalnie poprzedzoną pojedynczym identyfikatorem URI.
Na przykład następujące parametry połączenia Kusto rozpoczyna się od identyfikatora URI określającego punkt końcowy usługi na potrzeby komunikacji: https://help.kusto.windows.net. Ten identyfikator URI jest przypisywany Data Source do właściwości . /Samples Następnie w parametry połączenia reprezentuje domyślną bazę danych i jest przypisana Initial Catalog do właściwości . Na koniec dwie inne właściwości Fed i Accept, zapewniają dalszą konfigurację lub opcje dostosowywania połączenia.
https://help.kusto.windows.net/Samples; Fed=true; Accept=true
Uwaga
- W nazwach właściwości nie jest uwzględniana wielkość liter.
- W wartościach właściwości jest uwzględniana wielkość liter.
- Spacje między parami parametrów name-value są ignorowane.
- Wartość właściwości zawierająca średnik (
;), pojedynczy cudzysłów (') lub podwójny cudzysłów (") musi być ujęta między podwójnym cudzysłowem.
Kilka narzędzi klienckich Usługi Kusto obsługuje rozszerzenie za pośrednictwem prefiksu identyfikatora URI parametry połączenia, które umożliwia skrócony format @clusterName/InitialCatalog. Na przykład te narzędzia tłumaczą parametry połączenia @help/Samples na https://help.kusto.windows.net/Samples; Fed=true.
Programowo klasa języka C# Kusto.Data.KustoConnectionStringBuilder może analizować parametry połączenia usługi Kusto i manipulować nimi. Ta klasa sprawdza poprawność wszystkich parametrów połączenia i generuje wyjątek środowiska uruchomieniowego w przypadku niepowodzenia walidacji. Ta funkcja jest dostępna we wszystkich wersjach zestawu Kusto SDK.
Zaufane punkty końcowe
Połączenie z punktem końcowym usługi Kusto można ustanowić tylko wtedy, gdy ten punkt końcowy jest zaufany.
Klient Usługi Kusto ufa wszystkim punktom końcowym, których część nazwa hosta jest wystawiana przez usługę.
Na przykład punkty końcowe, których nazwa hosta DNS kończy się ciągiem kusto.windows.net.
Domyślnie klient nie nawiązuje połączeń z innymi punktami końcowymi. Aby zezwolić na połączenia z innymi punktami końcowymi, użyj Kusto.Data.Common.KustoTrustedEndpoints klasy , aby dodać punkty końcowe do listy zaufanych punktów końcowych. Służy SetOverridePolicy do zastępowania zasad domyślnych i AddTrustedHosts dodawania nowych wpisów do istniejących zasad.
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),
}
);
Właściwości parametrów połączenia
W poniższych tabelach wymieniono wszystkie możliwe właściwości, które można uwzględnić w usłudze Kusto parametry połączenia. Tabele zawierają również nazwy aliasów dla każdej właściwości. Ponadto tabele wskazują nazwy programowe skojarzone z każdą właściwością, która reprezentuje nazwę właściwości w Kusto.Data.KustoConnectionStringBuilder obiekcie.
Właściwości ogólne
| Nazwa właściwości | Nazwa programowa | Opis |
|---|---|---|
| Wersja klienta do śledzenia | TraceClientVersion | Podczas śledzenia wersji klienta użyj tej właściwości. |
| Aliasy źródeł danych: Addr, Address, Network Address, Server |
DataSource | Identyfikator URI określający punkt końcowy usługi Kusto. Na przykład https://mycluster.kusto.windows.net. |
| Alias katalogu początkowego: baza danych |
InitialCatalog | Nazwa bazy danych, która ma być używana domyślnie. Na przykład MyDatabase. |
| Alias spójności zapytania: QueryConsistency |
ZapytanieKonsistency | Ustaw wartość strongconsistency lub weakconsistency , aby określić, czy zapytanie powinno być zsynchronizowane z metadanymi przed uruchomieniem. |
Właściwości uwierzytelniania użytkownika
| Nazwa właściwości | Nazwa programowa | Opis |
|---|---|---|
| Microsoft Entra ID Federated Security Aliasy: Zabezpieczenia federacyjne, Federated, Fed, AADFed |
Zabezpieczenia federacyjne | Wartość logiczna, która nakazuje klientowi przeprowadzenie Microsoft Entra uwierzytelniania. |
| Alias identyfikatora urzędu: TenantId |
Urząd | Wartość ciągu, która zawiera nazwę lub identyfikator dzierżawy użytkownika. Wartość domyślna to microsoft.com. Aby uzyskać więcej informacji, zobacz urząd Microsoft Entra. |
| Wymuszanie aliasu uwierzytelniania wieloskładnikowego : uwierzytelnianie wieloskładnikowe, wymuszanie uwierzytelniania wieloskładnikowego |
EnforceMfa | Opcjonalna wartość logiczna, która nakazuje klientowi uzyskanie tokenu uwierzytelniania wieloskładnikowego. |
| Aliasy identyfikatorów użytkownika: UID, User |
UserID | Wartość ciągu, która nakazuje klientowi przeprowadzenie uwierzytelniania użytkownika przy użyciu wskazanej nazwy użytkownika. |
| Nazwa użytkownika do śledzenia | TraceUserName | Opcjonalna wartość ciągu zgłaszana do usługi, której nazwy użytkownika należy użyć podczas wewnętrznego śledzenia żądania. |
| Aliasy tokenu użytkownika: UsrToken, UserToken |
Usertoken | Wartość ciągu, która nakazuje klientowi przeprowadzenie uwierzytelniania użytkownika przy użyciu określonego tokenu elementu nośnego. Zastępuje wartości ApplicationClientId, ApplicationKeyi ApplicationToken. Jeśli zostanie określony, pomija rzeczywisty przepływ uwierzytelniania klienta na rzecz podanego tokenu. |
Obsługiwane kombinacje właściwości na potrzeby uwierzytelniania użytkowników
W przypadku uwierzytelniania użytkownika określ wartość AAD Federated Securitytrue. Następnie wybierz jeden z następujących trybów uwierzytelniania i określ odpowiednie właściwości dla tego trybu.
| Tryb uwierzytelniania | Nazwy właściwości |
|---|---|
| Microsoft Entra uwierzytelnianie monitu użytkownika | — Identyfikator użytkownika (opcjonalnie)- Identyfikator urzędu (opcjonalnie) - Wymuszanie uwierzytelniania wieloskładnikowego (opcjonalnie) — nazwa użytkownika do śledzenia (opcjonalnie) |
| Uwierzytelnianie tokenu użytkownika Microsoft Entra | — Token użytkownika — wymuszanie uwierzytelniania wieloskładnikowego (opcjonalnie) — nazwa użytkownika do śledzenia (opcjonalnie) |
Właściwości uwierzytelniania aplikacji
| Nazwa właściwości | Nazwa programowa | Opis |
|---|---|---|
| Microsoft Entra ID Federated Security Aliasy: Zabezpieczenia federacyjne, Federated, Fed, AADFed |
Zabezpieczenia federacyjne | Wartość logiczna, która nakazuje klientowi wykonanie Microsoft Entra identyfikatora uwierzytelniania federacyjnego. |
| Aliasy certyfikatu aplikacji SendX5c : Certyfikat aplikacji Wyślij certyfikat publiczny, SendX5c |
ApplicationCertificateSendX5c | Wartość logiczna, która nakazuje klientowi przeprowadzenie uwierzytelniania opartego na nazwie podmiotu i wystawcy. |
| Alias odcisku palca certyfikatu aplikacji: AppCert |
ApplicationCertificateThumbprint | Wartość ciągu, która dostarcza odcisk palca certyfikatu klienta do użycia podczas korzystania z przepływu uwierzytelniania certyfikatu klienta aplikacji. |
| Alias identyfikatora klienta aplikacji: AppClientId |
ApplicationClientId | Wartość ciągu, która udostępnia identyfikator klienta aplikacji do użycia podczas uwierzytelniania. |
| Alias klucza aplikacji: AppKey |
ApplicationKey | Wartość ciągu, która udostępnia klucz aplikacji do użycia podczas uwierzytelniania przy użyciu przepływu wpisu tajnego aplikacji. |
| Nazwa aplikacji dla aliasu śledzenia : TraceAppName |
ApplicationNameForTracing | Opcjonalna wartość ciągu zgłaszana do usługi, której nazwy aplikacji należy użyć podczas wewnętrznego śledzenia żądania. |
| Alias tokenu aplikacji: AppToken |
Token aplikacji | Wartość ciągu, która nakazuje klientowi przeprowadzenie uwierzytelniania aplikacji przy użyciu określonego tokenu elementu nośnego. |
| Alias identyfikatora urzędu: TenantId |
Urząd | Wartość ciągu, która zawiera nazwę lub identyfikator dzierżawy, w której zarejestrowano aplikację. Wartość domyślna to microsoft.com. Aby uzyskać więcej informacji, zobacz urząd Microsoft Entra. |
| Aliasy regionów platformy Azure: AzureRegion, Region |
AzureRegion | Wartość ciągu, która zawiera nazwę regionu świadczenia usługi Azure, w którym ma być uwierzytelniane. |
| ManagedServiceIdentity | EmbeddedManagedIdentity | Wartość ciągu, która instruuje klienta, którego tożsamości aplikacji użyć z uwierzytelnianiem tożsamości zarządzanej. Służy system do wskazywania tożsamości przypisanej przez system. Nie można ustawić tej właściwości za pomocą parametry połączenia tylko programowo. |
| Alias nazwy wyróżniającej podmiotu certyfikatu aplikacji: podmiot certyfikatu aplikacji |
ApplicationCertificateSubjectDistinguishedName | Wartość ciągu określająca nazwę wyróżniającą podmiotu certyfikatu aplikacji. |
| Alias nazwy wyróżniającej wystawcy certyfikatu aplikacji: wystawca certyfikatu aplikacji |
ApplicationCertificateIssuerDistinguishedName | Wartość ciągu określająca nazwę wyróżniającą wystawcy certyfikatu aplikacji. |
Obsługiwane kombinacje właściwości na potrzeby uwierzytelniania aplikacji
W przypadku uwierzytelniania aplikacji określ wartość AAD Federated Securitytrue. Następnie wybierz jeden z następujących trybów uwierzytelniania i określ odpowiednie właściwości dla tego trybu.
| Tryb uwierzytelniania | Nazwy właściwości |
|---|---|
| Uwierzytelnianie klucza aplikacji Microsoft Entra | — Identyfikator klienta aplikacji — klucz aplikacji — identyfikator urzędu — nazwa aplikacji do śledzenia (opcjonalnie) |
| Uwierzytelnianie odcisku palca aplikacji Microsoft Entra | — Identyfikator klienta aplikacji — odcisk palca certyfikatu aplikacji — identyfikator urzędu — nazwa aplikacji do śledzenia (opcjonalnie) |
| Microsoft Entra podmiot aplikacji i uwierzytelnianie wystawcy | — Identyfikator klienta aplikacji — nazwa wyróżniająca podmiotu certyfikatu aplikacji — nazwa wyróżniająca wystawcy certyfikatu aplikacji — identyfikator urzędu — region platformy Azure (opcjonalnie) — certyfikat aplikacji SendX5c (opcjonalnie) — nazwa aplikacji do śledzenia (opcjonalnie) |
| Uwierzytelnianie nazwy podmiotu aplikacji Microsoft Entra | — Identyfikator klienta aplikacji — nazwa wyróżniająca podmiotu certyfikatu aplikacji — identyfikator urzędu i region platformy Azure (opcjonalnie) — nazwa aplikacji do śledzenia (opcjonalnie) |
| Microsoft Entra uwierzytelnianie tokenu aplikacji | — Token aplikacji — nazwa aplikacji do śledzenia (opcjonalnie) |
Uwierzytelnianie przy użyciu certyfikatu aplikacji
- Aplikacja powinna być skonfigurowana do akceptowania danego certyfikatu. Jak uwierzytelniać na podstawie certyfikatu Microsoft Entra aplikacji.
- Aplikacja powinna być skonfigurowana jako autoryzowana jednostka w odpowiednim klastrze Kusto.
- Certyfikat należy zainstalować w magazynie komputera lokalnego lub w magazynie bieżących użytkowników.
- Klucz publiczny certyfikatu powinien zawierać co najmniej 2048 bitów.
Właściwości komunikacji klienta
| Nazwa właściwości | Nazwa programowa | Opis |
|---|---|---|
| Zaakceptuj | Zaakceptuj | Wartość logiczna, która żąda zwrócenia szczegółowych obiektów błędów po awarii. |
| Przesyłanie strumieniowe | Przesyłanie strumieniowe | Wartość logiczna, która żąda, aby klient nie gromadził danych przed dostarczeniem go do elementu wywołującego. Jest to zachowanie domyślne. |
| Nieskompresowane | Nieskompresowane | Wartość logiczna, która żąda, aby klient nie prosił o kompresję na poziomie transportu. |
Uwaga
Gdy flaga Streaming jest włączona (co jest wartością domyślną), zestaw SDK nie buforuje wszystkich danych odpowiedzi w pamięci. Zamiast tego "ściąga" dane z usługi, gdy obiekt wywołujący żąda. W związku z tym ważne jest, aby w tym przypadku obiekt wywołujący prawidłowo usuwał dane (np IDataReader. ) po zakończeniu odczytywania danych, ponieważ połączenie sieciowe z usługą jest niepotrzebnie utrzymywane.
Przykłady
Microsoft Entra identyfikator uwierzytelniania federacyjnego przy użyciu aktualnie zalogowanej tożsamości użytkownika (w razie potrzeby zostanie wyświetlony monit)
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 identyfikator federacyjnego uwierzytelniania z wskazówką identyfikatora użytkownika (w razie potrzeby zostanie wyświetlony monit)
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 uwierzytelnianie aplikacji federacyjnej przy użyciu identyfikatorów ApplicationClientId i ApplicationKey
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}"
Korzystanie z tożsamości zarządzanej przypisanej przez system
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadSystemManagedIdentity();
Korzystanie z tożsamości zarządzanej przypisanej przez użytkownika
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserManagedIdentity(managedIdentityClientId);
Microsoft Entra identyfikator uwierzytelniania federacyjnego przy użyciu tokenu użytkownika/aplikacji
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}"
Używanie wywołania zwrotnego dostawcy tokenu (będzie wywoływane za każdym razem, gdy token jest wymagany)
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);
Korzystanie z certyfikatu 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);
Przy użyciu certyfikatu X.509 przy użyciu odcisku palca (klient podejmie próbę załadowania certyfikatu z magazynu lokalnego)
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}"
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla