diff --git a/data-explorer/kusto/api/get-started/app-authentication-methods.md b/data-explorer/kusto/api/get-started/app-authentication-methods.md new file mode 100644 index 0000000000..8efa51b9c5 --- /dev/null +++ b/data-explorer/kusto/api/get-started/app-authentication-methods.md @@ -0,0 +1,696 @@ +--- +title: Authentication methods for Kusto client libraries +description: Learn about the different authentication methods that can be used in apps using Kusto client libraries. +ms.reviewer: yogilad +ms.topic: how-to +ms.date: 09/25/2024 +monikerRange: "azure-data-explorer" +#customer intent: To learn about the different authentication methods that can be used in apps. +--- +# App authentication methods + +> [!INCLUDE [applies](../../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../../includes/applies-to-version/azure-data-explorer.md)] + +This documentation provides an overview of the primary methods of authentication methods available for the Kusto client libraries. The provided code snippets demonstrate different approaches to authenticate users and apps, enabling seamless interaction with Kusto clusters. Each method is suitable for different scenarios and requirements. + +Where possible, we recommend using managed identities instead of username and password authentication or connection strings. Managed identities provide a more secure and streamlined approach to authentication. + +In this article, you learn how to authenticate using: + +> [!div class="checklist"] +> +> **Application Principal** +> +> - [Managed Identity authentication](#managed-identity-authentication) +> - [Certificate-Based Authentication](#certificate-based-authentication) +> - [Application key authentication](#application-key-authentication) +> +> **User Principal** +> +> - [Interactive user sign-in authentication](#interactive-user-sign-in-authentication) +> - [Azure Command-Line Interface (CLI) authentication](#azure-command-line-interface-cli-authentication) +> - [Device code authentication](#device-code-authentication) +> +> **Custom Token Provider** +> +> - [Custom token provider for federated Managed Identity credential authentication](#custom-token-provider-for-federated-managed-identity-credential-authentication) +> - [Using Azure TokenCredential authentication](#using-azure-tokencredential-authentication) + +## Prerequisites + +- [Set up your development environment](app-set-up.md) to use the Kusto client library. + +## Application Principal authentication methods + +This section covers the different methods of authenticating using an application principal. + +### Managed Identity authentication + +There are two types of managed identities: system-assigned and user-assigned. System-assigned managed identities have their lifecycle tied to the resource that created them. This identity is restricted to only one resource. User-assigned managed identities can be used on multiple resources. For more information, see [Managed Identities](/entra/identity/managed-identities-azure-resources/overview). + +| In the following examples, replace *``* and *``* with your own values. + +- System-assigned managed identity: + + #### [C\#](#tab/csharp) + + ```csharp + var kcsb = new KustoConnectionStringBuilder() + .WithAadSystemManagedIdentity(); + ``` + + #### [Python](#tab/python) + + ```python + kcsb = KustoConnectionStringBuilder + .with_aad_managed_service_identity_authentication() + ``` + + #### [TypeScript](#tab/typescript) + + ```typescript + const kcsb = KustoConnectionStringBuilder + .withSystemManagedIdentity(); + ``` + + #### [Java](#tab/java) + + ```java + ConnectionStringBuilder kcsb = ConnectionStringBuilder + .createWithAadManagedIdentity(); + ``` + + --- + +- User-assigned managed identity. Use the identity client ID or object ID, as follows: + + #### [C\#](#tab/csharp) + + ```csharp + var kcsb = new KustoConnectionStringBuilder() + .WithAadUserManagedIdentity(); + ``` + + #### [Python](#tab/python) + + ```python + kcsb = KustoConnectionStringBuilder + .with_aad_managed_service_identity_authentication(, client_id=) + ``` + + > [!NOTE] + > To use an object ID instead of a client ID, use the `object_id` parameter. + + #### [TypeScript](#tab/typescript) + + ```typescript + const kcsb = KustoConnectionStringBuilder + .withUserManagedIdentity(, ); + ``` + + #### [Java](#tab/java) + + ```java + ConnectionStringBuilder kcsb = ConnectionStringBuilder + .createWithAadManagedIdentity(, ); + ``` + + --- + +> [!IMPORTANT] +> +> - The object, or principal, ID of the Managed Identity resource must be assigned a role to access the Kusto cluster. You can do this in the Azure portal in your Kusto cluster resource page under **Security + networking** > **Permissions**. Managed Identity should not be attached directly to the Kusto cluster. +> - Managed Identity authentication is not supported in local development environments. To test Managed Identity authentication, deploy the application to Azure or use a different authentication method when working locally. + +### Certificate-based authentication + +Certificates can serve as secrets to authenticate an application's identity when requesting a token. There are several methods to load the certificate, such as loading it from the machine's local credentials store or from disk. + +| In the following examples, replace *``*, *``*, *``*, *``*, *``*, *``*, *``*, *``*, *``*, *``*, *``*, and *``* with your own values. + +- Certificate from the machine's local certificate store is only supported using C#: + + ```csharp + var kcsb = new KustoConnectionStringBuilder() + .WithAadApplicationSubjectAndIssuerAuthentication(, , , ); + ``` + + > [!IMPORTANT] + > When using subject name and issuer, the certificate must be installed in the local machine's certificate store. + +- Certificate from an arbitrary source, such as a file on disk, cache, or secure store like Azure Key Vault. The certificate object must contain a private key: + + #### [C\#](#tab/csharp) + + ```csharp + X509Certificate2 certificate = ; + var kcsb = new KustoConnectionStringBuilder() + .WithAadApplicationCertificateAuthentication(, certificate, ); + ``` + + #### [Python](#tab/python) + + - Certificate loaded in memory: + + ```python + kcsb = KustoConnectionStringBuilder + .with_aad_application_certificate_authentication(, , , , ) + ``` + + - Subject and Issuer (SNI) authentication: + + ```python + kcsb = KustoConnectionStringBuilder + .with_aad_application_certificate_sni_authentication(, , , , , ) + ``` + + #### [TypeScript](#tab/typescript) + + - Certificate loaded in memory, such as from a file: + + ```typescript + const certificate: string = await fs.promises.readFile(, "utf8"); + const kcsb = KustoConnectionStringBuilder + .withAadApplicationCertificateAuthentication(, , certificate, ); + ``` + + - Certificate loaded from a file: + + ```typescript + const kcsb = KustoConnectionStringBuilder + .withAadApplicationCertificateAuthentication(, , undefined, , , ); + ``` + + #### [Java](#tab/java) + + - Certificate loaded in memory: + + ```java + ConnectionStringBuilder kcsb = ConnectionStringBuilder + .createWithAadApplicationCertificate(, , , , ); + ``` + + - Subject and Issuer (SNI) authentication: + + ```java + ConnectionStringBuilder kcsb = ConnectionStringBuilder + .createWithAadApplicationCertificateSubjectNameIssuer(, , , , + ``` + + --- + + For more information, see [Kusto connection strings](../connection-strings/kusto.md). + +> [!IMPORTANT] +> To load certificates from Azure Key Vault, you can use the *Azure.Security.KeyVault.Certificates* [client](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/). + +### Application key authentication + +Application key, also known as an application password, is a secret string that an application uses to authenticate and prove its identity when requesting a token. It serves as a form of credential for the application to access protected resources. The application key is typically generated and assigned by the identity provider or authorization server. It's important to securely manage and protect the application key to prevent unauthorized access to sensitive information or actions. + +| In the following examples, replace *``*, *``*, *``*, *``*, and *``* with your own values. + +- Application key: + + #### [C\#](#tab/csharp) + + ```csharp + var kcsb = new KustoConnectionStringBuilder() + .WithAadApplicationKeyAuthentication(, , ); + ``` + + #### [Python](#tab/python) + + ```python + kcsb = KustoConnectionStringBuilder + .with_aad_application_key_authentication(, , , ) + ``` + + #### [TypeScript](#tab/typescript) + + ```typescript + const kcsb = KustoConnectionStringBuilder + .withAadApplicationKeyAuthentication(, , , ); + ``` + + #### [Java](#tab/java) + + ```java + ConnectionStringBuilder kcsb = ConnectionStringBuilder + .createWithAadApplicationCredentials(, , , ); + ``` + + --- + +- Connection string with application key: + + #### [C\#](#tab/csharp) + + ```csharp + var connectionString = "Data Source=;Initial Catalog=NetDefaultDB;AAD Federated Security=True;AppClientId=;AppKey=;Authority Id=;" + var kcsb = new KustoConnectionStringBuilder(connectionString); + ``` + + #### [Python](#tab/python) + + ```python + connectionString = "Data Source=;Initial Catalog=NetDefaultDB;AAD Federated Security=True;AppClientId=;AppKey=;Authority Id=" + kcsb = KustoConnectionStringBuilder(connectionString) + ``` + + #### [TypeScript](#tab/typescript) + + ```typescript + const connectionString = "Data Source=;Initial Catalog=NetDefaultDB;AAD Federated Security=True;AppClientId=;AppKey=;Authority Id="; + const kcsb = new KustoConnectionStringBuilder(connectionString) + ``` + + #### [Java](#tab/java) + + ```java + String connectionString = "Data Source=;AppClientId=;AppKey=;Authority Id="; + ConnectionStringBuilder kcsb = new ConnectionStringBuilder(connectionString); + ``` + + --- + +> [!IMPORTANT] +> Hard-coding secrets in your code is considered a bad practice. Storing sensitive information, such as authentication credentials, in plain text can lead to security vulnerabilities. We recommended that you keep sensitive information encrypted or store them securely in a key vault. By using encryption or a key vault, you can ensure that your secrets are protected and only accessible to authorized users or applications. + +## User Principal authentication methods + +This section covers the different methods of authenticating using a user principal. + +### Interactive user sign-in authentication + +This authentication method uses the user's credentials to establish a secure connection with Kusto. The method opens a web browser where the user is prompted to enter their username and password to complete the authentication process. + +| In the following examples, replace *``* ,*``*, and *``* with your own values. + +- Interactive user sign-in: + + #### [C\#](#tab/csharp) + + ```csharp + var kcsb = new KustoConnectionStringBuilder() + .WithAadUserPromptAuthentication(); + ``` + + #### [Python](#tab/python) + + ```python + kcsb = KustoConnectionStringBuilder + .with_interactive_login() + ``` + + #### [TypeScript](#tab/typescript) + + ```typescript + const kcsb = KustoConnectionStringBuilder + .createWithUserPrompt(, {tenantId: }); + ``` + + #### [Java](#tab/java) + + ```java + ConnectionStringBuilder kcsb = ConnectionStringBuilder + .createWithAadApplicationCredentials(, ); + ``` + + --- + +### Azure Command-Line Interface (CLI) authentication + +This authentication method uses the Azure Command-Line Interface (CLI) to authenticate and obtain a token for the user. Running the `az login` command means the user can securely establish a connection and retrieve the necessary token for authentication purposes. The user might be prompted to sign in if the token isn't available in the Azure CLI cache and the `interactive` parameter is set to `true`. For more information, see [Azure Command-Line Interface (CLI)](/cli/azure/). + +| In the following example, replace *``* with your own value. + +#### [C\#](#tab/csharp) + +```csharp +var kcsb = new KustoConnectionStringBuilder() + .WithAadAzCliAuthentication(interactive: true); +``` + +#### [Python](#tab/python) + +```python +kcsb = KustoConnectionStringBuilder + .with_az_cli_authentication() +``` + +#### [TypeScript](#tab/typescript) + +```typescript +const kcsb = KustoConnectionStringBuilder + .withAzLoginIdentity(); +``` + +#### [Java](#tab/java) + +```java +ConnectionStringBuilder kcsb = ConnectionStringBuilder + .createWithAzureCli(); +``` + +--- + +> [!IMPORTANT] +> This method is only supported for .NET Framework apps. + +### Device code authentication + +This method is designed for devices lacking a proper user interface for sign-in, such as IoT devices and server terminals. It provides the user with a code and a URL to authenticate using a different device, such as a smartphone. This interactive method requires the user to sign in through a browser. + +| In the following example, replace *``* with your own value. + +#### [C\#](#tab/csharp) + +```csharp +var kcsb = new KustoConnectionStringBuilder() + .WithAadDeviceCodeAuthentication((msg, uri, code) => + { + // The callback is used to display instructions to the user on how to authenticate using the device code + Console.WriteLine("Device Code Message: {0}", msg); + Console.WriteLine("Device Code Uri: {0}", uri); + Console.WriteLine("Device Code: {0}", code); + + return Task.CompletedTask; + }); +``` + +#### [Python](#tab/python) + +```python +kcsb = KustoConnectionStringBuilder + .with_aad_device_authentication() +``` + +#### [TypeScript](#tab/typescript) + +```typescript +const kcsb = KustoConnectionStringBuilder + .withAadDeviceAuthentication(); +``` + +#### [Java](#tab/java) + +```java +ConnectionStringBuilder kcsb = ConnectionStringBuilder + .createWithDeviceCode(); +``` + +--- + +> [!IMPORTANT] +> Device code authentication may be blocked by tenant Conditional Access Policies. +> If this occurs, select an alternative authentication method. + +## Custom token provider authentication methods + +This section covers the different methods of authenticating using a custom token provider. + +### Custom token provider for federated Managed Identity credential authentication + +Custom token providers can be used to acquire a Microsoft Entra ID token for authentication. The following example demonstrates how to use a custom token provider to obtain a token using federated managed identity. You can modify the code to fit your application's requirements. + +| In the following example, replace *``*, *``*, *``*, and *``* with your own values. + +#### [C\#](#tab/csharp) + +```csharp +public class TokenProvider +{ + private ClientAssertionCredential m_clientAssertion; + private TokenRequestContext m_tokenRequestContext; + + public TokenProvider(string queryEndpointUri) + { + string resourceId = null; + + try + { + // Get the appropiate resource id by querying the metadata + var httpClient = new HttpClient(); + var response = httpClient.GetByteArrayAsync($"{queryEndpointUri}/v1/rest/auth/metadata").Result; + var json = JObject.Parse(Encoding.UTF8.GetString(response)); + resourceId = json["AzureAD"]?["KustoServiceResourceId"]?.ToString(); + // Append scope to resource id + resourceId = !string.IsNullOrWhiteSpace(resourceId) ? $"{resourceId}/.default" : null; + } + catch { /* Handle exception */} + + m_tokenRequestContext = new TokenRequestContext(new string[] { resourceId ?? "https://kusto.kusto.windows.net/.default" }); + + // Create client assertion credential to authenticate with Kusto + m_clientAssertion = new ClientAssertionCredential + ( + , + , + async (token) => + { + // Get Managed Identity token + var miCredential = new ManagedIdentityCredential(); + var miToken = await miCredential.GetTokenAsync(new TokenRequestContext(new[] { + "api://AzureADTokenExchange/.default" + })).ConfigureAwait(false); + return miToken.Token; + } + ); + } + + public async Task GetTokenAsync() + { + var accessToken = await m_clientAssertion.GetTokenAsync(m_tokenRequestContext).ConfigureAwait(false); + return accessToken.Token; + } +} + +var tokenProvider = new TokenProvider(); + +var kcsb = new KustoConnectionStringBuilder() + .WithAadTokenProviderAuthentication( + async () => + { + return await tokenProvider.GetTokenAsync(); + }); +``` + +#### [Python](#tab/python) + +```python +import requests +from azure.identity import ClientAssertionCredential, ManagedIdentityCredential +from azure.kusto.data import KustoConnectionStringBuilder + +class TokenProvider: + def __init__(self, query_endpoint_uri): + self.query_endpoint_uri = query_endpoint_uri + self.resource_id = None + self.token_request_context = None + self.client_assertion = None + self._initialize() + + def _initialize(self): + try: + # Get the appropriate resource id by querying the metadata + response = requests.get(f"{self.query_endpoint_uri}/v1/rest/auth/metadata") + json = response.json() + self.resource_id = json.get("AzureAD", {}).get("KustoServiceResourceId", "https://kusto.kusto.windows.net") + # Append scope to resource id + self.resource_id = f"{self.resource_id}/.default" + except Exception as error: + print(f"Error fetching metadata: {error}") + + self.token_request_context = {"scopes": [self.resource_id or "https://kusto.kusto.windows.net/.default"]} + + # Create client assertion credential to authenticate with Kusto + self.client_assertion = ClientAssertionCredential( + tenant_id="" + client_id="", + func=self._get_managed_identity_token + ) + + async def _get_managed_identity_token(self): + mi_credential = ManagedIdentityCredential() + mi_token = await mi_credential.get_token("api://AzureADTokenExchange/.default") + return mi_token.token + + async def get_token_async(self): + access_token = await self.client_assertion.get_token(self.token_request_context) + return access_token.token + +def main(): + query_endpoint_uri = "" + token_provider = TokenProvider(query_endpoint_uri) + kcsb = KustoConnectionStringBuilder.with_token_provider( + query_endpoint_uri, + token_provider.get_token_async + ) +``` + +#### [TypeScript](#tab/typescript) + +```typescript +import { ManagedIdentityCredential, ClientAssertionCredential } from '@azure/identity'; +import get from 'axios'; +import { KustoConnectionStringBuilder } from 'azure-kusto-data'; + +class TokenProvider { + constructor(queryEndpointUri) { + this.queryEndpointUri = queryEndpointUri; + this.resourceId = null; + this.tokenRequestContext = null; + this.clientAssertion = null; + } + + async initialize() { + try { + // Get the appropriate resource id by querying the metadata + const response = await get(`${this.queryEndpointUri}/v1/rest/auth/metadata`); + const json = response.data; + this.resourceId = json.AzureAD?.KustoServiceResourceId || 'https://kusto.kusto.windows.net'; + // Append scope to resource id + this.resourceId = `${this.resourceId}/.default`; + } catch (error) { + console.error('Error fetching metadata:', error); + } + + this.tokenRequestContext = { scopes: [this.resourceId || 'https://kusto.kusto.windows.net/.default'] }; + + // Create client assertion credential to authenticate with Kusto + this.clientAssertion = new ClientAssertionCredential( + '', // tenantId + '', // clientId + async () => { + const miCredential = new ManagedIdentityCredential(); + const miToken = await miCredential.getToken({ scopes: ['api://AzureADTokenExchange/.default'] }); + return miToken.token; + } + ); + } + + async getTokenAsync() { + const accessToken = await this.clientAssertion.getToken(this.tokenRequestContext); + return accessToken.token; + } +} + +const tokenProvider = new TokenProvider(""); +await tokenProvider.initialize(); + +const kcsb = KustoConnectionStringBuilder.withAadTokenProviderAuthentication( + "", + async () => { + return await tokenProvider.getTokenAsync(); + } +); +``` + +#### [Java](#tab/java) + +```java +public class TokenProvider { + private TokenRequestContext tokenRequestContext; + private ClientAssertionCredential clientAssertion; + + public TokenProvider(String queryEndpointUri) { + String resourceId = ""; + try { + // Get the appropriate resource id by querying the metadata + URL url = new URL(queryEndpointUri + "/v1/rest/auth/metadata"); + HttpURLConnection conn = (HttpURLConnection) url.openConnection(); + conn.setRequestMethod("GET"); + conn.connect(); + + Scanner scanner = new Scanner(url.openStream(), StandardCharsets.UTF_8); + String jsonResponse = scanner.useDelimiter("\\A").next(); + scanner.close(); + + ObjectMapper mapper = new ObjectMapper(); + JsonNode jsonNode = mapper.readTree(jsonResponse); + resourceId = jsonNode.path("AzureAD").path("KustoServiceResourceId").asText("https://kusto.kusto.windows.net"); + // Append scope to resource id + resourceId = resourceId + "/.default"; + } catch (IOException e) { + System.err.println("Error fetching metadata: " + e.getMessage()); + resourceId = "https://kusto.kusto.windows.net/.default"; + } + + tokenRequestContext = new TokenRequestContext().addScopes(resourceId); + + // Create client assertion credential to authenticate with Kusto + clientAssertion = new ClientAssertionCredential( + "", + "", // clientId + () -> { + ManagedIdentityCredential miCredential = new ManagedIdentityCredential(); + return miCredential.getToken(new TokenRequestContext().addScopes("api://AzureADTokenExchange/.default")).block().getToken(); + } + ); + } + + public CompletableFuture getTokenAsync() { + return clientAssertion.getToken(tokenRequestContext).thenApply(token -> token.getToken()); + } +} + +TokenProvider tokenProvider = new TokenProvider(""); +ConnectionStringBuilder kcsb = ConnectionStringBuilder.createWithAadTokenProviderAuthentication(queryEndpointUri,tokenProvider::getTokenAsync); +``` + +--- + +### Using Azure TokenCredential authentication + +Create a custom token provider by creating a class that inherits from `TokenCredential` and implements the `GetToken` method. Alternatively, you can use an existing token provider like `DefaultAzureCredential`. This method provides flexibility for different authentication scenarios when a custom token provider is required. + +You can use `DefaultAzureCredential` for supporting production code that uses Managed Identity authentication, or testing code using Visual Studio or Azure CLI. `DefaultAzureCredential` can be configured to use different authentication methods. + +| In the following example, replace *``* and *``* with your own values. + +#### [C\#](#tab/csharp) + +```csharp +var credentialProvider = new DefaultAzureCredential(new DefaultAzureCredentialOptions { + ManagedIdentityClientId = + }); +var kcsb = new KustoConnectionStringBuilder() + .WithAadAzureTokenCredentialsAuthentication(credentialProvider); +``` + +#### [Python](#tab/python) + +```python +from azure.identity import DefaultAzureCredential +token_credential = DefaultAzureCredential() +kcsb = KustoConnectionStringBuilder + .with_azure_token_credential(, token_credential) +``` + +#### [TypeScript](#tab/typescript) + +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +const credential = new DefaultAzureCredential(); +const kcsb = KustoConnectionStringBuilder + .withTokenCredential(, credential); +``` + +#### [Java](#tab/java) + +Not supported. + +--- + +> [!NOTE] +> `DefaultAzureCredential` is used to authenticate with Azure services. +> It attempts multiple authentication methods to obtain a token and can be configured to work with Managed Identity, Visual Studio, Azure CLI, and more. +> This credential is suitable for both testing and production environments as it can be set up to use different authentication methods. +> For more information, see [DefaultAzureCredential Class](/dotnet/api/azure.identity.defaultazurecredential). + +## Next step + + +> [!div class="nextstepaction"] +> [Create an app to run basic queries](app-basic-query.md) diff --git a/data-explorer/kusto/api/get-started/app-basic-query.md b/data-explorer/kusto/api/get-started/app-basic-query.md index 75390c9487..552300e5a7 100644 --- a/data-explorer/kusto/api/get-started/app-basic-query.md +++ b/data-explorer/kusto/api/get-started/app-basic-query.md @@ -1,10 +1,11 @@ --- -title: 'Create an app to run basic queries' +title: Create an app to run basic queries description: Learn how to create an app to run basic queries using Kusto client libraries. ms.reviewer: yogilad ms.topic: how-to ms.date: 08/11/2024 monikerRange: "azure-data-explorer" +#customer intent: To learn about creating an app to run basic queries using Kusto client libraries. --- # Create an app to run basic queries @@ -64,7 +65,7 @@ In your preferred IDE or text editor, create a project or file named *basic quer main() ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript import { Client as KustoClient, KustoConnectionStringBuilder } from "azure-kusto-data"; @@ -137,7 +138,7 @@ In your preferred IDE or text editor, create a project or file named *basic quer "| order by DailyDamage desc" ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript const database = "Samples"; @@ -195,7 +196,7 @@ In your preferred IDE or text editor, create a project or file named *basic quer print(row["StartTime"], "-", row["State"], ",", row["DailyDamage"], "$") ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript const response = await kustoClient.execute(database, query); @@ -295,7 +296,7 @@ if __name__ == "__main__": main() ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript import { Client as KustoClient, KustoConnectionStringBuilder } from "azure-kusto-data"; @@ -384,7 +385,7 @@ dotnet run . python basic_query.py ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) In a Node.js environment: @@ -460,7 +461,7 @@ for row in response.primary_results[0]: print(row[start_time_col], "-", row[state_col], ",", row[damage_col], "$") ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript const columnNoState = 0; @@ -526,7 +527,7 @@ crp.set_option(crp.request_timeout_option_name, datetime.timedelta(minutes=1)) response = kusto_client.execute_query(database, query, crp) ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript import { ClientRequestProperties } from "azure-kusto-data"; @@ -623,7 +624,7 @@ for row in response.primary_results[0]: print(row["StartTime"], "-", row["State"], ",", row["DailyDamage"], "$") ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript const query = `declare query_parameters(event_type:string, daily_damage:int); @@ -770,7 +771,7 @@ if __name__ == "__main__": main() ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript import { diff --git a/data-explorer/kusto/api/get-started/app-hello-kusto.md b/data-explorer/kusto/api/get-started/app-hello-kusto.md index bf911af88f..d10d0cc32d 100644 --- a/data-explorer/kusto/api/get-started/app-hello-kusto.md +++ b/data-explorer/kusto/api/get-started/app-hello-kusto.md @@ -1,10 +1,11 @@ --- -title: 'Hello Kusto: Create your first app' +title: Create your first description: Learn how to create your first app to print Hello Kusto using Kusto client libraries. ms.reviewer: yogilad ms.topic: how-to -ms.date: 08/11/2024 +ms.date: 11/28/2024 monikerRange: "azure-data-explorer" +#customer intent: To learn about creating a simple app that prints Hello Kusto using Kusto client libraries. --- # Hello Kusto: Create your first app @@ -41,7 +42,7 @@ In your preferred IDE or text editor, create a project or file named *hello kust from azure.kusto.data import KustoClient, KustoConnectionStringBuilder ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript import { Client as KustoClient, KustoConnectionStringBuilder } from "azure-kusto-data"; @@ -86,7 +87,7 @@ In your preferred IDE or text editor, create a project or file named *hello kust main() ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript async function main() @@ -128,7 +129,7 @@ In your preferred IDE or text editor, create a project or file named *hello kust kcsb = KustoConnectionStringBuilder.with_interactive_login(cluster_uri) ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) The `clientId` and `redirectUri` are from the Microsoft Entra app registration you created in the **Prerequisites** section of [Set up your development environment](app-set-up.md#prerequisites). @@ -179,7 +180,7 @@ In your preferred IDE or text editor, create a project or file named *hello kust with KustoClient(kcsb) as kusto_client: ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript const kustoClient = new KustoClient(kcsb); @@ -212,7 +213,7 @@ In your preferred IDE or text editor, create a project or file named *hello kust query = "print Welcome='Hello Kusto!'" ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript const database = "Samples"; @@ -250,7 +251,7 @@ In your preferred IDE or text editor, create a project or file named *hello kust print(response.primary_results[0][0]["Welcome"]) ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript const response = await kustoClient.execute(database, query); @@ -355,7 +356,7 @@ if __name__ == "__main__": main() ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript import { Client as KustoClient, KustoConnectionStringBuilder } from "azure-kusto-data/"; @@ -432,7 +433,7 @@ dotnet run . python hello_kusto.py ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) In a Node.js environment: @@ -469,4 +470,4 @@ Hello Kusto! > [!div class="nextstepaction"] -> [Create an app to run basic queries](app-basic-query.md) +> [Secure your app](app-authentication-methods.md) diff --git a/data-explorer/kusto/api/get-started/app-management-commands.md b/data-explorer/kusto/api/get-started/app-management-commands.md index 1910a319a9..adf6abdf86 100644 --- a/data-explorer/kusto/api/get-started/app-management-commands.md +++ b/data-explorer/kusto/api/get-started/app-management-commands.md @@ -1,10 +1,11 @@ --- -title: 'Create an app to run management commands' +title: Create an app to run management commands description: Learn how to create an app to run management commands using Kusto client libraries. ms.reviewer: yogilad ms.topic: how-to ms.date: 08/11/2024 monikerRange: "azure-data-explorer" +#customer intent: To learn about creating an app to run management commands using Kusto client libraries. --- # Create an app to run management commands @@ -66,7 +67,7 @@ In your preferred IDE or text editor, create a project or file named *management main() ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript import { Client as KustoClient, KustoConnectionStringBuilder } from "azure-kusto-data/"; @@ -147,7 +148,7 @@ In your preferred IDE or text editor, create a project or file named *management print("\t", col, "-", row[col]) ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript function printResultsAsValueList(command: string, response: KustoResponseDataSet) { @@ -222,7 +223,7 @@ In your preferred IDE or text editor, create a project or file named *management " StormSummary:dynamic)" ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript const database = ""; @@ -284,7 +285,7 @@ In your preferred IDE or text editor, create a project or file named *management print_result_as_value_list(command, response) ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) > [!NOTE] > You'll use the `executeMgmt` method to run the command. @@ -399,7 +400,7 @@ if __name__ == "__main__": main() ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript import { Client as KustoClient, KustoConnectionStringBuilder, KustoResponseDataSet } from "azure-kusto-data/"; @@ -520,7 +521,7 @@ dotnet run . python management_commands.py ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) In a Node.js environment: @@ -598,7 +599,7 @@ response = kusto_client.execute_mgmt(database, command) print_result_as_value_list(command, response) ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript // Reduce the default batching timeout to 30 seconds @@ -667,7 +668,7 @@ response = kusto_client.execute_mgmt(database, command) print_result_as_value_list(command, response) ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript // Show the database retention policy (drop some columns from the result) diff --git a/data-explorer/kusto/api/get-started/app-queued-ingestion.md b/data-explorer/kusto/api/get-started/app-queued-ingestion.md index 127422abc9..c9a83b0de0 100644 --- a/data-explorer/kusto/api/get-started/app-queued-ingestion.md +++ b/data-explorer/kusto/api/get-started/app-queued-ingestion.md @@ -1,10 +1,11 @@ --- -title: Create an app to get data using queued ingestion +title: Create an app to get data using queued ingestion description: Learn how to create an app to get data using queued ingestion of the Kusto client libraries. ms.reviewer: yogilad ms.topic: how-to ms.date: 08/11/2024 monikerRange: "azure-data-explorer" +#customer intent: To learn about creating an app to get data using queued ingestion. --- # Create an app to get data using queued ingestion @@ -159,7 +160,7 @@ Add the following code: main() ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript import { Client as KustoClient, KustoConnectionStringBuilder } from "azure-kusto-data"; @@ -265,7 +266,7 @@ Add the following code: ingest_kcsb = KustoConnectionStringBuilder.with_azure_token_credential(ingest_uri, credentials) ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript import { IngestClient, IngestionProperties, DataFormat } from "azure-kusto-ingest"; @@ -329,7 +330,7 @@ Add the following code: ingest_client.ingest_from_file(file_path, ingest_props) ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript import path from 'path'; @@ -410,7 +411,7 @@ Add the following code: print_result_as_value_list(response) ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript console.log("\nWaiting 30 seconds for ingestion to complete ..."); @@ -580,7 +581,7 @@ if __name__ == "__main__": main() ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript import path from 'path'; @@ -732,7 +733,7 @@ dotnet run . python basic_ingestion.py ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) In a Node.js environment: @@ -802,7 +803,7 @@ For example, you can modify the app replacing the *ingest from file* code, as fo from azure.kusto.ingest import StreamDescriptor ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript import { Readable } from "stream"; @@ -837,7 +838,7 @@ For example, you can modify the app replacing the *ingest from file* code, as fo string_stream = io.StringIO(single_line) ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript const singleLine = '2018-01-26 00:00:00.0000000,2018-01-27 14:00:00.0000000,MEXICO,0,0,Unknown,"{}"'; @@ -872,7 +873,7 @@ For example, you can modify the app replacing the *ingest from file* code, as fo ingest_props = IngestionProperties(database, table, DataFormat.CSV, ignore_first_record=False) ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript ingestProps.ignoreFirstRecord = false; @@ -903,7 +904,7 @@ For example, you can modify the app replacing the *ingest from file* code, as fo ingest_client.ingest_from_stream(stream_descriptor, ingest_props) ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript stringStream.size = singleLine.length; @@ -995,7 +996,7 @@ if __name__ == "__main__": main() ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript import path from 'path'; @@ -1130,7 +1131,7 @@ For example, you can modify the app replacing the *ingest from memory* code with from azure.kusto.ingest import BlobDescriptor ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript No additional packages are required. @@ -1167,7 +1168,7 @@ For example, you can modify the app replacing the *ingest from memory* code with ingest_client.ingest_from_blob(blob_descriptor, ingest_props) ``` - ### [Typescript](#tab/typescript) + ### [TypeScript](#tab/typescript) ```typescript const blobUri = ""; @@ -1263,7 +1264,7 @@ if __name__ == "__main__": main() ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```typescript import path from 'path'; @@ -1372,9 +1373,8 @@ Last ingested row: ## Next step - - +> [!div class="nextstepaction"] +> [App authentication methods](app-authentication-methods.md) > [!div class="nextstepaction"] > [KQL quick reference](../../query/kql-quick-reference.md) diff --git a/data-explorer/kusto/api/get-started/app-set-up.md b/data-explorer/kusto/api/get-started/app-set-up.md index 52cea05cb4..f1df6d1564 100644 --- a/data-explorer/kusto/api/get-started/app-set-up.md +++ b/data-explorer/kusto/api/get-started/app-set-up.md @@ -5,6 +5,7 @@ ms.reviewer: yogilad ms.topic: how-to ms.date: 08/11/2024 monikerRange: "azure-data-explorer" +#customer intent: To learn about setting up your development environment to use Kusto client libraries. --- # Set up your development environment to use Kusto client libraries @@ -38,7 +39,7 @@ Verify installation: In a command shell, run `dotnet sdk check` to check that th - Ensure the `python` executable is in your `PATH` - Verify installation: In a command shell, run `python --version` to check that the version is 3.7 or later -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) - [Node 16 or later](https://nodejs.org/en/download/) built with ES6 - Ensure the `node` executable is in your `PATH` @@ -106,7 +107,7 @@ python -m pip install azure-kusto-data python -m pip install azure-kusto-ingest ``` -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) ```bash npm install azure-kusto-data @@ -169,7 +170,7 @@ The Kusto SDKs contain quick start sample applications. These applications showc [Python Quickstart App](https://github.com/Azure/azure-kusto-python/tree/master/quick_start) -### [Typescript](#tab/typescript) +### [TypeScript](#tab/typescript) - [Node.js Quickstart App](https://github.com/Azure/azure-kusto-node/tree/master/packages/quick_start) - [Browser Quickstart App](https://github.com/Azure/azure-kusto-node/tree/master/packages/quick_start_browser) @@ -187,6 +188,7 @@ The Kusto SDKs contain quick start sample applications. These applications showc The following articles walk you through creating apps that use the Kusto client libraries. - [Create your first app](app-hello-kusto.md) +- [Secure your app](app-authentication-methods.md) - [Create an app to run basic queries](app-basic-query.md) - [Create an app to run management commands](app-management-commands.md) - [Create an app to get data using queued ingestion](app-queued-ingestion.md) diff --git a/data-explorer/kusto/toc.yml b/data-explorer/kusto/toc.yml index 77eeca2594..eda1eb5e65 100644 --- a/data-explorer/kusto/toc.yml +++ b/data-explorer/kusto/toc.yml @@ -86,6 +86,8 @@ items: href: api/get-started/app-set-up.md - name: Create your first app href: api/get-started/app-hello-kusto.md + - name: Secure your app + href: api/get-started/app-authentication-methods.md - name: Run basic queries href: api/get-started/app-basic-query.md - name: Run management commands