Eğitim: Bağlı bir Azure Dosyalar depolamasıyla dayanıklı metin analizi

Bu öğreticide, paralel metin dosyası analizini yönetmek için Dayanıklı İşlevler kullanan bir Python Azure İşlevleri uygulaması dağıtacaksınız. İşlev uygulamanız bir Azure Dosyalar paylaşımı bağlar, birden çok metin dosyasını paralel olarak analiz eder (fan-out), sonuçları toplar (fan-in) ve arayana döndürür. Bu yaklaşım, depolama bağlamalarının önemli bir avantajını gösterir: istek başına ağ yükü olmadan birden çok işlev örneğinde paylaşılan dosya erişimi.

Bu eğitimde, siz:

  • Dayanıklı İşlevler uygulamasını bağlı bir Azure Dosyalar paylaşımıyla Esnek Tüketim planında dağıtmak için Azure Geliştirici CLI'sini kullanma
  • Örnek metin dosyalarını paralel olarak işlemek için bir orkestrasyon tetikle
  • Toplanan analiz sonuçlarını doğrulama

Note

Bu makalenin kod örnekleri, Azure İşlevleri Flex Consumption with Azure Dosyalar OS Mount Samples GitHub deposunda mevcuttur.

Prerequisites

Bu öğreticideki CLI örnekleri Bash söz dizimini kullanır ve Azure Cloud Shell (Bash) ve Linux/macOS terminallerinde test edilmiştir.

Örnek projeyi başlatma

Bu öğreticinin örnek kodunu Azure Dosyalar OS Bağlama Örnekleri ile Azure İşlevleri Esnek Tüketim GitHub deposunda bulabilirsiniz. durable-text-analysis klasörü, işlev uygulaması kodunu, gerekli Azure kaynaklarını sağlayan bir Bicep şablonunu ve örnek metin dosyalarını karşıya yükleyen dağıtım sonrası betiği içerir.

  1. Bir terminal açın ve depoyu kopyalamak istediğiniz dizine gidin.

  2. Depoyu kopyalayın:

    git clone https://github.com/Azure-Samples/Azure-Functions-Flex-Consumption-with-Azure-Files-OS-Mount-Samples.git

  3. Proje klasörüne gidin:

    cd Azure-Functions-Flex-Consumption-with-Azure-Files-OS-Mount-Samples/durable-text-analysis

  4. azd ortamını başlatın. İstendiğinde, durable-text gibi örneğin bir ortam adı girin:

    azd init

Kodu gözden geçirin

Bu örnek çalışmayı mümkün kılan üç ana unsur, bağlamayı gerçekleştiren altyapı, örnek dosyaları yükleyen betik ve analizi yöneten işlev kodudur.

Çalışma zamanında düzenleme şu akışı izler:

  1. /api/start-analysis için HTTP POST, Dayanıklı İşlevler orkestrasyonunu başlatır.
  2. Orkestratör, bağlamadaki tüm list_text_files dosyalarını bulmak için .txt etkinliğini çağırır.
  3. Orchestrator, her dosyayı paralel olarak işlemek için analyse_text_file çağırarak görevleri dağıtır.
  4. Tüm paralel görevler tamamlandıktan sonra düzenleyici, dosya başına ölçümleri tek bir özette birleştirmeyi çağırır aggregate_results .
  5. Toplanan sonuç, düzenleme çıkışı olarak döndürülür.

Modül, mounts.bicep işlev uygulamasında bir Azure Dosyalar SMB bağlamasını yapılandırır. değeri, mountPath dosyaların çalışma zamanında görüntülendiği yerel yolu belirler. Depolama hesabı erişim anahtarını bir parametre olarak geçersiniz ve platform bunu çalışma zamanında bir Key Vault başvurusu ile çözümler.

@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]

Azure Dosyalar SMB bağlamaları henüz yönetilen kimlik doğrulamasını desteklemediğinden bir depolama hesabı anahtarına ihtiyacınız vardır. En iyi uygulama olarak, bu anahtarı Azure Key Vault'ta depolayın ve bir uygulama ayarında Key Vault referansı kullanın. Montaj yapılandırması, @AppSettingRef() kullanarak bu uygulama ayarına başvurur, bu nedenle anahtar hiçbir zaman Bicep şablonlarınızda görünmez. Modül keyvault.bicep kasayı oluşturur, anahtarı depolar ve RBAC rollerini verir.

@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

main.bicep dosyası, bağlama ve Key Vault modüllerini çağırır.


// 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
  ]

Azure Geliştirici CLI'sı kullanarak dağıtma

Bu örnek bir Azure Geliştirici CLI (azd) şablonudur. Tek azd up bir komut altyapı sağlar, işlev kodunu dağıtır ve örnek metin dosyalarını Azure Dosyalar paylaşımına yükler.

  1. Azure'da oturum açın. Dağıtım sonrası betiği Azure CLI komutlarını kullandığından her iki aracı kullanarak kimlik doğrulaması yapmanız gerekir:

    azd auth login
az login

  2. Her şeyi sağlama ve dağıtma:

    azd up

    İstendiğinde, kullanılacak Azure aboneliğini ve konumunu seçin. Komut daha sonra şudur:

    • Bir kaynak grubu, depolama hesabı, Key Vault, Dayanıklı İşlevler yapılandırmasıyla birlikte Flex Consumption işlev uygulaması, Application Insights örneği ve yönetilen kimlik oluşturur.
    • Python işlev kodunu dağıtır
    • Örnek metin dosyalarını Azure Dosyalar paylaşımına yükler
    • Sistem durumu denetimi çalıştırır

    Note

    Azure Dosyalar SMB bağlamaları henüz yönetilen kimlik doğrulamasını desteklemediğinden bir depolama hesabı anahtarına ihtiyacınız vardır. En iyi uygulama olarak, dağıtım bu anahtarı Azure Key Vault'ta depolar ve anahtar uygulama ayarlarında hiçbir zaman gösterilmemesi için bir Key Vault başvurusu kullanır. Bu yaklaşım, merkezi gizli yönetimi, denetim ve anahtar yenileme desteği sağlar.

    Dağıtım birkaç dakika sürer. Tamamlandığında, oluşturulan kaynakların özetini görürsünüz.

  3. Kalan adımlar için kaynak adlarını kabuk değişkenleri olarak kaydedin:

    RESOURCE_GROUP=$(azd env get-value AZURE_RESOURCE_GROUP)
FUNCTION_APP_NAME=$(azd env get-value AZURE_FUNCTION_APP_NAME)
FUNCTION_APP_URL=$(azd env get-value AZURE_FUNCTION_APP_URL)

Orkestrasyonu tetikle

  1. İşlev ana bilgisayar anahtarını alın:

    HOST_KEY=$(az functionapp keys list \
  --resource-group $RESOURCE_GROUP \
  --name $FUNCTION_APP_NAME \
  --query "functionKeys.default" \
  -o tsv)

  2. Orkestrasyonu başlatın. Opsiyonel olarak {"mount_path": "/mounts/data/"} ile varsayılan montaj yolunu geçersiz kılmak için bir JSON gövdesi geçirebilirsiniz.

    curl -s -X POST "${FUNCTION_APP_URL}/api/start-analysis?code=${HOST_KEY}" | jq .

    Yanıt, durumu denetlemek, olayları göndermek veya düzenlemeyi sonlandırmak için kullanabileceğiniz bir örnek kimliği ve yönetim URI'leri içerir:

    {
  "id": "abc123def456",
  "statusQueryGetUri": "https://<your-app>.azurewebsites.net/...",
  "sendEventPostUri": "https://...",
  "terminatePostUri": "https://..."
}

Sonuçları doğrulama

  1. Tetikleyici yanıtından statusQueryGetUri'ü kullanarak orkestrasyon durumunu denetleyin.

    STATUS_URL="<statusQueryGetUri-from-trigger-response>"

curl -s "${STATUS_URL}" | jq .

    Orkestrasyon çalışırken, runtimeStatus halindedir Running. Tamamlandığında yanıt şöyle görünür:

    {
  "instanceId": "abc123def456",
  "runtimeStatus": "Completed",
  "output": {
    "total_files": 3,
    "total_words": 45,
    "total_lines": 12,
    "total_chars": 303,
    "overall_avg_word_length": 4.82,
    "overall_top_characters": [["e", 42], ["t", 38], ["a", 35]],
    "per_file": [
      {
        "file_path": "/mounts/data/sample1.txt",
        "word_count": 15,
        "line_count": 4,
        "char_count": 98,
        "avg_word_length": 5.1,
        "top_characters": [["e", 14], ["t", 12]]
      },
      {
        "file_path": "/mounts/data/sample2.txt",
        "word_count": 18,
        "line_count": 5,
        "char_count": 120,
        "avg_word_length": 4.6,
        "top_characters": [["a", 16], ["e", 15]]
      },
      {
        "file_path": "/mounts/data/sample3.txt",
        "word_count": 12,
        "line_count": 3,
        "char_count": 85,
        "avg_word_length": 4.9,
        "top_characters": [["e", 13], ["t", 11]]
      }
    ]
  }
}

    Uygulama ayrıca durum yanıtını basitleştirilmiş şekilde döndüren kullanışlı bir uç noktayı /api/status/{instance_id}'da sunar.

Tavsiye

İşlev uygulamanız, depolama bağlaması aracılığıyla üç dosyaya da paralel olarak erişir. Uygulamanın istek başına ağ çağrısına ihtiyacı yoktur. İşlev, standart dosya giriş/çıkış işlemlerini kullanarak bunları doğrudan bağlı paylaşımdan okur. Bu yaklaşım, Dayanıklı İşlevler ile birlikte kullanılması durumunda depolama montajlarının gücünü gösterir.

Kaynakları temizle

Devam eden ücretlerden kaçınmak için bu öğretici tarafından oluşturulan tüm kaynakları silin:

azd down --purge

Warning

Bu komut işlev uygulaması, depolama hesabı ve Application Insights örneği dahil olmak üzere kaynak grubunu ve içindeki tüm kaynakları siler.

İlgili içerik

  • Last updated on