Usare sessioni dinamiche in App contenitore di Azure

App contenitore di Azure sessioni dinamiche offrono contesti isolati e sicuri quando hai bisogno di eseguire codice o applicazioni separatamente da altri carichi di lavoro. Le sessioni vengono eseguite all'interno di un pool di sessioni che fornisce l'accesso immediato alle sessioni nuove ed esistenti. Queste sessioni sono ideali per scenari in cui l'input generato dall'utente deve essere elaborato in modo controllato o quando si integrano servizi di terze parti che richiedono l'esecuzione di codice in un ambiente isolato. Non è necessario distribuire una risorsa dell'app contenitore per usare sessioni dinamiche, creare un pool di sessioni e chiamarne l'API di gestione.

Questo articolo illustra come gestire e interagire con le sessioni dinamiche.

Endpoint di gestione e routing

L'applicazione interagisce con una sessione usando l'API di gestione del pool di sessioni. Per una panoramica concettuale del modo in cui vengono instradate le richieste, vedere Concetti chiave.

Per ottenere l'endpoint di gestione del pool di sessioni, vedere Endpoint di gestione dei pool di sessioni.

https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io

Per altre informazioni sulla gestione dei pool di sessioni, vedere Endpoint di gestione dei pool di sessioni.

Autenticazione e autorizzazione dell'API di gestione

Tutte le richieste all'API di gestione del pool di sessioni richiedono l'autenticazione (AuthN) con un token Microsoft Entra e l'autorizzazione (AuthZ) tramite il ruolo Azure ContainerApps Session Executor nel pool di sessioni. Per informazioni dettagliate ed esempi, vedere Autenticazione e autorizzazione.

Inviare richieste a una sessione

Per inviare una richiesta nel contenitore di una sessione, usare l'endpoint di gestione come radice per la richiesta. Qualsiasi elemento nel percorso che segue l'endpoint di gestione del pool di base viene inoltrato al contenitore della sessione.

Ad esempio, se si effettua una chiamata a <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile, la richiesta viene instradata al contenitore di sessione sulla porta di destinazione in <TARGET_PORT>/api/uploadfile.

Esempio di richiesta

Nell'esempio seguente viene illustrato come inviare una richiesta a una sessione usando l'ID di un utente come identificatore di sessione univoco.

Prima di inviare la richiesta, sostituire i segnaposto tra le parentesi <> con valori specifici della richiesta.

POST <POOL_MANAGEMENT_ENDPOINT>/<API_PATH_EXPOSED_BY_CONTAINER>?identifier=<USER_ID>
Authorization: Bearer <TOKEN>
{
  "command": "echo 'Hello, world!'"
}

Questa richiesta viene inoltrata al contenitore nella sessione con l'identificatore per l'ID dell'utente.

Se non esiste alcuna sessione per l'identificatore specificato, App contenitore di Azure alloca automaticamente uno dal pool prima di inoltrare la richiesta.

In questo esempio, il contenitore della sessione riceve una richiesta sulla porta di destinazione in <TARGET_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>.

Identifiers

Per inviare una richiesta HTTP a una sessione, è necessario specificare un identificatore di sessione nella richiesta. Quando si effettua una richiesta a una sessione, si passa l'identificatore di sessione in un parametro della stringa di query denominato identifier nell'URL.

• Se esiste già una sessione con l'identificatore, la richiesta viene inviata alla sessione esistente.

• Se non esiste una sessione con l'identificatore, viene allocata automaticamente una nuova sessione prima dell'invio della richiesta.

Il diagramma seguente illustra come un pool di sessioni instrada le richieste alle sessioni esistenti o alloca una nuova sessione quando necessario.

Formato identificatore

L'identificatore di sessione è una stringa in formato libero, ovvero è possibile definirla in qualsiasi modo che sia adatto alle esigenze dell'applicazione.

L'identificatore di sessione è una stringa definita che è univoca all'interno del pool di sessioni. Se si sta creando un'applicazione Web, è possibile usare l'ID dell'utente come identificatore di sessione. Se si sta creando un chatbot, è possibile usare l'ID conversazione.

L'identificatore deve essere una stringa lunga da 4 a 128 caratteri e può contenere solo caratteri alfanumerici e caratteri speciali da questo elenco: |, -, &, ^, %, $, #, (, ), {, }, [, ], ;, < e >.

Recuperare le informazioni sulla sessione

È possibile eseguire query sul pool di sessioni per controllare lo stato della sessione, ottenere i dettagli di scadenza ed elencare tutte le sessioni attive. Questa funzionalità è utile per monitorare l'integrità delle sessioni, tenere traccia dell'utilizzo delle risorse e implementare flussi di lavoro di pulizia personalizzati.

Ottieni una singola sessione

Per recuperare i dettagli relativi a una sessione specifica, usare l'endpoint getSession :

POST https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io/.management/getSession?identifier=<SESSION_ID>&api-version=2024-02-02-preview
Authorization: Bearer <TOKEN>

L'endpoint getSession restituisce i metadati della sessione, inclusi l'identificatore di sessione, l'ora di scadenza corrente e il timestamp di creazione.

Schema di risposta SessionView

Richiesta e risposta di esempio

curl -X POST "https://my-pool.env-id.westus2.azurecontainerapps.io/.management/getSession?identifier=user-123&api-version=2024-02-02-preview" \
  -H "Authorization: Bearer $TOKEN"

Risposta riuscita (HTTP 200):

{
  "identifier": "user-123",
  "etag": "a1b2c3d4",
  "expiresAt": "2026-04-30T14:30:00Z",
  "createdAt": "2026-04-30T13:30:00Z",
  "lastAccessedAt": "2026-04-30T14:29:00Z"
}

Elencare tutte le sessioni in un pool

Per recuperare un elenco di tutte le sessioni nel pool di sessioni, usare l'endpoint listSessions :

POST https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io/.management/listSessions?skip=0&api-version=2024-02-02-preview
Authorization: Bearer <TOKEN>

Impaginazione

Il punto finale dell'elenco supporta la paginazione basata su skip. Per impostazione predefinita, ogni pagina restituisce fino a 300 sessioni. Usare il skip parametro di query per spostarsi tra i risultati.

Schema di risposta ApiCollectionEnvelope

Ciclo di paginazione di esempio

POOL_URL="https://my-pool.env-id.westus2.azurecontainerapps.io"
next_url="$POOL_URL/.management/listSessions?skip=0&api-version=2024-02-02-preview"

while [ -n "$next_url" ]; do
  response=$(curl -s -X POST "$next_url" \
    -H "Authorization: Bearer $TOKEN")

  echo "$response" | jq '.value[] | {identifier, expiresAt}'

  next_url=$(echo "$response" | jq -r '.nextLink // empty')
done

Risposta di esempio (HTTP 200):

{
  "value": [
    {
      "identifier": "user-123",
      "etag": "a1b2c3d4",
      "expiresAt": "2026-04-30T14:30:00Z"
    },
    {
      "identifier": "user-456",
      "etag": "e5f6a7b8",
      "expiresAt": "2026-04-30T14:31:00Z"
    }
  ],
  "count": 2,
  "nextLink": "https://my-pool.env-id.westus2.azurecontainerapps.io/.management/listSessions?skip=300"
}

Risposte agli errori

Quando si verifica un errore, l'API restituisce una risposta di errore strutturata con i dettagli che consentono di diagnosticare il problema.

{
  "error": {
    "code": "ErrorCode",
    "message": "Human-readable error description",
    "details": "Optional additional context",
    "target": "Field or parameter that caused the error",
    "traceId": "Request trace ID for debugging"
  }
}

Codici di errore comuni

Ciclo di vita della sessione in pratica

Mentre si continua a effettuare chiamate alla stessa sessione, la sessione rimane allocata nel pool. Quando non sono presenti richieste alla sessione dopo che è trascorso il periodo di raffreddamento, la sessione viene eliminata automaticamente.

Sicurezza

Modello di sicurezza

Le sessioni dinamiche vengono create per eseguire codice e applicazioni non attendibili in un ambiente sicuro e isolato. Mentre le sessioni sono isolate l'una dall'altra, qualsiasi elemento all'interno di una singola sessione, inclusi i file e le variabili di ambiente, è accessibile dagli utenti della sessione.

Configurare o caricare dati sensibili in una sessione solo se si considerano attendibili gli utenti della sessione.

Accesso alla rete

Per impostazione predefinita, le sessioni non possono effettuare richieste di rete in uscita. È possibile controllare l'accesso alla rete configurando le impostazioni di stato della rete nel pool di sessioni.

Procedure consigliate

• Identificatori sicuri: usare sempre identificatori di sessione sicuri. Generare identificatori di sessione usando metodi di crittografia per garantire valori univoci e imprevedibili. Evitare di usare ID sequenziali che potrebbero essere indovinati da un utente malintenzionato.
• Usare HTTPS: usare sempre HTTPS per crittografare i dati in transito. In questo modo si proteggono gli identificatori di sessione e i dati sensibili scambiati tra il client e il server dall'essere intercettati.
• Limitare la durata della sessione: implementare timeout per le sessioni. Ad esempio, consentire un massimo di 15 minuti di inattività prima che la sessione venga terminata automaticamente. Ciò consente di attenuare i rischi dovuti a un dispositivo perso o incustodito.
• Limitare la visibilità della sessione: impostare controlli di accesso rigorosi per assicurarsi che gli identificatori di sessione siano visibili solo al pool di sessioni. Evitare di esporre gli ID sessione negli URL o nei log.
• Ruotare regolarmente le credenziali della sessione: esaminare e aggiornare periodicamente le credenziali associate alle sessioni. La rotazione riduce il rischio di accesso non autorizzato.

Indicazioni aggiuntive per le sessioni di contenitori personalizzate

• Usare protocolli di trasmissione sicuri: usare sempre HTTPS per crittografare i dati in transito, inclusi gli identificatori di sessione. Questo approccio protegge dagli attacchi man-in-the-middle.

• Monitorare l'attività di sessione: implementare la registrazione e il monitoraggio per tenere traccia delle attività di sessione. Usare questi log per identificare modelli insoliti o potenziali violazioni della sicurezza.

• Convalida l'input dell'utente: considera tutto l'input degli utenti come pericoloso. Usare tecniche di convalida e sanificazione dell'input per proteggersi dagli attacchi di iniezione e assicurarsi che vengano elaborati solo i dati attendibili.

Autenticazione e autorizzazione

Quando si inviano richieste a una sessione usando l'API di gestione del pool, l'autenticazione viene gestita usando Microsoft Entra token. Solo i token Microsoft Entra di un'identità appartenente al ruolo Esecutore di sessione app contenitore di Azure nel pool di sessioni sono autorizzati a chiamare l'API di gestione del pool.

Per assegnare il ruolo a un'identità, usare il comando interfaccia della riga di comando di Azure seguente:

az role assignment create \
    --role "Azure ContainerApps Session Executor" \
    --assignee <PRINCIPAL_ID> \
    --scope <SESSION_POOL_RESOURCE_ID>

Se si usa un'integrazione del framework LLM (Large Language Model), il framework gestisce automaticamente la generazione e la gestione dei token. Assicurarsi che l'applicazione sia configurata con un'identità gestita con le assegnazioni di ruolo necessarie nel pool di sessioni.

Se si usano direttamente gli endpoint API di gestione del pool, è necessario generare un token e includerlo nell'intestazione Authorization delle richieste HTTP. Oltre alle assegnazioni di ruolo indicate in precedenza, il token deve contenere un'attestazione del gruppo di destinatari (aud) con il valore https://dynamicsessions.io.

az account get-access-token --resource https://dynamicsessions.io

dotnet add package Azure.Identity

using Azure.Identity;

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://dynamicsessions.io/.default" }));
var accessToken = token.Token;

npm install @azure/identity

const { DefaultAzureCredential } = require("@azure/identity");
const { TokenCredential } = require("@azure/core-auth");

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://dynamicsessions.io/.default");
const accessToken = token.token;

pip install azure-identity

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://dynamicsessions.io/.default")
access_token = token.token

Proteggere gli identificatori di sessione

L'identificatore di sessione è costituito da informazioni riservate che è necessario gestire in modo sicuro. L'applicazione deve assicurarsi che ogni utente o tenant abbia accesso solo alle proprie sessioni.

Le strategie specifiche che impediscono l'uso improprio degli identificatori di sessione variano a seconda della progettazione e dell'architettura dell'app. Tuttavia, l'app deve avere sempre il controllo completo sulla creazione e l'uso di identificatori di sessione in modo che un utente malintenzionato non possa accedere alla sessione di un altro utente.

Esempi di strategie includono:

• Una sessione per utente: se l'app usa una sessione per utente, ogni utente deve essere autenticato in modo sicuro e l'app deve usare un identificatore di sessione univoco per ogni utente connesso.

• Una sessione per conversazione agente: se l'app usa una sessione per ogni conversazione dell'agente di intelligenza artificiale, assicurarsi che l'app usi un identificatore di sessione univoco per ogni conversazione che non possa essere modificato dall'utente finale.

Usare l'identità gestita

Un'identità gestita da Microsoft Entra ID consente ai pool di sessioni del contenitore e alle relative sessioni di accedere ad altre risorse protette Microsoft Entra. Le identità gestite assegnate dal sistema e assegnate dall'utente sono supportate in un pool di sessioni.

Per altre informazioni sulle identità gestite in Microsoft Entra ID, vedere Identità gestite per le risorse Azure.

Esistono due modi per usare le identità gestite con pool di sessioni di contenitori personalizzati:

• Autenticazione del pull dell'immagine: usare l'identità gestita per eseguire l'autenticazione con il registro contenitori per eseguire il pull dell'immagine del contenitore.

• Accesso alle risorse: usare l'identità gestita del pool di sessioni in una sessione per accedere ad altre risorse protette da Microsoft Entra. A causa delle implicazioni di sicurezza, questa funzionalità è disabilitata per impostazione predefinita.

  Importante

  Se si abilita l'accesso all'identità gestita in una sessione, qualsiasi codice o programma in esecuzione nella sessione può creare token Microsoft Entra per l'identità gestita del pool. Poiché le sessioni in genere eseguono codice non attendibile, usare questa funzionalità con estrema cautela.

{
  "type": "Microsoft.App/sessionPools",
  "apiVersion": "2024-08-02-preview",
  "name": "my-session-pool",
  "location": "westus2",
  "properties": {
    "environmentId": "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>",
    "poolManagementType": "Dynamic",
    "containerType": "CustomContainer",
    "scaleConfiguration": {
      "maxConcurrentSessions": 10,
      "readySessionInstances": 5
    },
    "dynamicPoolConfiguration": {
      "executionType": "Timed",
      "cooldownPeriodInSeconds": 600
    },
    "customContainerTemplate": {
      "registryCredentials": {
          "server": "myregistry.azurecr.io",
          "identity": "<IDENTITY_RESOURCE_ID>"
      },
      "containers": [
        {
          "image": "myregistry.azurecr.io/my-container-image:1.0",
          "name": "mycontainer",
          "resources": {
            "cpu": 0.25,
            "memory": "0.5Gi"
          },
          "command": [
            "/bin/sh"
          ],
          "args": [
            "-c",
            "while true; do echo hello; sleep 10;done"
          ],
          "env": [
            {
              "name": "key1",
              "value": "value1"
            },
            {
              "name": "key2",
              "value": "value2"
            }
          ]
        }
      ],
      "ingress": {
        "targetPort": 80
      }
    },
    "sessionNetworkConfiguration": {
      "status": "EgressEnabled"
    },
    "managedIdentitySettings": [
      {
        "identity": "<IDENTITY_RESOURCE_ID>",
        "lifecycle": "None"
      }
    ]
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "<IDENTITY_RESOURCE_ID>": {}
    }
  }
}

Registrazione

App contenitore di Azure sessioni dinamiche si integrano con Monitoraggio di Azure e Log Analytics per raccogliere i log generati durante l'esecuzione della sessione. I passaggi di configurazione sono gli stessi per interprete del codice e pool di sessioni di contenitori personalizzati, ma le categorie di log disponibili differiscono in base al tipo di sessione. Le metriche restituite tramite le intestazioni di risposta dell'API non vengono scritte su Log Analytics.

Registrazione delle differenze in base al tipo di sessione

Usare le indicazioni seguenti per confrontare il comportamento di registrazione e passare ai dettagli corrispondenti al tipo di sessione:

• sessioni dell'interprete Code: gli output sono restituiti dall'esecuzione (inclusi stdout e stderr), ma le tabelle AppEnvSession Log Analytics non vengono generate. Vedere Registrazione delle sessioni dell'interprete del codice.
• Sessioni di contenitori personalizzate: le tabelle appEnvSession di Log Analytics vengono generate quando il contenitore scrive in stdout o stderr, e i log della piattaforma sono disponibili per il ciclo di vita del pool e per gli eventi. Vedere Registrazione di sessioni di contenitori personalizzate.
• Common: le metriche restituite tramite le header di risposta API non vengono scritte in Log Analytics.

Per un elenco completo delle categorie di sessione supportate nella risorsa ambiente (Microsoft.App/managedEnvironments), vedere Log supportati per Microsoft. App/managedEnvironments.

Contenuti correlati

• Tipi di sessione: informazioni sui diversi tipi di sessioni dinamiche:

  • Sessioni dell'interprete di codice
  • Sessioni di contenitori personalizzate

• Esercitazioni: Usare direttamente l'API REST o un agente LLM:

  • Usare un agente LLM:
    • AutoGen
    • LangChain
    • LlamaIndex
    • Kernel semantico
  • Usare l'API REST
    • Interprete di codice JavaScript