Campos e códigos de erro dos métodos de armazenamento
Quando usar
Ao escrever uma integração ou examinar uma resposta, você precisa saber o conjunto exato de campos, o tipo de parâmetro, o nível de papel, o limite do VDC (data center virtual) e o significado de um código de erro. Para procedimentos passo a passo, consulte as instruções de visualização de pools e de propriedades de datasets; para o modelo, consulte Pools de armazenamento.
Resumo do grupo
| Método | Modo | Parâmetros | Acesso | O que retorna |
|---|---|---|---|---|
pool-map | síncrono, do banco de dados | nenhum | Cluster master, Resource Viewer | pools agrupados por node_id |
pool-map-by-guid | síncrono, do banco de dados | nenhum | não especificado na documentação canônica da API | pools agrupados por guid, com capacidade |
pools-list | assíncrono, repassado | nodeId | Cluster master | pools atendidos pelo nó, com propriedades ZFS |
pools-get | assíncrono, repassado | nodeId, name | Cluster master | propriedades completas de um pool |
filesystems-get | assíncrono, repassado | guid | papel <= 2, próprio VDC | propriedades do dataset |
filesystems-set | assíncrono, repassado | guid, properties | papel <= 2, próprio VDC | propriedades atualizadas do dataset |
Os métodos assíncronos respondem duas vezes: um {"message": "relayed"} intermediário e
um callback final do agente Storage.
Métodos
pool-map
Um mapa de pools do cluster agrupado por node_id — o número do nó que atende o pool.
Sem parâmetros.
{"jsonrpc": "2.0", "method": "pool-map", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
pool-map-by-guid
Um mapa detalhado de pools do cluster agrupado por guid. Sem parâmetros.
{"jsonrpc": "2.0", "method": "pool-map-by-guid", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
pools-list
Uma lista dos pools atendidos pelo nó especificado em nodeId.
| Parâmetro | Tipo | Obrigatório | Restrições |
|---|---|---|---|
nodeId | number | sim | intervalo 1–99 |
{"jsonrpc": "2.0", "method": "pools-list", "params": {"nodeId": 5}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
pools-get
Informações detalhadas sobre um pool atendido pelo nó especificado em nodeId.
| Parâmetro | Tipo | Obrigatório | Restrições |
|---|---|---|---|
nodeId | number | sim | intervalo 1–99 |
name | string | sim | nome do pool |
{"jsonrpc": "2.0", "method": "pools-get", "params": {"nodeId": 5, "name": "pool-a"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
filesystems-get
Propriedades do sistema de arquivos ZFS por GUID do disco.
| Parâmetro | Tipo | Obrigatório | Restrições |
|---|---|---|---|
guid | string | number | sim | comprimento mínimo de 1, valor numérico |
{"jsonrpc": "2.0", "method": "filesystems-get", "params": {"guid": "12345"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
filesystems-set
Altera propriedades do sistema de arquivos ZFS por GUID do disco. Requer que a
feature filesystem_options esteja habilitada.
| Parâmetro | Tipo | Obrigatório | Restrições |
|---|---|---|---|
guid | string | number | sim | comprimento mínimo de 1, valor numérico |
properties | object | sim | objeto com as propriedades ZFS a alterar |
{"jsonrpc": "2.0", "method": "filesystems-set", "params": {"guid": "12345", "properties": {"compression": "zstd"}}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
Campos do mapa de pools
Os dois métodos de mapa respondem a partir do banco de dados do vStack Center. Os conjuntos de campos diferem — as colunas mostram qual método retorna cada campo.
| Campo | pool-map | pool-map-by-guid | Significado |
|---|---|---|---|
guid | sim | sim | identificador persistente do pool |
name | sim | sim | nome do pool |
health | sim | sim | estado do pool; ONLINE para um pool íntegro |
consuming | sim | sim | o cluster aceitou o pool para armazenamento ativo de dados |
capacity_pct | sim | sim | uso do pool em porcentagem |
size | sim | sim | capacidade utilizável, sem a parte reservada à redundância |
node_id | sim | — | número do nó que atende o pool no momento |
nodeid | — | sim | o mesmo campo, sem o sublinhado no nome |
size_raw | — | sim | capacidade bruta, a soma das capacidades dos discos do pool |
used | — | sim | espaço usado pelos dados |
free | — | sim | capacidade utilizável restante |
provisioned | — | sim | a soma dos tamanhos solicitados dos datasets do pool |
provisioned_pct | — | sim | a razão entre provisioned e a capacidade utilizável |
scrubbing | — | sim | uma verificação de integridade está em andamento |
resilvering | — | sim | uma restauração de redundância está em andamento |
lif | — | sim | o endereço de rede pelo qual o pool está acessível |
A diferença no nome do campo de nó (node_id versus nodeid) é uma propriedade das respostas, e não
um erro de digitação da documentação: um cliente que processa os dois métodos precisa reconhecer os dois nomes.
Campos de resposta dos métodos ao vivo
Pools do nó: pools-list
A chave no objeto data é o nome do pool. Campos do registro:
allocated capacity checkpoint comment dedupditto dedupratio expandsize
fragmentation freeing guid health leaked nodeId readonly size
Significado dos principais campos: allocated — espaço usado, capacity — uso em porcentagem,
fragmentation — fragmentação em porcentagem, dedupratio — taxa de
deduplicação, expandsize — expansão disponível, readonly — modo
somente leitura, freeing — espaço sendo liberado, leaked — blocos perdidos.
Propriedades do pool: pools-get
O objeto data retorna o conjunto completo de propriedades ZFS do pool:
allocated altroot ashift autoexpand autoreplace autotrim bootfs cachefile
capacity checkpoint comment compatibility consuming dedupditto dedupratio
delegation expandsize failmode fragmentation free freeing guid health
leaked listsnapshots load_guid maxblocksize maxdnodesize multihost name
readonly resilvering scrubbing size tname version
Elas incluem os campos do mapa mais as propriedades do próprio pool: ashift — tamanho de bloco
do pool; autoexpand, autoreplace, autotrim — expansão automática, substituição de disco
e TRIM; failmode — comportamento em caso de falha; version — versão do pool;
load_guid — identificador do carregamento atual do pool.
Propriedades do dataset: filesystems-get e filesystems-set
A resposta de filesystems-get contém fs_name — o nome completo do dataset, como
pool-a/vm-100-disk-0 — e o objeto properties. Na resposta de filesystems-set,
o dispatcher remove fs_name, deixando apenas properties. O campo result.code
também difere. Para filesystems-get, o dispatcher o define como 1; para filesystems-set, o código
vem do agente Storage sem alteração.
Campos em properties:
available checksum compression compressratio context copies createtxg
creation dedup defcontext encryption fscontext guid inconsistent keyformat
keylocation logbias logicalreferenced logicalused mlslabel objsetid
pbkdf2iters pbkdf2salt primarycache readonly redacted redundant_metadata
refcompressratio referenced refreservation reservation rootcontext
secondarycache snapdev snapshot_count snapshot_limit unique used
usedbychildren usedbydataset usedbyrefreservation usedbysnapshots
useraccounting volblocksize volsize written
Campos examinados com mais frequência:
| Campo | Significado |
|---|---|
volsize | tamanho de volume solicitado — o que o sistema convidado enxerga |
volblocksize | tamanho de bloco do volume |
used | espaço que o dataset ocupa atualmente no pool |
usedbydataset | a parte desse espaço usada pelos próprios dados |
usedbysnapshots | a parte desse espaço retida por snapshots |
snapshot_count | número de snapshots do dataset |
snapshot_limit | limite de quantidade de snapshots; -1 significa sem limite |
logicalused | tamanho dos dados antes da compressão |
compression | algoritmo de compressão, como lz4 ou zstd |
compressratio | ganhos com a compressão |
dedup | deduplicação do dataset |
encryption | criptografia do dataset |
available | espaço restante disponível para o dataset |
readonly | modo somente leitura |
reservation | espaço reservado |
refreservation | reserva para os dados do próprio dataset |
Códigos de erro
| Código | Mensagem | Métodos | Significado |
|---|---|---|---|
-403 | Access denied | todos os métodos do grupo | nível de papel insuficiente ou solicitação para outro VDC |
-21 | erro do banco de dados | pool-map | o dispatcher não conseguiu ler o mapa do banco de dados |
-29 | Unable to obtain pool map data | pool-map-by-guid | erro do banco de dados ou nenhum pool no cluster |
-23 | texto do erro de repasse | pools-list | a solicitação não foi enviada ao nó |
-24 | nodeId is not present in the cluster | pools-list | não existe nó com esse número no cluster |
-25 | Pool is not present on the requested node | pools-list | o nó respondeu sem dados de pool |
-33 | texto do erro de repasse | pools-get | a solicitação não foi enviada ao nó |
-34 | nodeId is not present in the cluster | pools-get | não existe nó com esse número no cluster |
-35 | Pool is not present on the requested node | pools-get | o nó respondeu sem dados do pool |
-57 | param guid has bad value | filesystems-get | guid inválido ou falha de repasse |
-58 | Dataset does not exist at users scope | filesystems-get | o dataset não existe ou pertence a outro VDC |
-53 | Unable to locate the dataset | filesystems-get | a linha do dataset no banco de dados do dispatcher tem um nome vazio |
-54 | Unable to locate the pool of the dataset | filesystems-get | o pool do dataset não tem um nó atribuído para atendê-lo |
-86 | param guid has bad value | filesystems-set | guid inválido ou falha de repasse |
-87 | Filesystems methods has not been enabled | filesystems-set | a feature filesystem_options está desabilitada no cluster |
-88 | Dataset does not exist at users scope | filesystems-set | o dataset não existe ou pertence a outro VDC |
-83 | Unable to locate the dataset | filesystems-set | a linha do dataset no banco de dados do dispatcher tem um nome vazio |
-84 | Unable to locate the pool of the dataset | filesystems-set | o pool do dataset não tem um nó atribuído para atendê-lo |
O validador de parâmetros rejeita um nodeId inválido. O cliente recebe
-32602 Invalid params antes que a solicitação chegue ao handler do método.
Dois pares de códigos cobrem, cada um, dois casos diferentes: -57 e -86 cobrem um guid
inválido e uma falha de repasse; -58 e -88 cobrem um dataset inexistente e um dataset que pertence a outro VDC.
O último par é intencional: a existência de um dataset em outro VDC não é
revelada.
Correspondência com as colunas da interface
A tabela ZFS pools na guia Storage Resources reflete os campos do mapa de pools. A interface define a correspondência exata das colunas; os campos abaixo contêm os valores correspondentes.
| Coluna | Campo do mapa |
|---|---|
GUID | guid |
Name | name |
Health | health |
Consuming | consuming |
Scrubbing | scrubbing |
Resilvering | resilvering |
Current node | nodeid |
Capacity (RAW) | size_raw e capacity_pct |
Exemplo
Uma sequência completa: obtenha o mapa, selecione um pool nele e consulte as propriedades do dataset.
{"jsonrpc": "2.0", "method": "pool-map-by-guid", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
Pegue "nodeid": 5 e "name": "pool-a" da resposta. Solicite as propriedades do pool:
{"jsonrpc": "2.0", "method": "pools-get", "params": {"nodeId": 5, "name": "pool-a"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
Em seguida, solicite as propriedades do dataset de um disco nesse pool:
{"jsonrpc": "2.0", "method": "filesystems-get", "params": {"guid": "12345"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
Resultado esperado: na resposta final, fs_name começa com pool-a/ — o dataset
de fato está no pool solicitado.