:Ambientes cloud

O que é um ambiente

Um ambiente atua como a camada de infraestrutura para uma sessão:

• Tipo de contêiner — Atualmente, suporta cloud (um contêiner hospedado na cloud).

• Política de rede — Controla o acesso de rede de saída do contêiner.

• Pacotes — Pré-instala pacotes do sistema, Python e Node.js.

Ao iniciar uma sessão, o sistema cria uma instância isolada com base no modelo de ambiente especificado.

Campos

Política de rede

O campo config.networking suporta três modos. Todos os modos devem usar a forma de objeto; formas abreviadas de string como "unrestricted" não têm suporte e resultam em erro 400.

Campos de networking

Modo irrestrito

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

Use este modo para tarefas de desenvolvimento geral que precisam baixar dependências ou acessar APIs externas.

Modo limitado

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

Use este modo para tarefas que não precisam de acesso arbitrário à internet, mas ainda exigem baixar dependências por meio de 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"
      ]
    }
  }
}

Use este modo para cenários de alta segurança ou conformidade, nos quais você precisa controlar com precisão quais services externos estão acessíveis.

Pacotes pré-instalados

Especifique os pacotes a serem pré-instalados na inicialização do contêiner usando config.packages:

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

Pré-instalar pacotes aumenta o tempo de inicialização do ambiente. Adicione apenas o que for necessário; instale outros pacotes sob demanda durante a sessão.

Crie 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 um 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"
}

Crie 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 .

Consulte 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"

Atualize 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 se aplica apenas às sessões criadas após a atualização.

Exclua 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 um 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 logicamente o ambiente.

Configurações recomendadas

Perguntas frequentes

P: Quanto tempo preciso esperar para usar um ambiente após criá-lo? R: Após criar um ambiente, seu status passa imediatamente para ready, e você pode usá-lo para criar uma sessão de imediato. A inicialização real do contêiner, incluindo a instalação de dependências, ocorre ao iniciar a sessão.P: Posso especificar as versões dos pacotes pré-instalados? R: Sim, você pode especificar versões para pacotes pip e npm, como "pandas==2.1.0" ou "typescript@5.0.0". Os pacotes apt usam a versão padrão do repositório do sistema.P: O que devo fazer se o Agent falhar na execução devido a uma configuração de rede incorreta? R: Crie um novo ambiente ou atualize o existente, modifique a política de rede e, em seguida, reinicie a sessão.P: Qual é o número máximo de ambientes que uma conta pode criar? R: Não há limite rígido. No entanto, recomendamos criar ambientes com base nas suas necessidades reais para evitar problemas de gerenciamento. Sugerimos usar convenções de nomenclatura para organizá-los.