Campos y códigos de error de los métodos de almacenamiento
Cuándo usarlo
Al escribir una integración o examinar una respuesta, necesita conocer el conjunto exacto de campos, el tipo de los parámetros, el nivel de rol, el límite del VDC (centro de datos virtual) y el significado de un código de error. Para los procedimientos paso a paso, consulte las instrucciones para ver los pools y para las propiedades de un dataset; para el modelo, consulte Pools de almacenamiento.
Resumen del grupo
| Método | Modo | Parámetros | Acceso | Qué devuelve |
|---|---|---|---|---|
pool-map | síncrono, desde la base de datos | ninguno | Cluster master, Resource Viewer | pools agrupados por node_id |
pool-map-by-guid | síncrono, desde la base de datos | ninguno | no especificado en la documentación canónica de la API | pools agrupados por guid, con capacidad |
pools-list | asíncrono, retransmitido | nodeId | Cluster master | pools servidos por el nodo, con propiedades de ZFS |
pools-get | asíncrono, retransmitido | nodeId, name | Cluster master | propiedades completas de un pool |
filesystems-get | asíncrono, retransmitido | guid | rol <= 2, VDC propio | propiedades del dataset |
filesystems-set | asíncrono, retransmitido | guid, properties | rol <= 2, VDC propio | propiedades actualizadas del dataset |
Los métodos asíncronos responden dos veces: una respuesta intermedia {"message": "relayed"} y
una devolución de llamada (callback) final del agente Storage.
Métodos
pool-map
Un mapa de pools del clúster agrupado por node_id, el número del nodo que los sirve.
Sin parámetros.
{"jsonrpc": "2.0", "method": "pool-map", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
pool-map-by-guid
Un mapa detallado de pools del clúster agrupado por guid. Sin parámetros.
{"jsonrpc": "2.0", "method": "pool-map-by-guid", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
pools-list
Una lista de los pools servidos por el nodo indicado en nodeId.
| Parámetro | Tipo | Obligatorio | Restricciones |
|---|---|---|---|
nodeId | number | sí | rango 1–99 |
{"jsonrpc": "2.0", "method": "pools-list", "params": {"nodeId": 5}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
pools-get
Información detallada sobre un pool servido por el nodo indicado en nodeId.
| Parámetro | Tipo | Obligatorio | Restricciones |
|---|---|---|---|
nodeId | number | sí | rango 1–99 |
name | string | sí | nombre del pool |
{"jsonrpc": "2.0", "method": "pools-get", "params": {"nodeId": 5, "name": "pool-a"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
filesystems-get
Propiedades del sistema de archivos ZFS según el GUID del disco.
| Parámetro | Tipo | Obligatorio | Restricciones |
|---|---|---|---|
guid | string | number | sí | longitud mínima de 1, valor numérico |
{"jsonrpc": "2.0", "method": "filesystems-get", "params": {"guid": "12345"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
filesystems-set
Cambia las propiedades del sistema de archivos ZFS según el GUID del disco. Requiere que la
funcionalidad filesystem_options esté habilitada.
| Parámetro | Tipo | Obligatorio | Restricciones |
|---|---|---|---|
guid | string | number | sí | longitud mínima de 1, valor numérico |
properties | object | sí | objeto que contiene las propiedades de ZFS que se van a cambiar |
{"jsonrpc": "2.0", "method": "filesystems-set", "params": {"guid": "12345", "properties": {"compression": "zstd"}}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
Campos del mapa de pools
Ambos métodos de mapa responden desde la base de datos de vStack Center. Sus conjuntos de campos difieren: las columnas indican qué método devuelve cada campo.
| Campo | pool-map | pool-map-by-guid | Significado |
|---|---|---|---|
guid | sí | sí | identificador persistente del pool |
name | sí | sí | nombre del pool |
health | sí | sí | estado del pool; ONLINE para un pool en buen estado |
consuming | sí | sí | el clúster ha aceptado el pool para el almacenamiento activo de datos |
capacity_pct | sí | sí | uso del pool en porcentaje |
size | sí | sí | capacidad útil, excluida la parte destinada a la redundancia |
node_id | sí | — | número del nodo que sirve actualmente el pool |
nodeid | — | sí | el mismo campo, sin el guion bajo en el nombre |
size_raw | — | sí | capacidad bruta, la suma de las capacidades de los discos del pool |
used | — | sí | espacio ocupado por los datos |
free | — | sí | capacidad útil restante |
provisioned | — | sí | la suma de los tamaños solicitados de los datasets del pool |
provisioned_pct | — | sí | la relación entre provisioned y la capacidad útil |
scrubbing | — | sí | hay en curso una comprobación de integridad |
resilvering | — | sí | hay en curso una restauración de la redundancia |
lif | — | sí | la dirección de red a través de la cual el pool es accesible |
La diferencia en el nombre del campo del nodo (node_id frente a nodeid) es una propiedad de las respuestas, no
una errata de la documentación: un cliente que analice ambos métodos debe reconocer los dos nombres.
Campos de respuesta de los métodos en vivo
Pools del nodo: pools-list
La clave del objeto data es el nombre del pool. Campos del registro:
allocated capacity checkpoint comment dedupditto dedupratio expandsize
fragmentation freeing guid health leaked nodeId readonly size
Significado de los campos principales: allocated, espacio ocupado; capacity, uso en porcentaje;
fragmentation, fragmentación en porcentaje; dedupratio, coeficiente de
deduplicación; expandsize, ampliación disponible; readonly, modo de solo
lectura; freeing, espacio en proceso de liberación; leaked, bloques perdidos.
Propiedades del pool: pools-get
El objeto data devuelve el conjunto completo de propiedades del pool ZFS:
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
Incluyen los campos del mapa más propiedades del propio pool: ashift, tamaño de bloque
del pool; autoexpand, autoreplace, autotrim, ampliación automática, sustitución de discos
y TRIM; failmode, comportamiento ante fallos; version, versión del pool;
load_guid, identificador de la carga actual del pool.
Propiedades del dataset: filesystems-get y filesystems-set
La respuesta de filesystems-get contiene fs_name, el nombre completo del dataset, como
pool-a/vm-100-disk-0, y el objeto properties. En la respuesta de filesystems-set,
el despachador elimina fs_name y deja solo properties. El campo result.code
también difiere. Para filesystems-get, el despachador lo establece en 1; para filesystems-set, el código
procede del agente Storage sin cambios.
Campos de 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 que se examinan con más frecuencia:
| Campo | Significado |
|---|---|
volsize | tamaño de volumen solicitado: lo que ve el sistema invitado |
volblocksize | tamaño de bloque del volumen |
used | espacio que el dataset ocupa actualmente en el pool |
usedbydataset | la parte de ese espacio ocupada por los propios datos |
usedbysnapshots | la parte de ese espacio retenida por las instantáneas |
snapshot_count | número de instantáneas del dataset |
snapshot_limit | límite del número de instantáneas; -1 significa sin límite |
logicalused | tamaño de los datos antes de la compresión |
compression | algoritmo de compresión, como lz4 o zstd |
compressratio | ganancia obtenida por la compresión |
dedup | deduplicación del dataset |
encryption | cifrado del dataset |
available | espacio restante disponible para el dataset |
readonly | modo de solo lectura |
reservation | espacio reservado |
refreservation | reserva para los datos propios del dataset |
Códigos de error
| Código | Mensaje | Métodos | Significado |
|---|---|---|---|
-403 | Access denied | todos los métodos del grupo | nivel de rol insuficiente o solicitud para otro VDC |
-21 | error de la base de datos | pool-map | el despachador no pudo leer el mapa de la base de datos |
-29 | Unable to obtain pool map data | pool-map-by-guid | error de la base de datos o ausencia de pools en el clúster |
-23 | texto del error de retransmisión | pools-list | la solicitud no se envió al nodo |
-24 | nodeId is not present in the cluster | pools-list | no existe ningún nodo con este número en el clúster |
-25 | Pool is not present on the requested node | pools-list | el nodo respondió sin datos de pools |
-33 | texto del error de retransmisión | pools-get | la solicitud no se envió al nodo |
-34 | nodeId is not present in the cluster | pools-get | no existe ningún nodo con este número en el clúster |
-35 | Pool is not present on the requested node | pools-get | el nodo respondió sin datos del pool |
-57 | param guid has bad value | filesystems-get | guid no válido o fallo de retransmisión |
-58 | Dataset does not exist at users scope | filesystems-get | el dataset no existe o pertenece a otro VDC |
-53 | Unable to locate the dataset | filesystems-get | la fila del dataset en la base de datos del despachador tiene el nombre vacío |
-54 | Unable to locate the pool of the dataset | filesystems-get | el pool del dataset no tiene asignado un nodo que lo sirva |
-86 | param guid has bad value | filesystems-set | guid no válido o fallo de retransmisión |
-87 | Filesystems methods has not been enabled | filesystems-set | la funcionalidad filesystem_options está deshabilitada en el clúster |
-88 | Dataset does not exist at users scope | filesystems-set | el dataset no existe o pertenece a otro VDC |
-83 | Unable to locate the dataset | filesystems-set | la fila del dataset en la base de datos del despachador tiene el nombre vacío |
-84 | Unable to locate the pool of the dataset | filesystems-set | el pool del dataset no tiene asignado un nodo que lo sirva |
El validador de parámetros rechaza un nodeId no válido. El cliente recibe
-32602 Invalid params antes de que la solicitud llegue al manejador del método.
Dos pares de códigos abarcan cada uno dos casos distintos: -57 y -86 abarcan un guid
no válido y un fallo de retransmisión; -58 y -88 abarcan un dataset inexistente y un dataset que pertenece a otro VDC.
Este último par es intencionado: no se revela la existencia de un dataset en otro
VDC.
Correspondencia con las columnas de la interfaz
La tabla ZFS pools de la pestaña Storage Resources refleja los campos del mapa de pools. La interfaz define la correspondencia exacta de las columnas; los campos siguientes contienen los valores correspondientes.
| Columna | Campo del mapa |
|---|---|
GUID | guid |
Name | name |
Health | health |
Consuming | consuming |
Scrubbing | scrubbing |
Resilvering | resilvering |
Current node | nodeid |
Capacity (RAW) | size_raw y capacity_pct |
Ejemplo
Una secuencia completa: obtener el mapa, seleccionar un pool de él y consultar las propiedades de su dataset.
{"jsonrpc": "2.0", "method": "pool-map-by-guid", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
Tome "nodeid": 5 y "name": "pool-a" de la respuesta. Solicite las propiedades del pool:
{"jsonrpc": "2.0", "method": "pools-get", "params": {"nodeId": 5, "name": "pool-a"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
A continuación, solicite las propiedades del dataset de un disco de este pool:
{"jsonrpc": "2.0", "method": "filesystems-get", "params": {"guid": "12345"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}
Resultado esperado: en la respuesta final, fs_name empieza por pool-a/; el dataset
se encuentra efectivamente en el pool solicitado.