Esercitazione: Analisi del testo persistente con una condivisione di file di Azure montata

Il modulo mounts.bicep configura un mount SMB di Azure Files nell'applicazione funzione. Il mountPath valore determina il percorso locale in cui vengono visualizzati i file in fase di esecuzione. La chiave di accesso dell'account di archiviazione viene passata come parametro e la piattaforma la risolve in fase di esecuzione tramite un riferimento a Key Vault:

@description('Function app name')
param functionAppName string

@description('Storage account name')
param storageAccountName string

@description('Storage account access key or app setting reference for Azure Files SMB mount')
param accessKey string

@description('Array of mount configurations')
param mounts array

// Function app reference
resource functionApp 'Microsoft.Web/sites@2023-12-01' existing = {
  name: functionAppName
}

// Azure Files OS mount configuration
// Deploys azureStorageAccounts site config with all mounts in one shot
resource mountConfig 'Microsoft.Web/sites/config@2023-12-01' = {
  parent: functionApp
  name: 'azurestorageaccounts'
  properties: reduce(mounts, {}, (cur, mount) => union(cur, {
    '${mount.name}': {
      type: 'AzureFiles'
      shareName: mount.shareName
      mountPath: mount.mountPath
      accountName: storageAccountName
      accessKey: accessKey
    }
  }))
}

output mountPaths array = [for mount in mounts: mount.mountPath]

Poiché i montaggi SMB di Azure Files non supportano ancora l'autenticazione tramite identità gestita, è necessaria una chiave dell'account di archiviazione. Come procedura consigliata, archiviare questa chiave in Azure Key Vault e usare un riferimento a Key Vault in un'impostazione dell'app. La configurazione di montaggio fa riferimento all'impostazione dell'app usando @AppSettingRef(), in modo che la chiave non venga mai visualizzata nei modelli Bicep. Il keyvault.bicep modulo crea il vault, archivia la chiave e concede i ruoli di controllo degli accessi in base al ruolo (RBAC):

@description('Key Vault name')
param name string

@description('Location')
param location string

@description('Tags')
param tags object = {}

@description('Storage account name')
param storageAccountName string

@description('Principal ID of the function app identity (receives Key Vault Secrets User role)')
param functionAppPrincipalId string

@description('Principal ID of the deploying user (receives Key Vault Secrets Officer role)')
param deployerPrincipalId string = ''

// Storage account reference
resource storage 'Microsoft.Storage/storageAccounts@2023-05-01' existing = {
  name: storageAccountName
}

// Key Vault with RBAC authorization
resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: name
  location: location
  tags: tags
  properties: {
    sku: {
      family: 'A'
      name: 'standard'
    }
    tenantId: tenant().tenantId
    enableRbacAuthorization: true
    enabledForTemplateDeployment: true
    enableSoftDelete: true
    softDeleteRetentionInDays: 7
  }
}

// Store storage account key as a secret (Azure Files mounts require shared key)
resource storageKeySecret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  parent: keyVault
  name: 'storageAccountKey'
  properties: {
    value: storage.listKeys().keys[0].value
    contentType: 'Storage account access key for Azure Files SMB mount'
  }
}

// Built-in Key Vault RBAC role IDs
var roles = {
  KeyVaultSecretsOfficer: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b86a8fe4-44ce-4948-aee5-eccb2c155cd7')
  KeyVaultSecretsUser: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')
}

// Grant the function app identity read access to secrets
resource functionAppSecretsUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(keyVault.id, functionAppPrincipalId, roles.KeyVaultSecretsUser)
  scope: keyVault
  properties: {
    roleDefinitionId: roles.KeyVaultSecretsUser
    principalId: functionAppPrincipalId
    principalType: 'ServicePrincipal'
  }
}

// Grant the deployer manage access to secrets
resource deployerSecretsOfficer 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (!empty(deployerPrincipalId)) {
  name: guid(keyVault.id, deployerPrincipalId, roles.KeyVaultSecretsOfficer)
  scope: keyVault
  properties: {
    roleDefinitionId: roles.KeyVaultSecretsOfficer
    principalId: deployerPrincipalId
    principalType: 'User'
  }
}

output name string = keyVault.name
output uri string = keyVault.properties.vaultUri
output storageKeySecretUri string = storageKeySecret.properties.secretUri

Il main.bicep file richiama i moduli mount e Key Vault:

// Key Vault for secure storage of Azure Files access key
module keyVault './app/keyvault.bicep' = {
  name: 'keyVault'
  scope: rg
  params: {
    name: !empty(keyVaultName) ? keyVaultName : '${abbrs.keyVaultVaults}${resourceToken}'
    location: location
    tags: tags
    storageAccountName: storage.outputs.name
    functionAppPrincipalId: processorIdentity.outputs.principalId
    deployerPrincipalId: principalId
  }
}

// Azure Files mount configuration (access key resolved via Key Vault reference)
module azureFilesMount './app/mounts.bicep' = {
  name: 'azureFilesMount'
  scope: rg
  params: {
    functionAppName: functionApp.outputs.name
    storageAccountName: storage.outputs.name
    accessKey: '@AppSettingRef(MOUNT_SECRET_REFERENCE)'
    mounts: [
      {
        name: 'data'
        shareName: 'data'
        mountPath: '/mounts/data/'
      }
    ]
  }
  dependsOn: [
    functionAppRoleAssignments
  ]

Dopo azd up aver distribuito l'infrastruttura e il codice, uno script post-distribuzione crea file di testo di esempio, li carica nella condivisione file di Azure ed esegue un controllo di integrità:

# 2. Upload sample text files to Azure Files
# ---------------------------------------------------------------------------
echo "📝 Creating sample text files..."

cat > sample1.txt << 'EOF'
The Azure Functions Flex Consumption plan provides optimal cost-efficiency for
serverless workloads. It automatically scales based on demand and charges only
for the resources actually consumed during execution. This makes it ideal for
workloads with variable traffic patterns, batch processing jobs, and
event-driven architectures where requests can spike unpredictably.

Key benefits include per-second billing, automatic scaling to zero when idle,
and the ability to set maximum instance counts to control costs. The plan
supports multiple language runtimes including Python, Node.js, and .NET.
EOF

cat > sample2.txt << 'EOF'
Durable Functions enable stateful workflows in serverless environments without
requiring developers to manage state persistence manually. The framework
provides several application patterns including function chaining, fan-out and
fan-in, async HTTP APIs, monitoring, and human interaction.

The fan-out/fan-in pattern is particularly powerful for parallel processing
tasks. An orchestrator function can dispatch work to multiple activity functions
simultaneously, wait for all of them to complete, and then aggregate the
results. This is perfect for scenarios like batch processing, map-reduce
operations, and parallel data analysis across multiple files or data sources.
EOF

cat > sample3.txt << 'EOF'
Azure Files provides fully managed file shares in the cloud that are accessible
via the industry-standard SMB and NFS protocols. When mounted as OS-level
shares in Azure Functions Flex Consumption apps, they enable functions to read
and write files using standard filesystem APIs — no SDK or special client needed.

This is especially useful for scenarios that require shared state between
function instances, large binary tools like FFmpeg, or processing pipelines
that work with files on disk. The mount appears as a regular directory path
such as /mounts/data/ and supports concurrent reads from multiple instances.
EOF

echo "⬆️  Uploading sample files to Azure Files share..."
ACCOUNT_KEY=$(az storage account keys list \
  --resource-group "$RESOURCE_GROUP" \
  --account-name "$STORAGE_ACCOUNT" \
  --query "[0].value" -o tsv)

az storage file upload --account-name "$STORAGE_ACCOUNT" --share-name "$FILE_SHARE" --source sample1.txt --account-key "$ACCOUNT_KEY"
az storage file upload --account-name "$STORAGE_ACCOUNT" --share-name "$FILE_SHARE" --source sample2.txt --account-key "$ACCOUNT_KEY"
az storage file upload --account-name "$STORAGE_ACCOUNT" --share-name "$FILE_SHARE" --source sample3.txt --account-key "$ACCOUNT_KEY"

rm -f sample1.txt sample2.txt sample3.txt
echo "✅ Sample text files uploaded to Azure Files."
echo ""

# ---------------------------------------------------------------------------

L'avvio HTTP in function_app.py avvia un'orchestrazione di Durable Functions. L'orchestratore in orchestrator.py elenca tutti i file .txt sul montaggio, si espande per analizzare ogni file in parallelo e aggrega i risultati.

"""Durable Functions orchestrator — fan-out/fan-in text analysis.

The orchestrator reads a list of text files from the Azure Files OS mount,
then fans out to analyse each file in parallel.  Once all activity tasks
complete, it calls an aggregation activity to merge per-file results into
a single summary.
"""

import azure.functions as func
import azure.durable_functions as df

bp = df.Blueprint()


@bp.orchestration_trigger(context_name="context")
def text_analysis_orchestrator(context: df.DurableOrchestrationContext):
    """Fan-out/fan-in orchestrator for text file analysis."""

    input_data = context.get_input()
    mount_path = input_data.get("mount_path", "/mounts/data/")

    # Step 1 — List all text files on the mount.
    file_list: list[str] = yield context.call_activity(
        "list_text_files",
        {"mount_path": mount_path},
    )

    if not file_list:
        return {"error": "No text files found", "mount_path": mount_path}

    # Step 2 — Fan out: analyse each file in parallel.
    #
    # Durable Functions replays the orchestrator deterministically, so
    # context.task_all is safe even for large fan-outs.
    analysis_tasks = [
        context.call_activity(
            "analyse_text_file",
            {"file_path": file_path},
        )
        for file_path in file_list
    ]
    per_file_results: list[dict] = yield context.task_all(analysis_tasks)

    # Step 3 — Aggregate all per-file results into a summary.
    summary: dict = yield context.call_activity(
        "aggregate_results",
        {"results": per_file_results},
    )

    return summary

Ogni funzione di attività legge direttamente dalla condivisione montata usando l'I/O standard del file. Non sono necessarie chiamate di rete o SDK:

# Activity 1 — List text files on the mount
# ---------------------------------------------------------------------------
@bp.activity_trigger(input_name="payload")
def list_text_files(payload: dict) -> list[str]:
    """Return absolute paths of all ``.txt`` files under *mount_path*.

    The mount path comes from the orchestrator and ultimately from the
    ``MOUNT_PATH`` app setting or the HTTP request body.
    """
    mount_path = payload.get("mount_path", "/mounts/data/")
    root = Path(mount_path)

    if not root.exists():
        logger.warning("Mount path %s does not exist — is the share mounted?", mount_path)
        return []

    # Recursively find .txt files; sort for deterministic replay.
    txt_files = sorted(str(p) for p in root.rglob("*.txt") if p.is_file())
    logger.info("Found %d text file(s) in %s", len(txt_files), mount_path)
    return txt_files