Ambientes de nuvem - Qoder CN Series: Central de Documentação do Alibaba Cloud

O que é um ambiente

O ambiente funciona como a camada de infraestrutura da sessão:

Tipo de contêiner — Atualmente compatível com cloud (contêiner hospedado na nuvem).
Política de rede — Controla o acesso de rede de saída do contêiner.
Pacotes — Pré-instala pacotes de sistema, Python e Node.js.

Sempre que uma sessão é iniciada, o sistema cria uma instância isolada com base no modelo de ambiente especificado.

Campos

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	—	ID gerado pelo sistema com o prefixo `env_`.
`type`	string	—	Fixo como `"environment"`.
`name`	string	Sim	Nome do ambiente.
`description`	string	Não	Descrição opcional. O padrão é `""`.
`config`	object	Sim	Configuração do ambiente (tipo, rede, pacotes).
`config.type`	string	Sim	Tipo de contêiner. Atualmente fixo como `"cloud"`.
`config.networking`	object	Não	Objeto de política de rede. A propriedade `type` deve ser `"unrestricted"`, `"limited"` ou `"allowed_hosts"`.
`config.packages`	object	Não	Configuração dos pacotes pré-instalados.
`status`	string	—	Status do ambiente. Sempre `ready`.
`archived`	boolean	—	Indica se o ambiente está arquivado. O padrão é `false`.
`archived_at`	string	null	—	Timestamp de arquivamento (ISO 8601). `null` se não estiver arquivado.
`created_at`	string	—	Timestamp de criação (ISO 8601).
`updated_at`	string	—	Timestamp da última atualização (ISO 8601).

Política de rede

O campo config.networking aceita três modos. Todos os modos exigem o formato de objeto; atalhos em string como "unrestricted" não são suportados e causam erro 400.

Modo	Valor	Descrição
Irrestrito	`{"type": "unrestricted"}`	O contêiner pode acessar qualquer endereço externo.
Limitado	`{"type": "limited", "allow_package_managers": true}`	Permite acesso apenas a serviços públicos e gerenciadores de pacotes considerados seguros.
Lista de permissões	`{"type": "allowed_hosts", "allowed_hosts": [...]}`	Restringe o acesso a uma lista específica de nomes de host.

Campos de `networking`

Parâmetro	Tipo	Descrição
`networking.type`	string	Tipo de política de rede: `unrestricted`, `limited` ou `allowed_hosts`.
`networking.allow_package_managers`	boolean	Define se permite acesso aos gerenciadores de pacotes (pip, npm e apt) no modo `limited`.
`networking.allowed_hosts`	array	Lista de nomes de host permitidos no modo `allowed_hosts`.

Modo irrestrito

{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}

Ideal para tarefas gerais de desenvolvimento que exigem download de dependências ou acesso a APIs externas.

Modo limitado

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allow_package_managers": true
    }
  }
}

Recomendado para tarefas sem necessidade de acesso arbitrário à internet, mas que ainda requerem obtenção de dependências via gerenciadores de pacotes.

Modo de lista de permissões

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "allowed_hosts",
      "allowed_hosts": [
        "api.github.com",
        "registry.npmjs.org",
        "pypi.org"
      ]
    }
  }
}

Indicado para cenários de alta segurança ou conformidade que exigem controle preciso dos serviços externos acessíveis.

Pacotes pré-instalados

Use config.packages para especificar os pacotes a pré-instalar na inicialização do contêiner:

{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "packages": {
      "apt": ["git", "build-essential", "libssl-dev"],
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["typescript", "eslint", "prettier"]
    }
  }
}

Gerenciador de pacotes	Parâmetro	Descrição
apt	`packages.apt`	Pacotes de sistema Debian/Ubuntu.
pip	`packages.pip`	Pacotes Python.
npm	`packages.npm`	Pacotes Node.js (instalados globalmente).

A pré-instalação de pacotes aumenta o tempo de inicialização do ambiente. Adicione apenas o necessário; instale outros pacotes sob demanda durante a sessão.

Criar um ambiente

# Create a dedicated data science environment
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "apt": ["build-essential"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
      }
    }
  }' | jq .

Em caso de sucesso, a API retorna o status 201 Created:

{
  "id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "type": "environment",
  "name": "data-science",
  "description": "",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "packages": {
      "apt": ["build-essential"],
      "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
    }
  },
  "status": "ready",
  "archived": false,
  "archived_at": null,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

Criar um ambiente seguro

# Create a secure environment that only allows access to internal APIs
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "secure-internal",
    "config": {
      "type": "cloud",
      "networking": {
        "type": "allowed_hosts",
        "allowed_hosts": ["internal-api.mycompany.com", "git.mycompany.com"]
      },
      "packages": {
        "apt": ["git", "curl"]
      }
    }
  }' | jq .

Consultar ambientes

# List all environments
curl -s https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT"

# Get details for a single environment
curl -s https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"

Atualizar um ambiente

# Add new packages to an existing environment
curl -s -X PUT https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "apt": ["build-essential", "libpq-dev"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter", "sqlalchemy"]
      }
    }
  }' | jq .

Atualizar um ambiente não afeta as sessões em execução. A nova configuração aplica-se apenas às sessões criadas após a atualização.

Excluir um ambiente

# Delete a custom environment
curl -s -X DELETE https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"

Se uma sessão ativa estiver usando o ambiente, a solicitação DELETE falhará com o erro 409 Conflict: "Environment is in use and cannot be deleted". Arquive ou exclua as sessões associadas primeiro, ou use POST /environments/{id}/archive para excluir o ambiente logicamente.

Configurações recomendadas

Cenário	Configuração recomendada
Desenvolvimento geral	Use o ambiente `default`; nenhuma configuração extra necessária.
Análise de dados	Pré-instale pandas/numpy; use rede irrestrita.
Auditoria de segurança	Utilize lista de permissões de rede e instale apenas pacotes essenciais.
Desenvolvimento frontend	Pré-instale ferramentas do ecossistema Node.js; permita acesso ao registro npm.
Integração CI/CD	Pré-instale as CLIs do Git e Docker; use o modo de lista de permissões.

Perguntas frequentes

P: Quanto tempo devo esperar para usar um ambiente após a criação? R: Após criar o ambiente, o status muda imediatamente para ready, permitindo a criação imediata de uma sessão. A inicialização efetiva do contêiner, incluindo a instalação de dependências, ocorre apenas quando a sessão é iniciada. P: Posso especificar versões dos pacotes pré-instalados? R: Sim, é possível definir versões para pacotes pip e npm, como "pandas==2.1.0" ou "typescript@5.0.0". Pacotes apt utilizam a versão padrão do repositório do sistema. P: O que fazer se o Agent falhar devido a configuração de rede incorreta? R: Crie um novo ambiente ou atualize o existente, modifique a política de rede e reinicie a sessão. P: Qual o limite máximo de ambientes por conta? R: Não há limite rígido. Contudo, crie ambientes conforme a necessidade real para evitar problemas de gerenciamento. Recomendamos adotar convenções de nomenclatura para organização.

Próximas etapas

Iniciar uma sessão — Use um Agent e um ambiente para iniciar uma tarefa.
Definir um Agent — Revise a configuração do Agent.