Use sessões dinâmicas no Azure Container Apps

Azure Container Apps dinâmicas sessões oferecem contextos isolados e seguros quando é necessário executar código ou aplicações de forma separada de outras cargas de trabalho. As sessões são executadas dentro de um pool de sessões que fornece acesso imediato a sessões novas e existentes. Essas sessões são ideais para cenários em que a entrada gerada pelo usuário precisa ser processada de forma controlada ou ao integrar serviços de terceiros que exigem a execução de código em um ambiente isolado. Não precisas de implementar um recurso de aplicação container para usar sessões dinâmicas, criar um pool de sessões e chamar a sua API de gestão.

Este artigo mostra como gerenciar e interagir com sessões dinâmicas.

Endpoint de gestão e roteamento

Seu aplicativo interage com uma sessão usando a API de gerenciamento do pool de sessões. Para uma visão conceptual de como os pedidos são encaminhados, veja Conceitos-chave.

Para obter o endpoint de gestão de pools de sessões, veja endpoint de gestão de pools de sessões.

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

Para mais informações sobre a gestão de pools de sessões, consulte endpoint de gestão de pools de sessões.

Autenticação e autorização da API de gestão

Todos os pedidos para a API de gestão do pool de sessões exigem autenticação (AuthN) com um token Microsoft Entra e autorização (AuthZ) através da função Azure ContainerApps Session Executor no pool de sessões. Para detalhes e exemplos, consulte Autenticação e autorização.

Enviar pedidos para uma sessão

Para enviar uma solicitação para o contêiner de uma sessão, use o ponto de extremidade de gerenciamento como a raiz da solicitação. Qualquer coisa no caminho após o ponto de extremidade de gerenciamento do pool base é encaminhada para o contêiner da sessão.

Por exemplo, se fizer uma chamada para <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile, o pedido é encaminhado para o contentor de sessão na sua porta de destino em <TARGET_PORT>/api/uploadfile.

Pedido de amostra

O exemplo seguinte mostra como enviar um pedido para uma sessão usando o ID de um utilizador como identificador único da sessão.

Antes de enviar a solicitação, substitua os espaços reservados entre <> colchetes por valores específicos para sua solicitação.

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

Essa solicitação é encaminhada para o contêiner na sessão com o identificador do ID do usuário.

Se não existir sessão para o identificador indicado, o Azure Container Apps aloca automaticamente um do pool antes de encaminhar o pedido.

Neste exemplo, o contentor da sessão recebe o pedido na porta alvo em <TARGET_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>.

Identificadores

Para enviar uma solicitação HTTP para uma sessão, você deve fornecer um identificador de sessão na solicitação. Você passa o identificador de sessão em um parâmetro de cadeia de caracteres de consulta nomeado identifier na URL quando faz uma solicitação para uma sessão.

• Se já existir uma sessão com o identificador, o pedido é enviado para a sessão existente.

• Se uma sessão com o identificador não existir, uma nova sessão será automaticamente alocada antes que a solicitação seja enviada a ela.

O diagrama seguinte mostra como um grupo de sessões encaminha pedidos para sessões existentes ou aloca uma nova sessão quando necessário.

Formato do identificador

O identificador de sessão é uma cadeia de caracteres de forma livre, o que significa que você pode defini-lo de qualquer maneira que atenda às necessidades do seu aplicativo.

O identificador de sessão é uma string que defines e que é única dentro do conjunto de sessões. Se você estiver criando um aplicativo Web, poderá usar o ID do usuário como identificador de sessão. Se você estiver criando um chatbot, poderá usar o ID da conversa.

O identificador deve ser uma cadeia de caracteres com 4 a 128 caracteres e pode conter apenas caracteres alfanuméricos e caracteres especiais desta lista: |, -, &, ^, %$#(){}[];<e .>

Recuperar informação da sessão

Pode consultar o seu pool de sessões para verificar o estado da sessão, obter detalhes de expiração e listar todas as sessões ativas. Esta funcionalidade é útil para monitorizar a saúde das sessões, acompanhar o uso de recursos e implementar fluxos de trabalho personalizados de limpeza.

Faz uma única sessão

Para obter detalhes sobre uma sessão específica, use o getSession endpoint:

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

O getSession endpoint devolve metadados da sessão, incluindo o identificador da sessão, a hora de expiração atual e o carimbo temporal da criação.

Esquema de resposta SessionView

Exemplo de pedido e resposta

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"

Resposta de sucesso (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"
}

Liste todas as sessões num grupo

Para obter uma lista de todas as sessões do seu pool de sessões, use o listSessions endpoint:

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

Paginação

O endpoint da lista suporta paginação baseada em skip. Por padrão, cada página devolve até 300 sessões. Use o skip parâmetro de consulta para navegar pelos resultados.

Esquema de resposta ApiCollectionEnvelope

Exemplo de ciclo de paginação

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

Resposta de exemplo (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"
}

Respostas de erro

Quando ocorre um erro, a API devolve uma resposta estruturada de erro com detalhes para o ajudar a diagnosticar o 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"
  }
}

Códigos de erro comuns

Ciclo de vida da sessão na prática

À medida que você continua a fazer chamadas para a mesma sessão, a sessão permanece alocada no pool. Quando não houver solicitações para a sessão após o período de resfriamento, a sessão será automaticamente destruída.

Segurança

Modelo de segurança

As sessões dinâmicas são criadas para executar código e aplicativos não confiáveis em um ambiente seguro e isolado. Embora as sessões sejam isoladas umas das outras, qualquer coisa dentro de uma única sessão, incluindo arquivos e variáveis de ambiente, é acessível pelos usuários da sessão.

Configure ou carregue dados confidenciais para uma sessão somente se confiar nos usuários da sessão.

Acesso à rede

Por padrão, as sessões são impedidas de fazer solicitações de rede de saída. Você pode controlar o acesso à rede definindo as configurações de status da rede no pool de sessões.

Melhores práticas

• Identificadores seguros: use identificadores de sessão seguros em todos os momentos. Gere identificadores de sessão usando métodos criptográficos para garantir valores exclusivos e imprevisíveis. Evite usar IDs sequenciais que possam ser adivinhados por um invasor.
• Usar HTTPS: sempre use HTTPS para criptografar dados em trânsito. Isso protege os identificadores de sessão e quaisquer dados confidenciais trocados entre o cliente e o servidor de serem intercetados.
• Limitar o tempo de vida da sessão: implemente tempos limite para sessões. Por exemplo, permita um máximo de 15 minutos de inatividade antes que a sessão seja encerrada automaticamente. Isso ajuda a mitigar os riscos devido a um dispositivo perdido ou sem supervisão.
• Limitar a visibilidade da sessão: defina controles de acesso rígidos para garantir que os identificadores de sessão sejam visíveis apenas para o pool de sessões. Evite expor IDs de sessão em URLs ou logs.
• Alterne regularmente as credenciais da sessão: examine e atualize periodicamente as credenciais associadas às suas sessões. A rotação diminui o risco de acesso não autorizado.

Orientações adicionais para sessões personalizadas de contentores

• Utilize protocolos de transmissão seguros: Use sempre HTTPS para encriptar dados em trânsito, incluindo identificadores de sessão. Esta abordagem protege contra ataques man-in-the-middle.

• Monitorar a atividade da sessão: implemente o registro em log e o monitoramento para controlar as atividades da sessão. Use esses logs para identificar padrões incomuns ou possíveis violações de segurança.

• Validar entrada do usuário: trate todas as entradas do usuário como perigosas. Use técnicas de validação e higienização de entrada para proteger contra ataques de injeção e garantir que apenas dados confiáveis sejam processados.

Autenticação e autorização

Quando envia pedidos para uma sessão usando a API de gestão de pools, a autenticação é gerida usando tokens Microsoft Entra. Apenas Microsoft Entra tokens de uma identidade pertencente ao papel de Executor de Sessão Azure ContainerApps no pool de sessões estão autorizados a chamar a API de gestão do pool.

Para atribuir o papel a uma identidade, use o seguinte comando CLI do Azure:

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

Se estiveres a usar uma integração de um framework de grandes modelos de linguagem (LLM), o framework trata da geração e gestão de tokens para si. Verifique se o aplicativo está configurado com uma identidade gerenciada com as atribuições de função necessárias no pool de sessões.

Se você estiver usando os pontos de extremidade da API de gerenciamento do pool diretamente, deverá gerar um token e incluí-lo no Authorization cabeçalho de suas solicitações HTTP. Para além das atribuições de papéis mencionadas anteriormente, o token precisa de conter uma reivindicação de audiência (aud) com o valor 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

Proteger identificadores de sessão

O identificador de sessão é uma informação confidencial que deve ser gerida de forma segura. Seu aplicativo precisa garantir que cada usuário ou locatário tenha acesso apenas às suas próprias sessões.

As estratégias específicas que evitam o uso indevido de identificadores de sessão diferem dependendo do design e da arquitetura do seu aplicativo. No entanto, seu aplicativo sempre deve ter controle total sobre a criação e o uso de identificadores de sessão para que um usuário mal-intencionado não possa acessar a sessão de outro usuário.

Exemplos de estratégias incluem:

• Uma sessão por usuário: se seu aplicativo usa uma sessão por usuário, cada usuário deve ser autenticado com segurança e seu aplicativo deve usar um identificador de sessão exclusivo para cada usuário conectado.

• Uma sessão por conversa de agente: se seu aplicativo usa uma sessão por conversa de agente de IA, certifique-se de que seu aplicativo use um identificador de sessão exclusivo para cada conversa que não possa ser modificada pelo usuário final.

Utilizar a identidade gerida

Uma identidade gerida do Microsoft Entra ID permite que os seus pools de sessões de contentores e as suas sessões acedam a outros recursos protegidos pela Microsoft Entra. As identidades gerenciadas atribuídas pelo sistema e pelo usuário são suportadas em um pool de sessões.

Para saber mais sobre identidades geridas no Microsoft Entra ID, consulte Identidades geridas para recursos do Azure.

Há duas maneiras de usar identidades geridas com grupos de sessão de contentores personalizados:

• Autenticação de pull de imagem: use a identidade gerenciada para autenticar com o registro de contêiner para extrair a imagem de contêiner.

• Acesso a recursos: Use a identidade gerida do pool de sessões numa sessão para aceder a outros recursos Microsoft Entra protegidos. Devido às suas implicações de segurança, esse recurso é desativado por padrão.

  Importante

  Se ativar o acesso à identidade gerida numa sessão, qualquer código ou programa a correr pode criar tokens Microsoft Entra para a identidade gerida do pool. Como as sessões geralmente executam código não confiável, use esse recurso com extrema 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>": {}
    }
  }
}

Exploração Florestal

As sessões dinâmicas do Azure Container Apps integram-se com o Azure Monitor e o Log Analytics para recolher os registos emitidos durante a execução da sessão. Os passos de configuração são os mesmos para intérpretes de código e pools personalizados de sessões de contentores, mas as categorias de registos disponíveis variam consoante o tipo de sessão. Métricas devolvidas através dos cabeçalhos de resposta API não são escritas para o Log Analytics.

Diferenças de registo por tipo de sessão

Use as seguintes orientações para comparar o comportamento de registo e vá direto aos detalhes que correspondem ao seu tipo de sessão:

• Code interpreter sessions: Os resultados são retornados da execução (incluindo stdout e stderr), mas as tabelas Log Analytics do AppEnvSession não são emitidas. Ver registo de sessões do interpretador de código.
• Custom container sessions: As tabelas de Log Analytics do AppEnvSession são emitidas quando o seu contentor escreve em stdout ou stderr, e os registos da plataforma estão disponíveis para o ciclo de vida do pool e eventos. Veja o registo de sessões de contentores personalizados.
• Common: Métricas devolvidas via cabeçalhos de resposta API não são escritas para Log Analytics.

Para uma lista completa das categorias de sessão suportadas no recurso de ambiente (Microsoft.App/managedEnvironments), veja Registos suportados para Microsoft. App/managed Environments.

Conteúdo relacionado

• Tipos de sessão: Saiba mais sobre os diferentes tipos de sessões dinâmicas:

  • Sessões de intérprete de código
  • Sessões de contêiner personalizadas

• Tutoriais: Trabalhe diretamente com a API REST ou através de um agente LLM:

  • Use um agente LLM:
    • AutoGen
    • LangChain
    • LlamaIndex
    • Kernel Semântico
  • Usar a API REST
    • Interpretador de código JavaScript