Les endpoints de liste de l’API v4 ne renvoient pas tout : les README des clients officiels Go, Java et Python documentent un défaut de 50 enregistrements par appel. Tant qu’on ne sait pas écrire les options OData, on ramène des pages entières pour filtrer côté client.
L’API v4 de Prism Central suit les conventions d’URL OData V4.01. Cinq paramètres couvrent l’essentiel : $filter, $orderby, $select, $page et $limit, auxquels s’ajoutent $expand et $apply. Tous sont préfixés par $.
$filter
Opérateurs logiques supportés : eq, ne, gt, ge, lt, le, and, or, not, in. Fonctions de chaîne : contains, startswith, endswith, tolower, toupper.
# images dont le nom commence par un préfixe
https://<pc_vip>:9440/api/vmm/v4.1/content/images?$filter=startswith(name, 'fileserver_')
# combinaisons
?$filter=numSockets eq 1 and name eq 'api_v4'
?$filter=not startswith(name, 'pc')
?$filter=name in ('test_1')Les propriétés imbriquées se traversent avec /. Pour un tableau, il faut une lambda — et la doc est explicite : les API v4 ne supportent que l’opérateur any.
?$filter=config/clusterFunction/any(a:a eq Clustermgmt.Config.ClusterFunctionRef'PRISM_CENTRAL')Noter la forme de la valeur : Clustermgmt.Config.ClusterFunctionRef'PRISM_CENTRAL'. Une énumération n’est pas une chaîne, c’est un littéral typé par son nom qualifié complet.
$orderby
Tri croissant avec asc, décroissant avec desc. En l’absence de mention, le tri est croissant.
images_list = api_instance.get_images_list(_orderby="sizeBytes desc")$select
Projection : on ne demande que les propriétés utiles, ce qui allège la réponse.
'https://<pc_vip>:9440/api/clustermgmt/v4.1/config/storage-containers?$select=name,containerExtId,replicationFactor'C’est le paramètre à dégainer pour construire un inventaire : un $select=extId,name suffit à bâtir un référentiel indexé par UUID, ce qui reste la seule façon fiable d’identifier une VM (voir ce billet).
$page et $limit
$page est le numéro de page, $limit le nombre de ressources par page. La pagination est à index zéro, et l’API User Guide donne la formule : starting index = page * limit, ending index = (limit * (page+1)) - 1. Les README des clients précisent les bornes : $limit entier entre 0 et 100, défaut 50.
'https://<pc_vip>:9440/api/vmm/v4.1/ahv/config/vms?$page=2&$limit=100'La réponse porte totalAvailableResults dans ses métadonnées, avec les drapeaux isPaginated / isTruncated et les liens first, self, last. totalAvailableResults est le nombre total de ressources, pas un nombre de pages : le nombre de pages s’en déduit en le divisant par $limit, arrondi au supérieur.
Les erreurs qui coûtent une heure
Le nom du champ n’est pas celui que vous voyez. Le champ filtrable est celui du modèle, et il change d’un endpoint à l’autre : les templates se filtrent sur templateName, les VM sur name. La liste des champs filtrables et triables est propre à chaque opération de liste.
Le $ mangé par le shell. En bash, "...?$filter=..." entre guillemets doubles fait disparaître $filter dans une variable vide. Quotes simples autour de l’URL, toujours.
Les SDK renomment les paramètres. En Python, le préfixe n’est pas $ mais _ : _page, _limit, _filter, _orderby, _select, _expand.
template_list = vmm_instance.list_templates(async_req=False, _filter="templateName eq 'cr-template'")Ce qu’il faut retenir
$limitplafonne à 100 et vaut 50 par défaut : toute collecte sérieuse boucle sur$page(index zéro) jusqu’à avoir lutotalAvailableResultsressources.- Les chaînes sont entre quotes simples, les énumérations sont des littéraux typés par leur nom qualifié complet.
- Propriété imbriquée :
/. Tableau :any(...), la seule lambda supportée. - Le champ filtrable est celui du modèle de l’endpoint, à vérifier opération par opération.
$selectet$applydéplacent le travail côté serveur : moins de données sur le fil, moins de code de post-traitement.
In English
v4 API lists are driven with $filter, $orderby, $select, $page and $limit. Exact syntax, limit values and the pitfalls that make a request fail: enum filters need a fully qualified typed literal, nested properties use a slash, arrays use the any lambda, and the filterable field name follows the model, which varies from one endpoint to another.
Sources & vérification
- Nutanix API User Guide (nutanix.dev) nutanix.dev
- Deploying VMs from templates using Nutanix v4 Python SDK and REST APIs nutanix.dev
- Nutanix v4 APIs – Making The First Requests (Python 3 SDK) nutanix.dev
- Automation with Nutanix Central 2.0 v4 APIs – Part 1, REST APIs nutanix.dev
- ntnx-api-golang-clients, files-go-client README github.com
- ntnx-api-java-clients, vmm README github.com
- ntnx-api-python-clients, vmm README github.com