Go to main content

Guide RESTful API des systèmes Oracle® ZFS Storage Appliance, version OS8.8.x

Quitter la vue de l'impression

Mis à jour : Août 2021
 
 

Paramètres de requête

Certaines requêtes acceptent des paramètres facultatifs qui sélectionnent les données à retourner ou à traiter. Cette section présente les paramètres de requête pouvant être utilisés par plusieurs types de ressources. Reportez-vous à la documentation relative aux ressources pour en savoir plus sur les paramètres de requête spécifiques à chacune et les utilisations spécialisées des paramètres décrits dans cette section.

Table 2  Paramètres de requête courants
Paramètre
Description
props=true
Enumération des métadonnées de la propriété pour une ressource. La valeur par défaut est false.
start=index
Permet de spécifier les données ou les objets les plus anciens à renvoyer après l'heure ou l'ID objet indiqués.
end=index
Permet de spécifier les données ou les objets les plus récents à renvoyer avant l'heure ou l'ID objet indiqués.
limit=n
Limite le nombre éléments de liste renvoyés à n au maximum.
depth=n
Permet d'indiquer le niveau de détail des données renvoyées.
match_property-name=value
Renvoie les objets de liste dont la propriété spécifiée indique la valeur précisée.

Paramètre de requête : props

Le paramètre de requête props affiche les valeurs de métadonnées de propriété. Lorsque vous utilisez props=true avec des opérations qui sans cela modifieraient les données ou en créeraient de nouvelles, les propriétés et les métadonnées sont affichées et l'opération n'est pas exécutée. Vous visualisez ainsi les valeurs de données courantes qui peuvent vous aider à modifier ou à créer la ressource.

Table 3  Valeurs des métadonnées de la propriété
Propriété
Description
name
Nom de la propriété
label
Description de la propriété
immutable
Indicateur de l'impossibilité de modifier une propriété
type
Type de propriété, tel que String, Integer, Boolean ou ChooseOne
choices
Groupe de valeurs disponibles pour les propriétés énumérées

Paramètre de requête : start

Le paramètre de requête start peut être un numéro d'index d'objet ou une valeur de temps.

  • Spécifiez un numéro d'index d'objet afin de renvoyer une liste qui inclut l'objet sélectionné par cet index et les objets les plus anciens créés après l'objet indiqué.

  • Spécifiez une heure UTC pour renvoyer une liste des objets ou des données les plus anciens créés à ou après la valeur de temps spécifiée. Certaines ressources ne prennent pas en charge les valeurs de temps pour le paramètre de requête start.

Les valeurs de temps doivent être exprimées dans le format UTC présenté dans le tableau suivant.

Version du service
Format de la valeur de temps
Exemple de valeur de temps
Chemins v1
%A%m%jT%H:%M:%SZ
20200723T14:11:49
Chemins v2
%A-%m-%jT%H:%M:%SZ
2020-07-23T14:11:49Z

Reportez-vous aux sections suivantes pour obtenir des exemples utilisant le paramètre de requête start :

Paramètre de requête : end

Le paramètre de requête end peut être un numéro d'index d'objet ou une valeur de temps.

  • Spécifiez un numéro d'index d'objet afin de renvoyer une liste qui inclut l'objet sélectionné par cet index et les objets les plus récents créés avant l'objet indiqué.

  • Spécifiez une heure UTC pour renvoyer une liste des objets ou des données les plus récents créés à ou avant la valeur de temps spécifiée.

    Les valeurs de temps doivent être exprimées dans le format UTC %A-%m-%jT%H:%M:%SZ.

Pour obtenir un exemple d'utilisation du paramètre de requête end, reportez-vous à la section Liste des sauvegardes cloud.

Paramètre de requête : limit

Le paramètre de requête limit indique le nombre maximum d'éléments à renvoyer.

Si les paramètres start ou end ne sont pas indiqués, limit=n renvoie les n éléments les plus récents.

Paramètre de requête : depth

Le paramètre de requête depth indique le niveau de détail d'une liste de ressources renvoyées. Celui-ci augmente plus la valeur de profondeur est élevée, comme indiqué dans le tableau suivant.

valeur depth
Informations renvoyées dans la liste
depth=0
Propriétés des noeuds et noms des enfants
depth=1
Propriétés des noeuds, noms et propriétés des enfants et noms des petits-enfants
depth=2
Propriétés des noeuds, noms et propriétés des enfants et sortie depth=0 pour les petits-enfants

Remarque -  Le paramètre de requête depth n'est pas pris en charge pour afficher la liste des journaux à l'aide de /api/log/v{1|2}, ni pour afficher la liste des pools, des projets, des systèmes de fichiers ou des LUN à l'aide de /api/storage/v{1|2}..

Exemple de demande de liste d'utilisateurs à l'aide du paramètre de requête depth :

GET /api/user/v1/users?depth=2 HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-User: root
X-Auth-Key: password-xxx

Exemple de réponse :

Pour des raisons de concision, la liste des utilisateurs est incomplète.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1558
X-Zfssa-Access-Api: 1.0

{
  "users": [
    {
      "name": "root",
...
    },
    {
      "name": "firstlast",
      "properties": {
        "logname": "firstlast",
        "type": "directory",
        "uid": uid,
        "fullname": "First Last",
        "require_annotation": false,
        "roles": [
          "basic"
        ],
        "kiosk_mode": false,
        "kiosk_screen": "status/dashboard"
      },
      "children": [
        {
          "name": "exceptions",
          "properties": {},
          "children": [],
          "list": [
            {
              "name": "auth-000",
              "properties": {
                "scope": "ad",
                "name": "*",
                "allow_domain": true,
                "allow_workgroup": false
              },
              "children": [],
              "list": []
            },
            {
              "name": "auth-001",
              "properties": {
                "scope": "alert",
                "allow_configure": true,
                "allow_post": true
              },
              "children": [],
              "list": []
            }
          ]
        },
        {
          "name": "preferences",
          "properties": {
            "locale": "C",
            "login_screen": "configuration/preferences",
            "session_timeout": 15,
            "cli_idle_timeout": "infinite",
            "advanced_analytics": false
          },
          "children": [
            {
              "name": "keys",
              "properties": {},
              "children": [],
              "list": []
            },
            {
              "name": "tokens",
              "properties": {},
              "children": [],
              "list": []
            }
          ],
          "list": []
        }
      ],
      "list": [],
      "href": "/api/user/v1/users/firstlast"
    },
    {
...
    }
  ]
}

Paramètre de requête : match

Le paramètre de requête matchproperty-name=value renvoie une liste de ressources dont la propriété indiquée a la valeur spécifiée.

L'exemple suivant renvoie la liste des utilisateurs pour lesquels la valeur de la propriété kiosk_mode est true :

match_kiosk_mode=true

L'exemple suivant renvoie la liste des utilisateurs pour lesquels la valeur de la propriété roles est super et celle de la propriété require_annotation est true :

match_roles='*super*'&match_require_annotation=true

Remarque -  Le paramètre de requête match_property-name=value n'est pas pris en charge pour afficher la liste des journaux à l'aide de /api/log/v{1|2}, ni pour afficher la liste des pools, des projets, des systèmes de fichiers ou des LUN à l'aide de /api/storage/v{1|2}.