Kusto 연결 문자열
Kusto 연결 문자열은 Kusto 클라이언트 애플리케이션이 Kusto 서비스 엔드포인트에 대한 연결을 설정하는 데 필요한 정보를 제공합니다. Kusto 연결 문자열은 ADO.NET 연결 문자열을 본따 만들어졌습니다. 즉, 연결 문자열 선택적으로 단일 URI 접두사로 지정된 이름-값 매개 변수 쌍의 세미콜론으로 구분된 목록입니다.
예를 들어 다음 Kusto 연결 문자열 통신https://help.kusto.windows.net용 서비스 엔드포인트를 지정하는 URI로 시작합니다. 이 URI는 속성에 Data Source 할당됩니다. 다음으로, /Samples 연결 문자열 내에서 기본 데이터베이스를 나타내며 속성에 Initial Catalog 할당됩니다. 마지막으로, 두 개의 다른 속성 Fed 및 Accept는 연결에 대한 추가 구성 또는 사용자 지정 옵션을 제공합니다.
https://help.kusto.windows.net/Samples; Fed=true; Accept=true
참고
- 속성 이름은 대/소문자를 구분하지 않습니다.
- 속성 값은 대/소문자를 구분합니다.
- 이름-값 매개 변수 쌍 간의 공백은 무시됩니다.
- 세미콜론(
;), 작은따옴표(') 또는 큰따옴표(")를 포함하는 속성 값은 큰따옴표로 묶어야 합니다.
여러 Kusto 클라이언트 도구는 ClusterName/InitialCatalog의 약식 형식 @ 을 허용하는 연결 문자열 URI 접두사를 통해 확장을 지원합니다. 예를 들어 이러한 도구는 연결 문자열 @help/Samples 로 변환합니다https://help.kusto.windows.net/Samples; Fed=true.
프로그래밍 방식으로 C# Kusto.Data.KustoConnectionStringBuilder 클래스는 Kusto 연결 문자열을 구문 분석하고 조작할 수 있습니다. 이 클래스는 모든 연결 문자열의 유효성을 검사하고 유효성 검사에 실패할 경우 런타임 예외를 생성합니다. 이 기능은 Kusto SDK의 모든 버전에 있습니다.
신뢰할 수 있는 엔드포인트
Kusto 엔드포인트와의 연결은 해당 엔드포인트를 신뢰할 수 있는 경우에만 설정할 수 있습니다.
Kusto 클라이언트는 서비스에서 호스트 이름 부분을 발급하는 모든 엔드포인트를 신뢰합니다.
instance 경우 DNS 호스트 이름이 로 끝나는 kusto.windows.net엔드포인트입니다.
기본적으로 클라이언트는 다른 엔드포인트에 대한 연결을 설정하지 않습니다. 다른 엔드포인트에 대한 연결을 허용하려면 클래스를 Kusto.Data.Common.KustoTrustedEndpoints 사용하여 신뢰할 수 있는 엔드포인트 목록에 엔드포인트를 추가합니다. 를 사용하여 SetOverridePolicy 기본 정책을 재정의하고 AddTrustedHosts 기존 정책에 새 항목을 추가합니다.
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),
}
);
연결 문자열 속성
다음 표에는 Kusto 연결 문자열 포함할 수 있는 모든 가능한 속성이 나와 있습니다. 테이블은 각 속성에 대한 별칭 이름도 제공합니다. 또한 테이블은 개체의 속성 이름을 Kusto.Data.KustoConnectionStringBuilder 나타내는 각 속성과 연결된 프로그래밍 이름을 나타냅니다.
일반 속성
| 속성 이름 | 프로그래매틱 이름 | 설명 |
|---|---|---|
| Client Version for Tracing | TraceClientVersion | 클라이언트 버전을 추적할 때 이 속성을 사용합니다. |
| 데이터 원본 별칭: Addr, Address, Network Address, Server |
DataSource | Kusto 서비스 엔드포인트를 지정하는 URI입니다. https://mycluster.kusto.windows.net)을 입력합니다. |
| 초기 카탈로그 별칭: 데이터베이스 |
InitialCatalog | 기본적으로 사용할 데이터베이스의 이름입니다. MyDatabase)을 입력합니다. |
| 쿼리 일관성 별칭: QueryConsistency |
QueryConsistency | 를 또는 weakconsistency 로 strongconsistency 설정하여 쿼리를 실행하기 전에 메타데이터와 동기화해야 하는지 확인합니다. |
사용자 인증 속성
| 속성 이름 | 프로그래매틱 이름 | 설명 |
|---|---|---|
| Microsoft Entra ID 페더레이션 보안 별칭: 페더레이션 보안, 페더레이션, 연준, AADFed |
FederatedSecurity | Microsoft Entra 인증을 수행하도록 클라이언트에 지시하는 부울 값입니다. |
| 기관 ID 별칭: TenantId |
Authority | 사용자 테넌트의 이름 또는 ID를 제공하는 문자열 값입니다. 기본값은 microsoft.com입니다. 자세한 내용은 Microsoft Entra 기관을 참조하세요. |
| MFA 별칭 적용: MFA, EnforceMFA |
EnforceMfa | 클라이언트가 다단계 인증 토큰을 획득하도록 지시하는 선택적 부울 값입니다. |
| 사용자 ID 별칭: UID, 사용자 |
UserID | 클라이언트가 표시된 사용자 이름으로 사용자 인증을 수행하도록 지시하는 문자열 값입니다. |
| User Name for Tracing | TraceUserName | 내부적으로 요청을 추적할 때 사용할 사용자 이름을 서비스에 보고하는 선택적 문자열 값입니다. |
| 사용자 토큰 별칭: UsrToken, UserToken |
UserToken | 지정된 전달자 토큰을 사용하여 사용자 인증을 수행하도록 클라이언트에 지시하는 문자열 값입니다. , ApplicationKey및 ApplicationToken를 재정의합니다ApplicationClientId. 지정된 경우 제공된 토큰을 위해 실제 클라이언트 인증 흐름을 건너뜁니다. |
사용자 인증에 지원되는 속성 조합
사용자 인증의 경우 를 로 true지정합니다AAD Federated Security. 그런 다음, 다음 인증 모드 중 하나를 선택하고 해당 모드에 대한 관련 속성을 지정합니다.
| 인증 모드 | 속성 이름 |
|---|---|
| Microsoft Entra 사용자 프롬프트 인증 | - 사용자 ID(선택 사항) - 기관 ID(선택 사항) - MFA 적용(선택 사항) - 추적을 위한 사용자 이름(선택 사항) |
| 사용자 토큰 인증 Microsoft Entra | - 사용자 토큰 - MFA 적용(선택 사항) - 추적을 위한 사용자 이름(선택 사항) |
애플리케이션 인증 속성
| 속성 이름 | 프로그래매틱 이름 | 설명 |
|---|---|---|
| Microsoft Entra ID 페더레이션 보안 별칭: 페더레이션 보안, 페더레이션, 연준, AADFed |
FederatedSecurity | 클라이언트가 Microsoft Entra ID 페더레이션 인증을 수행하도록 지시하는 부울 값입니다. |
| 애플리케이션 인증서 SendX5c 별칭: 애플리케이션 인증서 공용 인증서 보내기, SendX5c |
ApplicationCertificateSendX5c | 주체 이름 및 발급자 기반 인증을 수행하도록 클라이언트에 지시하는 부울 값입니다. |
| 애플리케이션 인증서 지문 별칭: AppCert |
ApplicationCertificateThumbprint | 애플리케이션 클라이언트 인증서 인증 흐름을 사용할 때 사용할 클라이언트 인증서의 지문을 제공하는 문자열 값입니다. |
| 애플리케이션 클라이언트 ID 별칭: AppClientId |
ApplicationClientId | 인증할 때 사용할 애플리케이션 클라이언트 ID를 제공하는 문자열 값입니다. |
| 애플리케이션 키 별칭: AppKey |
ApplicationKey | 애플리케이션 비밀 흐름을 사용하여 인증할 때 사용할 애플리케이션 키를 제공하는 문자열 값입니다. |
| 추적 별칭 에 대한 애플리케이션 이름: TraceAppName |
ApplicationNameForTracing | 내부적으로 요청을 추적할 때 사용할 애플리케이션 이름을 서비스에 보고하는 선택적 문자열 값입니다. |
| 애플리케이션 토큰 별칭: AppToken |
ApplicationToken | 지정된 전달자 토큰을 사용하여 애플리케이션 인증을 수행하도록 클라이언트에 지시하는 문자열 값입니다. |
| 기관 ID 별칭: TenantId |
Authority | 애플리케이션이 등록된 테넌트 이름 또는 ID를 제공하는 문자열 값입니다. 기본값은 microsoft.com입니다. 자세한 내용은 Microsoft Entra 기관을 참조하세요. |
| Azure 지역 별칭: AzureRegion, Region |
AzureRegion | 인증할 Azure 지역의 이름을 제공하는 문자열 값입니다. |
| ManagedServiceIdentity | EmbeddedManagedIdentity | 관리 ID 인증에 사용할 애플리케이션 ID를 클라이언트에 지시하는 문자열 값입니다. 를 사용하여 system 시스템 할당 ID를 나타냅니다. 이 속성은 프로그래밍 방식으로만 연결 문자열 설정할 수 없습니다. |
| 애플리케이션 인증서 주체 고유 이름 별칭: 애플리케이션 인증서 주체 |
ApplicationCertificateSubjectDistinguishedName | 애플리케이션 인증서 주체 고유 이름을 지정하는 문자열 값입니다. |
| 애플리케이션 인증서 발급자 고유 이름 별칭: 애플리케이션 인증서 발급자 |
ApplicationCertificateIssuerDistinguishedName | 애플리케이션 인증서 발급자 고유 이름을 지정하는 문자열 값입니다. |
애플리케이션 인증에 지원되는 속성 조합
애플리케이션 인증의 경우 를 로 true지정합니다AAD Federated Security. 그런 다음, 다음 인증 모드 중 하나를 선택하고 해당 모드에 대한 관련 속성을 지정합니다.
| 인증 모드 | 속성 이름 |
|---|---|
| 애플리케이션 키 인증 Microsoft Entra | - 애플리케이션 클라이언트 ID - 애플리케이션 키 - 기관 ID - 추적을 위한 애플리케이션 이름(선택 사항) |
| 애플리케이션 지문 인증 Microsoft Entra | - 애플리케이션 클라이언트 ID - 애플리케이션 인증서 지문 - 기관 ID - 추적용 애플리케이션 이름(선택 사항) |
| Microsoft Entra 애플리케이션 주체 및 발급자 인증 | - 애플리케이션 클라이언트 ID - 애플리케이션 인증서 주체 고유 이름 - 애플리케이션 인증서 발급자 고유 이름 - 기관 ID - Azure 지역(선택 사항) - 애플리케이션 인증서 SendX5c(선택 사항) - 추적용 애플리케이션 이름(선택 사항) |
| Microsoft Entra 애플리케이션 주체 이름 인증 | - 애플리케이션 클라이언트 ID - 애플리케이션 인증서 주체 고유 이름 - 기관 ID 및 Azure 지역(선택 사항) - 추적용 애플리케이션 이름(선택 사항) |
| Microsoft Entra 애플리케이션 토큰 인증 | - 애플리케이션 토큰 - 추적용 애플리케이션 이름(선택 사항) |
애플리케이션 인증서를 사용한 인증
- 지정된 인증서를 수락하도록 애플리케이션을 구성해야 합니다. Microsoft Entra 애플리케이션의 인증서를 기반으로 인증하는 방법입니다.
- 애플리케이션은 관련 Kusto 클러스터에서 권한 있는 보안 주체로 구성되어야 합니다.
- 인증서는 로컬 머신 저장소 또는 현재 사용자 저장소에 설치해야 합니다.
- 인증서의 공개 키는 2048비트 이상을 포함해야 합니다.
클라이언트 통신 속성
| 속성 이름 | 프로그래매틱 이름 | 설명 |
|---|---|---|
| Accept | Accept | 오류 발생 시 반환할 자세한 오류 개체를 요청하는 부울 값입니다. |
| 스트리밍 | 스트리밍 | 호출자에게 제공하기 전에 클라이언트가 데이터를 누적하지 않도록 요청하는 부울 값입니다. 이는 기본 동작입니다. |
| 미압축 | 미압축 | 클라이언트가 전송 수준 압축을 요청하지 않도록 요청하는 부울 값입니다. |
참고
플래그를 Streaming 사용하도록 설정하면(기본값으로) SDK는 메모리의 모든 응답 데이터를 버퍼링하지 않습니다. 대신 호출자가 요청할 때 서비스에서 데이터를 "끌어오기"합니다. 따라서 이 경우 호출자는 서비스에 대한 네트워크 연결이 불필요하게 열린 상태로 유지되므로 데이터를 읽은 후에는 데이터(예: IDataReader)를 올바르게 삭제해야 합니다.
예제
현재 로그온한 사용자 ID를 사용하여 ID 페더레이션 인증을 Microsoft Entra(필요한 경우 사용자에게 메시지가 표시됨)
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}"
사용자 ID 힌트를 사용하여 ID 페더레이션 인증을 Microsoft Entra(필요한 경우 사용자에게 메시지가 표시됨)
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}"
ApplicationClientId 및 ApplicationKey를 사용하여 ID 페더레이션된 애플리케이션 인증 Microsoft Entra
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}"
시스템이 할당한 관리 ID 사용
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadSystemManagedIdentity();
사용자가 할당한 관리 ID 사용
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserManagedIdentity(managedIdentityClientId);
사용자/애플리케이션 토큰을 사용하여 ID 페더레이션 인증 Microsoft Entra
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}"
토큰 공급자 콜백 사용(토큰이 필요할 때마다 호출)
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 인증서 사용
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 인증서 사용(클라이언트가 로컬 저장소에서 인증서 로드 시도)
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}"
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기