Azure Health Data Services: The Complete Guide for FHIR R4 in Healthcare Production (2026)

# Using Azure CLI
az healthcareapis workspace create \
  --name "myhealthworkspace" \
  --resource-group "healthcare-rg" \
  --location "eastus"

resource healthWorkspace 'Microsoft.HealthcareApis/workspaces@2022-06-01' = {
  name: workspaceName
  location: location
  properties: {}
}
 
resource fhirService 'Microsoft.HealthcareApis/workspaces/fhirservices@2022-06-01' = {
  name: '${workspaceName}/${fhirServiceName}'
  location: location
  kind: 'fhir-R4'
  identity: {
    type: 'SystemAssigned'  // Required for SMART on FHIR
  }
  properties: {
    authenticationConfiguration: {
      authority: 'https://login.microsoftonline.com/${tenantId}'
      audience: 'https://${workspaceName}-${fhirServiceName}.fhir.azurehealthcareapis.com'
      smartProxyEnabled: true  // Enable SMART on FHIR
    }
    corsConfiguration: {
      allowedOrigins: ['https://yourapp.com']
      allowedHeaders: ['*']
      allowedMethods: ['DELETE', 'GET', 'OPTIONS', 'PATCH', 'POST', 'PUT']
      maxAge: 1440
    }
    exportConfiguration: {
      storageAccountName: exportStorageAccount.name  // For bulk $export
    }
  }
}

# Get the FHIR Service resource ID
FHIR_SERVICE_ID=$(az healthcareapis fhir-service show \
  --name fhir-service \
  --workspace-name myhealthworkspace \
  --resource-group healthcare-rg \
  --query id -o tsv)
 
# Assign FHIR Data Reader to a managed identity
az role assignment create \
  --role "FHIR Data Reader" \
  --assignee $SERVICE_PRINCIPAL_OBJECT_ID \
  --scope $FHIR_SERVICE_ID

using Azure.Identity;
using Hl7.Fhir.Rest;
using Hl7.Fhir.Model;
 
public class AzureFhirClient
{
    private readonly FhirClient _client;
 
    public AzureFhirClient(string fhirBaseUrl, string tenantId, 
                            string clientId, string clientSecret)
    {
        // Use Azure.Identity for token acquisition
        var credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
        
        var settings = new FhirClientSettings
        {
            PreferredFormat = ResourceFormat.Json,
            VerifyFhirVersion = false
        };
        
        _client = new FhirClient(fhirBaseUrl, settings);
        
        // Inject Azure AD token as Bearer for each request
        _client.RequestHeaders.Authorization = new AuthenticationHeaderValue(
            "Bearer",
            credential.GetToken(new TokenRequestContext(
                new[] { $"{fhirBaseUrl}/.default" }
            )).Token
        );
    }
    
    public async Task<Patient?> GetPatientAsync(string patientId)
    {
        return await _client.ReadAsync<Patient>($"Patient/{patientId}");
    }
    
    public async Task<Bundle> SearchObservationsAsync(string patientId, string loincCode)
    {
        return await _client.SearchAsync<Observation>(new SearchParams()
            .Where($"patient=Patient/{patientId}")
            .Where($"code=http://loinc.org|{loincCode}")
            .OrderBy("date", SortOrder.Descending)
            .LimitTo(50));
    }
}

import httpx
import asyncio
import time
 
async def run_bulk_export(
    fhir_base_url: str, 
    access_token: str,
    resource_types: list[str],
    output_container_url: str
) -> list[dict]:
    """
    Run a system-level bulk export to Azure Blob Storage.
    Returns list of output file information.
    """
    
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Accept": "application/fhir+json",
        "Prefer": "respond-async"
    }
    
    params = {
        "_type": ",".join(resource_types),
        "_outputFormat": "application/fhir+ndjson",
        "_container": output_container_url  # Azure Blob container URL
    }
    
    # Initiate export
    response = await httpx.get(f"{fhir_base_url}/$export", 
                                headers=headers, params=params)
    
    assert response.status_code == 202, f"Export initiation failed: {response.text}"
    status_url = response.headers["Content-Location"]
    
    # Poll for completion
    while True:
        status_response = await httpx.get(status_url, headers=headers)
        
        if status_response.status_code == 202:
            progress = status_response.headers.get("X-Progress", "processing")
            print(f"Export status: {progress}")
            await asyncio.sleep(30)
            
        elif status_response.status_code == 200:
            result = status_response.json()
            return result.get("output", [])
            
        else:
            raise Exception(f"Export failed: {status_response.text}")

import json
from azure.storage.blob import BlobServiceClient
 
async def process_fhir_export(
    storage_connection_string: str,
    container_name: str,
    blob_path: str
) -> list[dict]:
    """Stream NDJSON file from blob storage, parse each FHIR resource."""
    
    blob_service = BlobServiceClient.from_connection_string(storage_connection_string)
    blob_client = blob_service.get_blob_client(container_name, blob_path)
    
    resources = []
    
    # Stream blob content to handle large files without loading into memory
    downloader = blob_client.download_blob()
    
    buffer = ""
    async for chunk in downloader.chunks():
        buffer += chunk.decode("utf-8")
        lines = buffer.split("\n")
        buffer = lines[-1]  # Keep incomplete last line in buffer
        
        for line in lines[:-1]:
            if line.strip():
                resource = json.loads(line)
                resources.append(resource)
    
    # Process remaining buffer
    if buffer.strip():
        resources.append(json.loads(buffer))
    
    return resources

// Device Mapping Template (MedTech device-to-FHIR mapping)
{
  "templateType": "CollectionContent",
  "template": [
    {
      "templateType": "JsonPathContent",
      "template": {
        "typeName": "heartrate",
        "typeMatchExpression": "$..[?(@.heartRate)]",
        "deviceIdExpression": "$.deviceId",
        "timestampExpression": "$.timestamp",
        "values": [
          {
            "required": true,
            "valueExpression": "$.heartRate",
            "valueName": "hr"
          }
        ]
      }
    }
  ]
}

// FHIR Mapping Template (normalized measurement to FHIR Observation)
{
  "templateType": "CollectionFhir",
  "template": [
    {
      "templateType": "CodeValueFhir",
      "template": {
        "codes": [
          {
            "code": "8867-4",
            "system": "http://loinc.org",
            "display": "Heart rate"
          }
        ],
        "periodInterval": 0,
        "typeName": "heartrate",
        "value": {
          "defaultPeriod": 5000,
          "unit": "/min",
          "valueName": "hr",
          "valueType": "Quantity"
        }
      }
    }
  ]
}

using Polly;
using Polly.Extensions.Http;
 
// Configure retry with exponential backoff for transient FHIR API failures
var retryPolicy = HttpPolicyExtensions
    .HandleTransientHttpError()
    .WaitAndRetryAsync(
        retryCount: 3,
        sleepDurationProvider: attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt)),
        onRetry: (outcome, timespan, attempt, context) =>
        {
            logger.LogWarning("FHIR request retry {Attempt} after {Delay}ms: {StatusCode}",
                attempt, timespan.TotalMilliseconds, outcome.Result?.StatusCode);
        });
 
// Circuit breaker to stop hammering FHIR when it is degraded
var circuitBreakerPolicy = HttpPolicyExtensions
    .HandleTransientHttpError()
    .CircuitBreakerAsync(
        handledEventsAllowedBeforeBreaking: 5,
        durationOfBreak: TimeSpan.FromSeconds(30));
 
// Combine policies
var combinedPolicy = Policy.WrapAsync(retryPolicy, circuitBreakerPolicy);

// Structured logging for FHIR operations
public async Task<T?> ExecuteFhirOperationAsync<T>(
    string operationName, Func<Task<T>> operation) where T : class
{
    using var activity = _activitySource.StartActivity(operationName);
    var stopwatch = Stopwatch.StartNew();
    
    try
    {
        var result = await operation();
        
        _logger.LogInformation("{Operation} completed in {ElapsedMs}ms",
            operationName, stopwatch.ElapsedMilliseconds);
        
        _metrics.RecordFhirOperationDuration(operationName, stopwatch.Elapsed);
        
        return result;
    }
    catch (FhirOperationException ex)
    {
        _logger.LogError(ex, "{Operation} failed with FHIR status {Status}: {Detail}",
            operationName, ex.Status, ex.Outcome?.ToString());
        throw;
    }
}