See www.zabbix.com for the official Zabbix site.

Docs/specs/ZBXNEXT-1485

From Zabbix.org
Jump to: navigation, search

Redesigning the output parameter for get methods

ZBXNEXT-1485

Status: v1.1

Owner: Jelisejev (talk)

Summary

The output parameter will be redesigned to support only three values: all, count and arrays of property names.

Specification

Details

Frontend changes
  • Arrays of property names must be used instead of output shorten or refer.
  • output: count must be used instead of countOutput.

API changes

The output parameter
  • Three possible values must be supported:
    • all - return all object properties;
    • count - return the number of results;
    • array of properties - return only the given properties.
  • extend value will become deprecated and remain as an alias of all.
  • shorten and refer must be removed without any backward compatibility support; arrays with specific property names must be used instead.
  • The default value must be all.
  • An error must be triggered in an incorrect output value is given saying: "Incorrect value "%VALUE%" for the "output" parameter."
  • Listed property name validation must not be implemented in this task.
The countOutput parameter
  • The countOutput parameter will become deprecated and must reuse the code behind output: count.
  • The behavior of the groupCount parameter must not be affected.
Deprecated parameters
  • If a deprecated output value or the countOutput parameter is used, a E_USER_NOTICE error must be triggered using trigger_error() saying either "The "%VALUE% value for the "output" parameter is deprecated" or "The "countOutput" parameter is deprecated".
  • The deprecated values and parameters will be dropped in Zabbix 2.4.

Documentation

The following documentation sections must be updated:

  • The API changelog; all deprecated parameters and values must be explicitly highlighted.
  • The description of the output parameter in the 1. Reference commentary
  • All subselects in the 2.2 API reference.

Test cases

  • All get methods return all data if the output parameter is not given.
  • All get methods support output: count and output: all.
  • All get methods and subselects throw an error when using shorten and extend.
  • A notice is triggered in the frontend when using the countOutput parameter, or output: extend.

API request examples

The following examples demonstrate how to use the affected parameters.

Output shorten
// request before
// retrieve the itemid property of all items
{
    "jsonrpc": "2.0",
    "method": "item.get",
    "params": {
        "output": "shorten"
    },
    "id": 3,
    "auth": "c165e6136dce18e930417335ece7aae8"
}

// request after
{
    "jsonrpc": "2.0",
    "method": "item.get",
    "params": {
        "output": ["itemid"]
    },
    "id": 3,
    "auth": "c165e6136dce18e930417335ece7aae8"
}

// response
{
    "jsonrpc": "2.0",
    "result": [
        {
            "itemid": "23327"
        }
    ],
    "id": 3
}
Output refer

Example 1: item.get

// request before
// retrieve the itemid and hostid properties for all items on a host
{
    "jsonrpc": "2.0",
    "method": "item.get",
    "params": {
        "output": "refer",
        "hostids": "10084"
    },
    "id": 3,
    "auth": "c165e6136dce18e930417335ece7aae8"
}

// request after
{
    "jsonrpc": "2.0",
    "method": "item.get",
    "params": {
        "output": ["itemid", "hostid"],
        "hostids": "10084"
    },
    "id": 3,
    "auth": "c165e6136dce18e930417335ece7aae8"
}

// response
{
    "jsonrpc": "2.0",
    "result": [
        {
            "itemid": "23327",
            "hostid": "10084"
        }
    ],
    "id": 3
}


Example 2: graph.get

// request before
// retrieve the graphid property and hosts for all graphs on a host
{
    "jsonrpc": "2.0",
    "method": "graph.get",
    "params": {
        "output": "refer",
        "hostids": "10084"
    },
    "id": 5,
    "auth": "c165e6136dce18e930417335ece7aae8"
}

// an equivalent request, but this one will also return a hostid property for the graph object due to a bug
{
    "jsonrpc": "2.0",
    "method": "graph.get",
    "params": {
        "output": [
            "graphid"
        ],
        "selectHosts": "refer",
        "hostids": "10084"
    },
    "id": 5,
    "auth": "c165e6136dce18e930417335ece7aae8"
}

// request after
{
    "jsonrpc": "2.0",
    "method": "graph.get",
    "params": {
        "output": ["graphid"],
        "selectHosts": [
            "hostid"
        ]
    },
    "id": 5,
    "auth": "c165e6136dce18e930417335ece7aae8"
}

// response
{
    "jsonrpc": "2.0",
    "result": [
        {
            "hosts": [
                {
                    "hostid": "10084"
                }
            ],
            "graphid": "517"
        }
    ],
    "id": 5
}
CountOutput
// request before
// return the total number of items
{
    "jsonrpc": "2.0",
    "method": "item.get",
    "params": {
        "countOutput": 1
    },
    "id": 8,
    "auth": "c165e6136dce18e930417335ece7aae8"
}

// request after
{
    "jsonrpc": "2.0",
    "method": "item.get",
    "params": {
        "output": "count"
    },
    "id": 8,
    "auth": "c165e6136dce18e930417335ece7aae8"
}

// response
{
    "jsonrpc": "2.0",
    "result": "593",
    "id": 8
}

ChangeLog

  • v1.1
    • Added a note that only subselects that currently support refer must support arrays of property names.
    • Removed the changes described in ZBXNEXT-1491.