Use pools de sessões em Azure Container Apps

Os conjuntos de sessões fornecem tempos de alocação de sessões a nível de milissegundos para novos conjuntos e são responsáveis pela gestão e pelo ciclo de vida de cada sessão.

Configuração

Pode controlar o comportamento dos grupos de sessões usando os seguintes parâmetros disponíveis para az containerapp sessionpool create.

Propósito	Propriedade	Description
Definir o número máximo de sessões	`max-sessions`	O número máximo de sessões simultâneas permitidas num pool. Os pedidos que chegam após o limite máximo ser atingido recebem um `404` erro de servidor indicando que não há mais sessões a serem atribuídas ao pool.
Duração da espera	`cooldown-period`	O número de segundos em que uma sessão pode estar inativa antes de ser terminada. O período de inatividade é reiniciado cada vez que a API da sessão é chamada. O valor deve estar entre `300` e `3600`.
Quantidade alvo da sessão	`ready-sessions`	O número alvo de sessões para manter preparado numa piscina.

Criar um pool

O processo para criar um pool é ligeiramente diferente dependendo se está a criar um pool de interpretadores de código ou um pool de contentores personalizado.

Pool de interpretadores de código

Para criar um pool de sessões de interpretador de código usando a CLI do Azure, certifique-se de que tem as versões mais recentes da CLI do Azure e da extensão Azure Container Apps com os seguintes comandos:

# Upgrade the Azure CLI
az upgrade

# Install or upgrade the Azure Container Apps extension
az extension add --name containerapp --upgrade --allow-preview true -y

Use o az containerapps sessionpool create comando para criar o pool. O exemplo seguinte cria um pool de sessões interpretador de código Python chamado my-session-pool. Certifica-te de substituir <RESOURCE_GROUP> pelo nome do teu grupo de recursos antes de executares o comando.

az containerapp sessionpool create \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --location westus2 \
    --container-type PythonLTS \
    --max-sessions 100 \
    --cooldown-period 300 \
    --network-status EgressDisabled

Pode definir as seguintes definições ao criar um pool de sessões:

Configuração	Description
`--container-type`	O tipo de interpretador de código a usar. Os valores suportados incluem `PythonLTS`, `NodeLTS`, e `Shell`.
`--max-sessions`	O número máximo de sessões alocadas permitido em simultâneo. O valor máximo é `600`.
`--cooldown-period`	O número de segundos de inatividade permitidos antes da terminação. O período de inatividade é reiniciado cada vez que a API da sessão é chamada. O intervalo permitido é entre `300` e `3600`.
`--network-status`	Designa se o tráfego de rede de saída é permitido a partir da sessão. Os valores válidos são `EgressDisabled` (por defeito) e `EgressEnabled`.

Importante

Se ativares a saída, o código a correr na sessão pode aceder à internet. Use cautela quando o código não for confiável, pois pode ser usado para realizar atividades maliciosas, como ataques de negação de serviço.

Obtenha o endpoint da API de gestão

Para usar sessões de interpretadores de código com integrações de frameworks LLM ou ao chamar diretamente os endpoints da API de gestão, precisa do endpoint da API de gestão do pool.

O endpoint está no formato https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>.

Para recuperar o endpoint da API de gestão para um pool de sessões, use o az containerapps sessionpool show comando. Certifica-te de substituir <RESOURCE_GROUP> pelo nome do teu grupo de recursos antes de executares o comando.

az containerapp sessionpool show \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --query 'properties.poolManagementEndpoint' -o tsv

Pool de contentores personalizados

Para criar um pool personalizado de sessões de contentor, precisa de fornecer uma imagem de contentor e definições de configuração do pool.

Invocas ou comunicas com cada sessão usando pedidos HTTP. O contentor personalizado deve expor um servidor HTTP numa porta que especifique para responder a estes pedidos.

Azure CLI
Azure Resource Manager

Para criar um pool personalizado de sessões de contentores usando a CLI do Azure, certifique-se de que tem as versões mais recentes da CLI do Azure e da extensão Azure Container Apps com os seguintes comandos:

az upgrade
az extension add --name containerapp --upgrade --allow-preview true -y

Pools personalizados de sessões de contentores requerem um ambiente Azure Container Apps habilitado pelo perfil de carga de trabalho. Se não tiveres um ambiente, usa o az containerapp env create -n <ENVIRONMENT_NAME> -g <RESOURCE_GROUP> --location <LOCATION> --enable-workload-profiles comando para criar um.

Use o az containerapp sessionpool create comando para criar um pool personalizado de sessões de contentores.

O exemplo seguinte cria um pool de sessões nomeado my-session-pool com uma imagem myregistry.azurecr.io/my-container-image:1.0de contentor personalizada .

Antes de enviar o pedido, substitua os marcadores entre os <> parênteses pelos valores apropriados para o seu conjunto de sessões e identificador de sessão.

az containerapp sessionpool create \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --environment <ENVIRONMENT> \
    --registry-server myregistry.azurecr.io \
    --registry-username <USER_NAME> \
    --registry-password <PASSWORD> \
    --container-type CustomContainer \
    --image myregistry.azurecr.io/my-container-image:1.0 \
    --cpu 0.25 --memory 0.5Gi \
    --target-port 80 \
    --cooldown-period 300 \
    --network-status EgressDisabled \
    --max-sessions 10 \
    --ready-sessions 5 \
    --env-vars "key1=value1" "key2=value2" \
    --location <LOCATION>

Este comando cria um pool de sessões com as seguintes definições:

Parâmetro	Valor	Description
`--name`	`my-session-pool`	O nome do grupo de sessões.
`--resource-group`	`my-resource-group`	O grupo de recursos que contém o pool de sessões.
`--environment`	`my-environment`	O nome ou ID de recurso do ambiente da aplicação container.
`--container-type`	`CustomContainer`	O tipo de contentor do pool de sessões. Deve ser `CustomContainer` para sessões personalizadas de containers.
`--image`	`myregistry.azurecr.io/my-container-image:1.0`	A imagem do contêiner a ser utilizada para o pool de sessões.
`--registry-server`	`myregistry.azurecr.io`	O nome de host do servidor do registo de contentores.
`--registry-username`	`my-username`	O nome de utilizador para iniciar sessão no registo do contentor.
`--registry-password`	`my-password`	A palavra-passe para iniciar sessão no registo de contentores.
`--cpu`	`0.25`	O CPU necessário em núcleos.
`--memory`	`0.5Gi`	A memória necessária.
`--target-port`	`80`	A porta de sessão usada para o tráfego de entrada.
`--cooldown-period`	`300`	O número de segundos em que uma sessão pode estar inativa antes de ser terminada. O período de inatividade é reiniciado cada vez que a API da sessão é chamada. O valor deve estar entre `300` e `3600`.
`--network-status`	`EgressDisabled`	Designa se o tráfego de rede de saída é permitido a partir da sessão. Os valores válidos são `EgressDisabled` (por defeito) e `EgressEnabled`.
`--max-sessions`	`10`	O número máximo de sessões que podem ser atribuídas ao mesmo tempo.
`--ready-sessions`	`5`	O número alvo de sessões que estão sempre prontas no pool de sessões. Aumente este número se as sessões forem atribuídas mais rapidamente do que a reserva é reabastecida.
`--env-vars`	`"key1=value1" "key2=value2"`	As variáveis de ambiente a definir no contentor.
`--location`	`"Supported Location"`	O local do pool de sessões.

Para verificar o estado do pool de sessões, use o az containerapp sessionpool show comando:

az containerapp sessionpool show \
    --name <SESSION_POOL_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --query "properties.poolManagementEndpoint" \
    --output tsv

Para atualizar o pool de sessões, use o az containerapp sessionpool update comando.

Para criar um pool de sessões personalizado usando o Azure Resource Manager, crie um recurso de pool de sessões com o tipo de recurso Microsoft.ContainerApps/sessionPools. O exemplo seguinte mostra um snippet de template ARM que cria um pool personalizado de sessões de contentores.

Antes de enviar o pedido, substitua os marcadores entre os <> parênteses pelos valores apropriados para o seu conjunto de sessões e identificador de sessão.

{
  "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
    },
    "secrets": [
      {
        "name": "registrypassword",
        "value": "<REGISTRY_PASSWORD>"
      }
    ],
    "customContainerTemplate": {
      "registryCredentials": {
          "server": "myregistry.azurecr.io",
          "username": "myregistry",
          "passwordSecretRef": "registrypassword"
      },
      "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"
    }
  }
}

Este modelo cria um pool de sessões com as seguintes definições:

Parâmetro	Valor	Description
`name`	`my-session-pool`	O nome do grupo de sessões.
`location`	`westus2`	O local do pool de sessões.
`environmentId`	`/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>`	O ID do recurso do ambiente da aplicação container.
`poolManagementType`	`Dynamic`	Deve ser `Dynamic` para sessões personalizadas de contentores.
`containerType`	`CustomContainer`	O tipo de contentor do pool de sessões. Deve ser `CustomContainer` para sessões de containers personalizadas.
`scaleConfiguration.maxConcurrentSessions`	`10`	O número máximo de sessões que podem ser atribuídas ao mesmo tempo.
`scaleConfiguration.readySessionInstances`	`5`	O número desejado de sessões que estão prontas o tempo todo no pool de sessões. Aumente este número se as sessões forem atribuídas mais rapidamente do que a reserva é reabastecida.
`dynamicPoolConfiguration.executionType`	`Timed`	O tipo de execução do pool de sessões. Deve ser `Timed` para sessões personalizadas de contêiner.
`dynamicPoolConfiguration.cooldownPeriodInSeconds`	`600`	O número de segundos em que uma sessão pode estar inativa antes de ser terminada. O período de inatividade é reiniciado cada vez que a API da sessão é chamada. O valor deve estar entre `300` e `3600`.
`secrets`	`[{ "name": "registrypassword", "value": "<REGISTRY_PASSWORD>" }]`	Uma lista de segredos.
`customContainerTemplate.registryCredentials.server`	`myregistry.azurecr.io`	O nome do anfitrião do servidor do registo de contentores.
`customContainerTemplate.registryCredentials.username`	`myregistry`	O nome de utilizador para iniciar sessão no registo do contentor.
`customContainerTemplate.registryCredentials.passwordSecretRef`	`registrypassword`	O nome do segredo que contém a palavra-passe para iniciar sessão no registo de contentores.
`customContainerTemplate.containers[0].image`	`myregistry.azurecr.io/my-container-image:1.0`	A imagem do contentor a usar para o pool de sessões.
`customContainerTemplate.containers[0].name`	`mycontainer`	O nome do contêiner.
`customContainerTemplate.containers[0].resources.cpu`	`0.25`	O CPU necessário em núcleos.
`customContainerTemplate.containers[0].resources.memory`	`0.5Gi`	A memória necessária.
`customContainerTemplate.containers[0].env`	Array de pares nome-valor	As variáveis de ambiente a definir no contentor.
`customContainerTemplate.containers[0].command`	`["/bin/sh"]`	O comando para correr no contentor.
`customContainerTemplate.containers[0].args`	`["-c", "while true; do echo hello; sleep 10;done"]`	Os argumentos para passar ao comando.
`customContainerTemplate.containers[0].ingress.targetPort`	`80`	A porta de sessão usada para o tráfego de entrada.
`sessionNetworkConfiguration.status`	`EgressDisabled`	Designa se o tráfego de rede de saída é permitido a partir da sessão. Os valores válidos são `EgressDisabled` (por defeito) e `EgressEnabled`.

Importante

Se a sessão for usada para executar código não confiável, não inclua informação ou dados que não queira que o código não confiável aceda. Assuma que o código é malicioso e tem acesso total ao contentor, incluindo as suas variáveis de ambiente, segredos e ficheiros.

Ponto de extremidade de gerenciamento

Importante

O identificador de sessão é informação sensível que requer um processo seguro enquanto cria e gere o seu valor. Para proteger este valor, a sua aplicação deve garantir que cada utilizador ou inquilino só tenha acesso às suas próprias sessões.

A falha em garantir o acesso às sessões pode resultar em uso indevido ou acesso não autorizado aos dados armazenados nas sessões dos seus utilizadores. Para mais informações, consulte Identificadores de Sessão

Os seguintes endpoints estão disponíveis para gerir sessões num pool:

Caminho do ponto final	Método	Description
`code/execute`	`POST`	Execute código em uma sessão.
`files/upload`	`POST`	Carregue um ficheiro para uma sessão.
`files/content/{filename}`	`GET`	Descarrega um ficheiro de uma sessão.
`files`	`GET`	Lista os ficheiros numa sessão.

Constróis a URL completa para cada endpoint concatenando o endpoint da API de gestão do pool com o caminho do endpoint. A cadeia de consulta deve incluir um identifier parâmetro contendo o identificador da sessão e um api-version parâmetro com o valor 2024-02-02-preview.

Por exemplo: https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/code/execute?api-version=2024-02-02-preview&identifier=<IDENTIFIER>

Para recuperar o endpoint de gestão do pool de sessões, use o az containerapp sessionpool show comando:

az containerapp sessionpool show \
    --name <SESSION_POOL_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --query "properties.poolManagementEndpoint" \
    --output tsv

Todos os pedidos ao endpoint de gestão do pool devem incluir um Authorization cabeçalho com um token portador. Para aprender a autenticar com a API de gestão de pools, consulte Autenticação.

Cada pedido de API deve também incluir o parâmetro identifier da cadeia de consulta com o ID da Sessão. Este ID de sessão único permite que a sua aplicação interaja com sessões específicas. Para saber mais sobre identificadores de sessão, consulte Identificadores de sessão.

Cache de imagens

Quando um pool de sessões é criado ou atualizado, o Azure Container Apps armazena em cache a imagem do contentor no pool. Esta cache ajuda a acelerar o processo de criação de novas sessões.

Quaisquer alterações à imagem não são automaticamente refletidas nas sessões. Para atualizar a imagem, atualize o pool de sessões com uma nova tag de imagem. Use uma etiqueta única para cada atualização de imagem para garantir que a nova imagem é retirada.

Tipos de sessões: Aprenda 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 de LLM:
- Utilize a API REST
  - Interpretador de código JavaScript

Feedback

Esta página foi útil?

Last updated on 2025-11-19

Partilhar via

Use pools de sessões em Azure Container Apps

Configuração

Criar um pool

Pool de interpretadores de código

Obtenha o endpoint da API de gestão

Pool de contentores personalizados

Ponto de extremidade de gerenciamento

Cache de imagens

Conteúdo relacionado

Feedback

Recursos adicionais