Usar sessões dinâmicas no Aplicativos de Contêiner do Azure

Aplicativos de Contêiner do Azure sessões dinâmicas oferecem contextos isolados e seguros quando você precisa executar código ou aplicativos separadamente 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 maneira controlada ou ao integrar serviços de terceiros que exigem a execução de código em um ambiente isolado. Você não precisa implantar um recurso de aplicativo de contêiner para usar sessões dinâmicas, criar um pool de sessões e chamar sua API de gerenciamento.

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

Endpoint de gerenciamento e roteamento

Seu aplicativo interage com uma sessão usando a API de gerenciamento do pool de sessão. Para obter uma visão geral conceitual de como as solicitações são roteada, consulte os principais conceitos.

Para obter o ponto de extremidade de gerenciamento do pool de sessão, consulte o ponto de extremidade de gerenciamento de pools de sessão.

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

Para obter mais informações sobre como gerenciar pools de sessões, consulte Ponto de extremidade de gerenciamento de pools de sessões.

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

Todas as solicitações para a API de gerenciamento de pools de sessões exigem autenticação (AuthN) com um token Microsoft Entra e autorização (AuthZ) por meio da função Executor de Sessão do Azure ContainerApps no pool de sessões. Para obter detalhes e exemplos, consulte Autenticação e autorização.

Enviar solicitações para uma sessão

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

Por exemplo, se você fizer uma chamada para <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile, a solicitação será roteada para o contêiner de sessão em sua porta de destino em <TARGET_PORT>/api/uploadfile.

Solicitação de exemplo

O exemplo a seguir mostra como enviar uma solicitação para uma sessão usando a ID de um usuário como o identificador de sessão exclusivo.

Antes de enviar a solicitação, substitua os espaços reservados entre os colchetes <> por valores específicos à 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 da ID do usuário.

Se não houver sessão para o identificador especificado, Aplicativos de Contêiner do Azure alocará automaticamente um do pool antes de encaminhar a solicitação.

Neste exemplo, o contêiner da sessão recebe a solicitação na porta de destino 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, a solicitação será enviada para a sessão existente.

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

O diagrama a seguir mostra como um pool de sessões roteia solicitações 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-la de qualquer maneira que atenda às necessidades do aplicativo.

O identificador de sessão é uma cadeia de caracteres que você define que é exclusiva dentro do pool de sessão. Se você estiver criando um aplicativo Web, poderá usar a ID do usuário como o identificador de sessão. Se você estiver criando um chatbot, poderá usar a ID da conversa.

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

Recuperar informações da sessão

Você pode consultar o pool de sessões para verificar o status da sessão, obter detalhes de expiração e listar todas as sessões ativas. Essa funcionalidade é útil para monitorar a integridade da sessão, acompanhar o uso de recursos e implementar fluxos de trabalho de limpeza personalizados.

Obter uma única sessão

Para recuperar detalhes sobre uma sessão específica, use o 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>

O ponto de extremidade getSession retorna metadados de sessão, incluindo o identificador de sessão, o carimbo de data/hora de criação e o tempo de expiração atual.

O esquema de resposta do SessionView

Exemplo de solicitação 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"
}

Listar todas as sessões em um pool

Para recuperar uma lista de todas as sessões do pool de sessões, use o ponto de extremidade listSessions.

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 ponto de extremidade da lista dá suporte à paginação baseada em skip. Por padrão, cada página retorna até 300 sessões. Use o skip parâmetro de consulta para navegar pelos resultados.

Esquema de resposta do ApiCollectionEnvelope

Loop de paginação de exemplo

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 retorna uma resposta de erro estruturada com detalhes para ajudá-lo 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. Depois que não houver solicitações para a sessão após o período de resfriamento ter decorrido, a sessão será destruída automaticamente.

Segurança

Modelo de segurança

As sessões dinâmicas são criadas para executar aplicativos e códigos 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.

Somente configure ou carregue dados confidenciais em uma sessão se confiar nos usuários dela.

Acesso de 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 de rede no pool de sessões.

Práticas recomendadas

• Identificadores seguros: use identificadores de sessão seguros o tempo todo. Gere identificadores de sessão usando métodos criptográficos para garantir valores exclusivos e imprevisíveis. Evite usar IDs sequenciais que podem ser adivinhadas por um invasor.
• Use HTTPS: sempre use HTTPS para criptografar dados em trânsito. Isso protege os identificadores de sessão e todos os dados confidenciais trocados entre o cliente e o servidor de serem interceptados.
• Limitar o tempo de vida da sessão: implementar 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 reduzir os riscos devido a um dispositivo perdido ou desatendido.
• Limitar a visibilidade da sessão: defina controles de acesso estritos para garantir que os identificadores de sessão só estejam visíveis para o pool de sessões. Evite expor IDs de sessão em URLs ou logs.
• Gire regularmente as credenciais de sessão: revise e atualize periodicamente as credenciais associadas às suas sessões. A rotação diminui o risco de acesso não autorizado.

Diretrizes adicionais para sessões de contêiner personalizadas

• Utilizar protocolos de transmissão seguros: sempre use HTTPS para criptografar dados em trânsito, incluindo identificadores de sessão. Essa abordagem protege contra ataques man-in-the-middle.

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

• Validar a entrada do usuário: trate toda a entrada do usuário como perigosa. Use técnicas de validação de entrada e saneamento para proteger contra ataques de injeção e garantir que apenas dados confiáveis sejam processados.

Autenticação e autorização

Quando você envia solicitações para uma sessão usando a API de gerenciamento de pool, a autenticação é tratada usando tokens Microsoft Entra. Apenas tokens do Microsoft Entra de uma identidade pertencente à função Executor de Sessão do Azure ContainerApps no pool de sessões têm autorização para chamar a API de gerenciamento de pool.

Para atribuir a função 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 você estiver usando uma integração de estrutura de Large Language Model (LLM), a estrutura manipulará a geração e o gerenciamento de tokens para você. Verifique se o aplicativo está configurado com uma identidade gerenciada com as atribuições de função necessárias no pool de sessão.

Se você estiver usando diretamente os pontos de extremidade da API de gerenciamento do pool, deverá gerar um token e incluí-lo no cabeçalho Authorization de suas solicitações HTTP. Além das atribuições de função mencionadas anteriormente, o token precisa conter uma declaraçã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 é as informações confidenciais que você deve gerenciar com segurança. Seu aplicativo precisa garantir que cada usuário ou locatário tenha acesso apenas a suas próprias sessões.

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

As estratégias de exemplo incluem:

• Uma sessão por usuário: caso o aplicativo use 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: caso o aplicativo use uma sessão por conversa de agente de IA, garanta que o aplicativo use um identificador de sessão exclusivo para cada conversa que não possa ser modificado pelo usuário final.

Usar identidade gerenciada

Uma identidade gerenciada do Microsoft Entra ID permite que os pools de sessão de contêiner e suas sessões acessem outros recursos protegidos do Microsoft Entra. Tanto as identidades gerenciadas atribuídas pelo sistema quanto as atribuídas pelo usuário são suportadas em um pool de sessões.

Para obter mais informações sobre identidades gerenciadas no Microsoft Entra ID, consulte Identidades gerenciadas para recursos do Azure.

Há duas maneiras de usar identidades gerenciadas com os pools de sessões de contêiner 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 gerenciada do pool de sessão em uma sessão para acessar outros recursos protegidos pelo Microsoft Entra. Devido a suas implicações de segurança, essa funcionalidade está desabilitada por padrão.

  Importante

  Se você habilitar o acesso à identidade gerenciada em uma sessão, qualquer código ou programa em execução na sessão poderá criar tokens Microsoft Entra para a identidade gerenciada do pool. Como as sessões normalmente 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>": {}
    }
  }
}

Registro em log

As sessões dinâmicas de Aplicativos de Contêiner do Azure integram-se com o Azure Monitor e a análise de logs para coletar os registros emitidos durante a execução da sessão. As etapas de configuração são as mesmas para pools de sessões de contêineres personalizados e de interpretador de código, mas as categorias de log disponíveis diferem de acordo com o tipo de sessão. As métricas retornadas por meio de cabeçalhos de resposta de API não são gravadas em Log Analytics.

Diferenças nos registros de log de acordo com o tipo de sessão

Use as diretrizes a seguir para comparar o comportamento do log e ir para os detalhes que correspondem ao tipo de sessão:

• Sessões do interpretador de código: os resultados são retornados da execução (incluindo stdout e stderr), mas as tabelas de Log Analytics de AppEnvSession não são emitidas. Consulte o registro em log de sessões do interpretador de código.
• Sessões de contêiner personalizadas: as tabelas do Log Analytics do AppEnvSession são emitidas quando seu contêiner grava em stdout ou stderr, e os logs da plataforma estão disponíveis para o ciclo de vida e eventos do pool. Consulte log de sessões de contêiner personalizadas.
• Common: as métricas retornadas por meio de cabeçalhos de resposta de API não são gravadas no Log Analytics.

Para obter uma lista completa das categorias de sessão compatíveis com o recurso de ambiente (Microsoft.App/managedEnvironments), consulte Logs compatíveis para Microsoft.App/managedEnvironments.

Conteúdo relacionado

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

  • Sessões de interpretador de código
  • Sessões de contêiner personalizadas

• Tutoriais: trabalhe diretamente com a API REST ou por meio de um agente LLM:

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