{"id":1616,"date":"2026-09-14T10:18:50","date_gmt":"2026-09-14T13:18:50","guid":{"rendered":"https:\/\/www.linuxpro.com.br\/?p=1616"},"modified":"2026-09-14T10:20:55","modified_gmt":"2026-09-14T13:20:55","slug":"api-do-virtualbox-em-go-liste-vms-com-soap","status":"publish","type":"post","link":"https:\/\/www.linuxpro.com.br\/es\/2026\/09\/api-do-virtualbox-em-go-liste-vms-com-soap\/","title":{"rendered":"API de VirtualBox \u2014 parte 2: cliente SOAP en Go"},"content":{"rendered":"

\"Mascote<\/p>\n

Vamos implementar um cliente em Go que autentica no web service do VirtualBox, lista UUID, nome e estado das m\u00e1quinas e encerra a sess\u00e3o. O programa utiliza somente a biblioteca padr\u00e3o e produz um invent\u00e1rio JSON, sem executar a\u00e7\u00f5es de escrita sobre as VMs.<\/p>\n

Esta \u00e9 a parte 2<\/strong>. Se voc\u00ea ainda n\u00e3o conhece o servi\u00e7o, leia primeiro a parte 1: SOAP, sess\u00f5es e seguran\u00e7a na API do VirtualBox<\/a>. L\u00e1 est\u00e3o a prepara\u00e7\u00e3o do vboxwebsrv<\/code>, o t\u00fanel SSH e a diferen\u00e7a entre refer\u00eancias e UUIDs.<\/p>\n

Pr\u00e9-requisitos do exemplo<\/h2>\n

Tenha Go instalado e um host VirtualBox com vboxwebsrv<\/code> ativo, autentica\u00e7\u00e3o configurada e acesso protegido. Os comandos abaixo usam http:\/\/127.0.0.1:18083\/<\/code>: execute o cliente no mesmo host ou use o t\u00fanel explicado na parte 1. N\u00e3o desabilite a autentica\u00e7\u00e3o nem exponha essa porta diretamente \u00e0 internet.<\/p>\n

Qual contrato foi usado e o que foi testado<\/h2>\n

As opera\u00e7\u00f5es e seus par\u00e2metros foram conferidos no WSDL inclu\u00eddo no SDK oficial 7.2.0<\/a>, usado como refer\u00eancia documental da linha 7.2. Isso n\u00e3o \u00e9 recomenda\u00e7\u00e3o para instalar um patch antigo: use uma vers\u00e3o mantida do VirtualBox e confira o SDK correspondente ao seu ambiente.<\/p>\n

Valida\u00e7\u00e3o deste artigo:<\/strong> o c\u00f3digo foi compilado, verificado com go vet<\/code> e testado com servidor SOAP simulado e detector de corridas. Tamb\u00e9m verificamos estruturas de requisi\u00e7\u00e3o contra o XSD do SDK. N\u00e3o houve teste de uma sess\u00e3o autenticada em um host VirtualBox real. Portanto, a integra\u00e7\u00e3o precisa passar por homologa\u00e7\u00e3o no seu laborat\u00f3rio antes de uso operacional.<\/p>\n

Os testes adicionais cobriram erro SOAP, XML inv\u00e1lido, resposta excessiva, redirecionamento, cancelamento, escape de caracteres e limpeza de sess\u00e3o ap\u00f3s falha. O exemplo n\u00e3o pretende substituir um SDK completo.<\/p>\n

1. Criar o projeto Go<\/h2>\n
mkdir vbox-inventory\ncd vbox-inventory\ngo mod init example.com\/vbox-inventory<\/code><\/pre>\n
O exemplo utiliza errors.Join<\/code>, dispon\u00edvel a partir do Go 1.20; prefira uma vers\u00e3o atualmente mantida. N\u00e3o h\u00e1 depend\u00eancias externas para baixar. Vamos separar o transporte SOAP em client.go<\/code> e o invent\u00e1rio em main.go<\/code>.<\/p>\n
2. Implementar o transporte SOAP<\/h2>\n
Salve como client.go<\/code>. O cliente aceita HTTP apenas para loopback, n\u00e3o segue redirecionamentos, limita a resposta e deixa a valida\u00e7\u00e3o TLS padr\u00e3o ativa:<\/p>\n
package main\n\nimport (\n\t"bytes"\n\t"context"\n\t"encoding\/xml"\n\t"errors"\n\t"fmt"\n\t"io"\n\t"net"\n\t"net\/http"\n\t"net\/url"\n\t"time"\n)\n\nconst apiNS = "http:\/\/www.virtualbox.org\/"\nconst soapNS = "http:\/\/schemas.xmlsoap.org\/soap\/envelope\/"\nconst maxResponse = 2 << 20\n\ntype client struct {\n\tendpoint string\n\thttp     *http.Client\n}\n\ntype field struct{ name, value string }\n\ntype reply struct {\n\tXMLName xml.Name `xml:"http:\/\/schemas.xmlsoap.org\/soap\/envelope\/ Envelope"`\n\tBody    struct {\n\t\tFault  *struct{} `xml:"http:\/\/schemas.xmlsoap.org\/soap\/envelope\/ Fault"`\n\t\tResult struct {\n\t\t\tXMLName xml.Name\n\t\t\tValues  []string `xml:"returnval"`\n\t\t} `xml:",any"`\n\t} `xml:"http:\/\/schemas.xmlsoap.org\/soap\/envelope\/ Body"`\n}\n\nfunc newClient(endpoint string) (*client, error) {\n\tu, err := url.Parse(endpoint)\n\tif err != nil || u.Host == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" {\n\t\treturn nil, errors.New("endpoint inv\u00e1lido: use URL sem credenciais ou par\u00e2metros")\n\t}\n\tip := net.ParseIP(u.Hostname())\n\tloopback := u.Hostname() == "localhost" || (ip != nil && ip.IsLoopback())\n\tif u.Scheme != "https" && !(u.Scheme == "http" && loopback) {\n\t\treturn nil, errors.New("use HTTPS; HTTP s\u00f3 \u00e9 permitido no loopback")\n\t}\n\ttransport := http.DefaultTransport.(*http.Transport).Clone()\n\ttransport.Proxy = nil \/\/ N\u00e3o encaminhar credenciais por proxy do ambiente.\n\treturn &client{\n\t\tendpoint: endpoint,\n\t\thttp: &http.Client{\n\t\t\tTransport:     transport,\n\t\t\tTimeout:       10 * time.Second,\n\t\t\tCheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },\n\t\t},\n\t}, nil\n}\n\nfunc (c *client) call(ctx context.Context, method string, fields ...field) (values []string, err error) {\n\tswitch method {\n\tcase "IWebsessionManager_logon", "IWebsessionManager_logoff", "IVirtualBox_getMachines",\n\t\t"IMachine_getId", "IMachine_getName", "IMachine_getState":\n\tdefault:\n\t\treturn nil, errors.New("opera\u00e7\u00e3o fora do escopo somente leitura")\n\t}\n\tvar params bytes.Buffer\n\tenc := xml.NewEncoder(&params)\n\tfor _, f := range fields {\n\t\tif err := enc.EncodeElement(f.value, xml.StartElement{Name: xml.Name{Local: f.name}}); err != nil {\n\t\t\treturn nil, fmt.Errorf("codificar par\u00e2metros: %w", err)\n\t\t}\n\t}\n\tif err := enc.Flush(); err != nil {\n\t\treturn nil, fmt.Errorf("finalizar XML: %w", err)\n\t}\n\tbody := fmt.Sprintf(\n\t\t`<s:Envelope xmlns:s="%s" xmlns:v="%s"><s:Body><v:%s>%s<\/v:%s><\/s:Body><\/s:Envelope>`,\n\t\tsoapNS, apiNS, method, params.String(), method,\n\t)\n\treq, err := http.NewRequestWithContext(ctx, http.MethodPost, c.endpoint, bytes.NewBufferString(body))\n\tif err != nil {\n\t\treturn nil, fmt.Errorf("criar requisi\u00e7\u00e3o: %w", err)\n\t}\n\treq.Header.Set("Content-Type", "text\/xml; charset=utf-8")\n\treq.Header.Set("SOAPAction", `""`)\n\tres, err := c.http.Do(req)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf("transportar %s: %w", method, err)\n\t}\n\tdefer func() { err = errors.Join(err, res.Body.Close()) }()\n\tdata, err := io.ReadAll(io.LimitReader(res.Body, maxResponse+1))\n\tif err != nil {\n\t\treturn nil, fmt.Errorf("ler resposta: %w", err)\n\t}\n\tif len(data) > maxResponse {\n\t\treturn nil, errors.New("resposta excede 2 MiB")\n\t}\n\tvar decoded reply\n\tdecodeErr := xml.Unmarshal(data, &decoded)\n\tif decodeErr == nil && decoded.Body.Fault != nil {\n\t\t\/\/ N\u00e3o imprimir faultstring\/detail: podem revelar informa\u00e7\u00f5es do host.\n\t\treturn nil, fmt.Errorf("falha SOAP em %s (HTTP %d)", method, res.StatusCode)\n\t}\n\tif res.StatusCode != http.StatusOK {\n\t\treturn nil, fmt.Errorf("%s: HTTP %d", method, res.StatusCode)\n\t}\n\tif decodeErr != nil {\n\t\treturn nil, fmt.Errorf("decodificar resposta: %w", decodeErr)\n\t}\n\tresult := decoded.Body.Result\n\tif result.XMLName.Space != apiNS || result.XMLName.Local != method+"Response" {\n\t\treturn nil, errors.New("resposta SOAP inesperada")\n\t}\n\treturn result.Values, nil\n}\n\nfunc (c *client) one(ctx context.Context, method string, fields ...field) (string, error) {\n\tvalues, err := c.call(ctx, method, fields...)\n\tif err != nil {\n\t\treturn "", err\n\t}\n\tif len(values) != 1 || values[0] == "" {\n\t\treturn "", errors.New("retorno escalar vazio ou inv\u00e1lido")\n\t}\n\treturn values[0], nil\n}<\/code><\/pre>\n
O xml.Encoder<\/code> cuida do escape dos valores. N\u00e3o concatenamos a senha diretamente como XML. O namespace, as opera\u00e7\u00f5es e o SOAPAction<\/code> vazio seguem o contrato consultado; erros HTTP e SOAP s\u00e3o tratados separadamente.<\/p>\n
Detalhes completos de falhas do servidor foram omitidos da mensagem para reduzir exposi\u00e7\u00e3o de informa\u00e7\u00f5es. Em um produto real, voc\u00ea pode classificar os tipos de falha internamente, mantendo segredos e detalhes sens\u00edveis fora dos logs. Veja as refer\u00eancias de encoding\/xml<\/a> e net\/http<\/a>.<\/p>\n
3. Listar as m\u00e1quinas e garantir o logoff<\/h2>\n
Salve como main.go<\/code>:<\/p>\n
package main\n\nimport (\n\t"context"\n\t"encoding\/json"\n\t"errors"\n\t"fmt"\n\t"os"\n\t"time"\n)\n\ntype machine struct {\n\tID    string `json:"id"`\n\tName  string `json:"name"`\n\tState string `json:"state"`\n}\n\nfunc inventory(ctx context.Context, c *client, username, password string) (vms []machine, err error) {\n\tref, err := c.one(ctx, "IWebsessionManager_logon",\n\t\tfield{name: "username", value: username},\n\t\tfield{name: "password", value: password},\n\t)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tdefer func() {\n\t\t\/\/ A limpeza precisa funcionar mesmo se o contexto principal expirar.\n\t\tcleanup, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\t\tdefer cancel()\n\t\t_, closeErr := c.call(cleanup, "IWebsessionManager_logoff", field{name: "refIVirtualBox", value: ref})\n\t\tif closeErr != nil {\n\t\t\terr = errors.Join(err, fmt.Errorf("encerrar sess\u00e3o: %w", closeErr))\n\t\t}\n\t}()\n\trefs, err := c.call(ctx, "IVirtualBox_getMachines", field{name: "_this", value: ref})\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tvms = make([]machine, 0, len(refs))\n\tfor _, machineRef := range refs {\n\t\ttarget := field{name: "_this", value: machineRef}\n\t\tid, err := c.one(ctx, "IMachine_getId", target)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tname, err := c.one(ctx, "IMachine_getName", target)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tstate, err := c.one(ctx, "IMachine_getState", target)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tvms = append(vms, machine{ID: id, Name: name, State: state})\n\t}\n\treturn vms, nil\n}\n\nfunc run() error {\n\tendpoint := os.Getenv("VBOX_URL")\n\tif endpoint == "" {\n\t\tendpoint = "http:\/\/127.0.0.1:18083\/"\n\t}\n\tusername, password := os.Getenv("VBOX_USER"), os.Getenv("VBOX_PASSWORD")\n\tif username == "" || password == "" {\n\t\treturn errors.New("defina VBOX_USER e VBOX_PASSWORD")\n\t}\n\tc, err := newClient(endpoint)\n\tif err != nil {\n\t\treturn err\n\t}\n\tdefer c.http.CloseIdleConnections()\n\tctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)\n\tdefer cancel()\n\tvms, err := inventory(ctx, c, username, password)\n\tif err != nil {\n\t\treturn err\n\t}\n\tout := json.NewEncoder(os.Stdout)\n\tout.SetIndent("", "  ")\n\tif err := out.Encode(vms); err != nil {\n\t\treturn fmt.Errorf("escrever invent\u00e1rio: %w", err)\n\t}\n\treturn nil\n}\n\nfunc main() {\n\tif err := run(); err != nil {\n\t\tfmt.Fprintln(os.Stderr, "erro:", err)\n\t\tos.Exit(1)\n\t}\n}<\/code><\/pre>\n
O defer<\/code> para limpeza \u00e9 registrado assim que o login retorna uma refer\u00eancia v\u00e1lida. Ele usa um contexto independente e curto: se a consulta principal expirar, ainda haver\u00e1 uma tentativa de encerrar a sess\u00e3o. Uma falha no logoff n\u00e3o \u00e9 silenciosamente descartada.<\/p>\n
A execu\u00e7\u00e3o \u00e9 sequencial por clareza. O nome, estado e UUID exigem consultas separadas; n\u00e3o \u00e9 um coletor otimizado para invent\u00e1rios enormes. O programa interrompe a coleta no primeiro erro e n\u00e3o apresenta um invent\u00e1rio parcial como se fosse completo. A restri\u00e7\u00e3o de opera\u00e7\u00f5es \u00e9 do cliente did\u00e1tico, n\u00e3o uma pol\u00edtica de autoriza\u00e7\u00e3o aplicada pelo servidor.<\/p>\n
4. Compilar e executar sem colocar a senha no hist\u00f3rico<\/h2>\n
No Bash, compile e leia a senha sem escrev\u00ea-la na linha de comando:<\/p>\n
gofmt -w client.go main.go\ngo vet .\/...\ngo build -o vbox-inventory .\n\nexport VBOX_URL='http:\/\/127.0.0.1:18083\/'\nIFS= read -r -p 'Usu\u00e1rio do servi\u00e7o: ' VBOX_USER\nexport VBOX_USER\nIFS= read -r -s -p 'Senha do servi\u00e7o: ' VBOX_PASSWORD\nprintf '\\n'\nexport VBOX_PASSWORD\n.\/vbox-inventory\nunset VBOX_PASSWORD<\/code><\/pre>\n
Vari\u00e1veis de ambiente n\u00e3o s\u00e3o um cofre: processos privilegiados e ferramentas de diagn\u00f3stico podem exp\u00f4-las. Em automa\u00e7\u00e3o, integre um mecanismo de segredos apropriado e n\u00e3o imprima ambiente, XML de login ou refer\u00eancias de sess\u00e3o.<\/p>\n
Formato ilustrativo de sa\u00edda, n\u00e3o capturado de um host real:<\/p>\n
[\n  {\n    "id": "11111111-2222-3333-4444-555555555555",\n    "name": "Linux lab",\n    "state": "PoweredOff"\n  }\n]<\/code><\/pre>\n
Se a conta n\u00e3o tiver m\u00e1quinas registradas, a sa\u00edda ser\u00e1 []<\/code>. Um erro faz o programa terminar com c\u00f3digo diferente de zero. Antes de concluir que o invent\u00e1rio est\u00e1 errado, confirme qual ambiente de usu\u00e1rio o servi\u00e7o est\u00e1 expondo.<\/p>\n
5. Um teste automatizado sem hipervisor<\/h2>\n
Salve este teste como client_test.go<\/code>. Ele verifica que um SOAP Fault produz erro sem reproduzir os detalhes privados do servidor:<\/p>\n
package main\n\nimport (\n\t"context"\n\t"io"\n\t"net\/http"\n\t"net\/http\/httptest"\n\t"strings"\n\t"testing"\n)\n\nfunc TestSOAPFaultIsNotSuccess(t *testing.T) {\n\tserver := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\tw.WriteHeader(http.StatusInternalServerError)\n\t\tbody := `<s:Envelope xmlns:s="http:\/\/schemas.xmlsoap.org\/soap\/envelope\/">` +\n\t\t\t`<s:Body><s:Fault><faultstring>private-host-detail<\/faultstring><\/s:Fault><\/s:Body><\/s:Envelope>`\n\t\tif _, err := io.WriteString(w, body); err != nil {\n\t\t\tt.Error(err)\n\t\t}\n\t}))\n\tdefer server.Close()\n\tc, err := newClient(server.URL)\n\tif err != nil {\n\t\tt.Fatal(err)\n\t}\n\tdefer c.http.CloseIdleConnections()\n\t_, err = c.call(context.Background(), "IVirtualBox_getMachines", field{name: "_this", value: "test-ref"})\n\tif err == nil {\n\t\tt.Fatal("SOAP Fault deveria produzir erro")\n\t}\n\tif strings.Contains(err.Error(), "private-host-detail") {\n\t\tt.Fatal("erro exp\u00f4s detalhes do host")\n\t}\n}<\/code><\/pre>\n
go test -race -count=1 .\/...<\/code><\/pre>\n
Esse teste exercita o transporte com um servidor simulado. Ele n\u00e3o comprova credenciais, permiss\u00f5es ou compatibilidade operacional com seu VirtualBox. Complete a homologa\u00e7\u00e3o com uma m\u00e1quina de laborat\u00f3rio e compare UUID, nome e estado com a administra\u00e7\u00e3o local.<\/p>\n
Falhas comuns e diagn\u00f3stico<\/h2>\n\n\n\n\n\n\n\n\n\n\n\n
Problema<\/th>\nO que verificar<\/th>\n<\/tr>\n<\/thead>\n
Conex\u00e3o recusada<\/td>\nServi\u00e7o ativo, endere\u00e7o, porta e t\u00fanel SSH.<\/td>\n<\/tr>\n
Falha SOAP no login<\/td>\nAutentica\u00e7\u00e3o configurada, usu\u00e1rio e senha; n\u00e3o desligue a prote\u00e7\u00e3o como corre\u00e7\u00e3o.<\/td>\n<\/tr>\n
Lista vazia<\/td>\nUsu\u00e1rio que executa o servi\u00e7o e m\u00e1quinas registradas naquele ambiente.<\/td>\n<\/tr>\n
Refer\u00eancia inv\u00e1lida<\/td>\nSess\u00e3o expirada ou refer\u00eancia reutilizada de outra execu\u00e7\u00e3o.<\/td>\n<\/tr>\n
Erro de certificado<\/td>\nNome do servidor e cadeia de confian\u00e7a; n\u00e3o use InsecureSkipVerify<\/code>.<\/td>\n<\/tr>\n
Resposta inesperada<\/td>\nEndpoint correto, namespace, vers\u00e3o e contrato WSDL.<\/td>\n<\/tr>\n
Prazo excedido<\/td>\nLat\u00eancia, n\u00famero de VMs e limites configurados.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
O programa utiliza dez segundos por requisi\u00e7\u00e3o, trinta para a coleta e cinco para a limpeza. S\u00e3o escolhas did\u00e1ticas, n\u00e3o valores universais. Ajuste-os com medi\u00e7\u00e3o. N\u00e3o acrescente repeti\u00e7\u00e3o autom\u00e1tica indiscriminada quando evoluir para a\u00e7\u00f5es de escrita: um timeout n\u00e3o prova que o servidor deixou de executar a opera\u00e7\u00e3o.<\/p>\n
Quer evoluir de consultas para a\u00e7\u00f5es sobre as VMs? Revise na parte 1<\/a> os cuidados com sess\u00f5es de m\u00e1quina, bloqueios, autoriza\u00e7\u00e3o e opera\u00e7\u00f5es de escrita.<\/p>\n
Como transformar o exemplo em um projeto maior<\/h2>\n