Skip to content

configuration.md

Latest commit

 

History

History
202 lines (146 loc) · 5.13 KB

configuration.md

File metadata and controls

202 lines (146 loc) · 5.13 KB

Configuration

Azure Core provides the Configuration class as the standard way to load, store, and share environment and runtime configuration across SDK components.

Configuration API

Get

Checks in-memory cache first, then falls back to System.getProperty and System.getenv (in that order), accepting the first non-null value.

// Get as String
String proxy = configuration.get("HTTP_PROXY");

// Get with default value
String proxy = configuration.get("HTTP_PROXY", "localhost:8888");

// Get and transform to a typed value
URL proxy = configuration.get("HTTP_PROXY", endpoint -> {
    try {
        return new URL(endpoint);
    } catch (MalformedURLException ex) {
        return null;
    }
});

Check Existence

if (configuration.contains("HTTP_PROXY")) {
    String proxy = configuration.get("HTTP_PROXY");
} else {
    configuration.put("HTTP_PROXY", "<default proxy>");
}

Put

Insert a runtime value (bypasses environment lookup):

configuration.put("HTTP_PROXY", "localhost:8888");

Remove

Remove from in-memory cache (causes next get to re-read from the environment):

String removed = configuration.remove("HTTP_PROXY");

Configuration Scoping

Global Configuration

// Shared across the entire application
Configuration global = Configuration.getGlobalConfiguration();
global.put("AZURE_LOG_LEVEL", "2"); // affects all SDK components

Scoped Configuration

// Applies only where this instance is passed explicitly
Configuration scopedConfig = new Configuration();
scopedConfig.put("AZURE_CLIENT_CERTIFICATE_PATH", "/my/cert.pem");

BlobServiceClient client = new BlobServiceClientBuilder()
    .configuration(scopedConfig)
    .buildClient();

No-op / Empty Configuration

Use Configuration.NONE to prevent configuration from affecting behavior:

HttpClient httpClient = new NettyAsyncHttpClientBuilder()
    .configuration(Configuration.NONE)
    .build();

Common Environment Variables

Variable Description
AZURE_CLIENT_ID Service principal / managed identity client ID
AZURE_CLIENT_SECRET Service principal client secret
AZURE_CLIENT_CERTIFICATE_PATH Path to PEM/PFX certificate
AZURE_TENANT_ID Azure AD tenant ID
AZURE_SUBSCRIPTION_ID Azure subscription ID
HTTP_PROXY / HTTPS_PROXY Proxy URL (e.g. http://proxy:8080)
NO_PROXY Comma-separated list of hosts to bypass proxy
AZURE_LOG_LEVEL Logging level: 1=verbose, 2=info, 3=warn, 4=error
AZURE_TELEMETRY_DISABLED Set to true to disable telemetry
AZURE_TEST_MODE PLAYBACK, RECORD, or LIVE for tests

Configure HTTP Clients

NettyAsyncHttpClient (default)

The default HTTP client uses Reactor Netty. Customize via NettyAsyncHttpClientBuilder:

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-netty</artifactId>
  <version>1.15.0</version>
</dependency>

Connection Pool (ConnectionProvider)

ConnectionProvider connectionProvider = ConnectionProvider.builder("custom")
    .maxConnections(500)           // default: 500
    .maxIdleTime(Duration.ofSeconds(60))
    .maxLifeTime(Duration.ofMinutes(10))
    .pendingAcquireMaxCount(1000)  // default: 1000
    .pendingAcquireTimeout(Duration.ofSeconds(45))
    .build();

HttpClient nettyClient = new NettyAsyncHttpClientBuilder()
    .connectionProvider(connectionProvider)
    .build();

When specifying maxConnections without a ConnectionProvider, it defaults to max(16, 2 × available processors) and pendingAcquireMaxCount defaults to 2 × maxConnections.

Proxy

ProxyOptions proxy = new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("proxy", 8080))
    .setCredentials("username", "password");

HttpClient nettyClient = new NettyAsyncHttpClientBuilder()
    .proxy(proxy)
    .build();

OkHttp Client

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-okhttp</artifactId>
  <version>1.12.0</version>
</dependency>
HttpClient okHttpClient = new OkHttpAsyncHttpClientBuilder().build();

BlobServiceClient client = new BlobServiceClientBuilder()
    .httpClient(okHttpClient)
    .buildClient();

Use the Client in a Service Builder

BlobServiceClient client = new BlobServiceClientBuilder()
    .httpClient(nettyClient)
    .buildClient();

Retry Configuration

Retries are handled automatically by the retry policy in the HTTP pipeline. To customize:

RetryOptions retryOptions = new RetryOptions(new ExponentialBackoffOptions()
    .setMaxRetries(3)
    .setBaseDelay(Duration.ofMillis(800))
    .setMaxDelay(Duration.ofSeconds(8)));

BlobServiceClient client = new BlobServiceClientBuilder()
    .retryOptions(retryOptions)
    .buildClient();

See Also