manual:api:reference:host:get

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
manual:api:reference:host:get [2014/02/17 14:02]
127.0.0.1 external edit
manual:api:reference:host:get [2019/07/10 08:59] (current)
martins-v formatting change
Line 40: Line 40:
 |with_triggers|flag|Return only hosts that have triggers. \\ \\ Overrides the ''​with_monitored_triggers''​ parameter. | |with_triggers|flag|Return only hosts that have triggers. \\ \\ Overrides the ''​with_monitored_triggers''​ parameter. |
 |withInventory|flag|Return only hosts that have inventory data.| |withInventory|flag|Return only hosts that have inventory data.|
 +|evaltype|integer|Rules for tag searching. \\ \\ Possible values: \\ 0 - (default) And/Or; \\ 2 - Or. |
 +|tags|array/​object|Return only hosts with given tags. Exact match by tag and case-sensitive or case-insensitive search by tag value depending on operator value. \\ Format: ''<​nowiki>​[{"​tag":​ "<​tag>",​ "​value":​ "<​value>",​ "​operator":​ "<​operator>"​},​ ...]</​nowiki>''​.\\ An empty array returns all hosts. \\ \\ Possible operator values: \\ 0 - (default) Contains; \\ 1 - Equals. |
 ^  ||| ^  |||
-|selectGroups|query|Return ​the host groups that the host belongs to in the ''​groups''​ property. | +|selectGroups|query|Return ​a ''​[[:​manual/​api/​reference/​hostgroup/​object|groups]]''​ property with host groups ​data that the host belongs to.  | 
-|selectApplications|query|Return ​the applications from the host in the ''​applications''​ property. \\ \\ Support ​''​count''​. | +|selectTags|query|Return a ''​[[:​manual/​api/​reference/​host/​object#​host_tag|tags]]''​ property ​with host tags. | 
-|selectDiscoveries|query|Return ​the low level discoveries from the host in the ''​discoveries''​ property. \\ \\ Supports ''​count''​. | +|selectApplications|query|Return ​an ''​[[:​manual/​api/​reference/​application/​object|applications]]''​ property ​with host applications.\\ \\ Supports ​''​count''​. | 
-| selectDiscoveryRule | query | Return the LLD rule that created the host in the ''​discoveryRule''​ property. | +|selectDiscoveries|query|Return ​''​[[:​manual/​api/​reference/​discoveryrule/​object|discoveries]]''​ property ​with host low-level discovery rules.\\ \\ Supports ''​count''​. | 
-|selectGraphs|query|Return ​the graphs from the host in the ''​graphs''​ property. \\ \\ Supports ''​count''​. | +|selectDiscoveryRule |query|Return ​a ''​[[:​manual/​api/​reference/​discoveryrule/​object|discoveryRule]]''​ property with the low-level discovery ​rule that created the host (from host prototype ​in VMware monitoring) 
-| selectHostDiscovery | query | Return ​the host discovery object in the ''​hostDiscovery''​ property. \\ \\ The host discovery object links a discovered host to a host prototype or a host prototypes to an LLD rule and has the following properties: \\ ''​host''​ - //​(string)//​ host of the host prototype; \\  ''​hostid''​ - //​(string)//​ ID of the discovered host or host prototype; \\ ''​parent_hostid''​ - //​(string)//​ ID of the host prototype from which the host has been created; \\ ''​parent_itemid''​ - //​(string)//​ ID of the LLD rule that created the discovered host; \\ ''​lastcheck''​ - //​(timestamp)//​ time when the host was last discovered; \\ ''​ts_delete''​ - //​(timestamp)//​ time when a host that is no longer discovered will be deleted. | +|selectGraphs|query|Return ​''​[[:​manual/​api/​reference/​graph/​object|graphs]]''​ property ​with host graphs.\\ \\ Supports ''​count''​. | 
-|selectHttpTests|query|Return ​the web scenarios from the host in the ''​httpTests''​ property. \\ \\ Supports ''​count''​. | +|selectHostDiscovery |query|Return ​''​hostDiscovery''​ property ​with host discovery object data.\\ \\ The host discovery object links a discovered host to a host prototype or a host prototypes to an LLD rule and has the following properties: \\ ''​host''​ - //​(string)//​ host of the host prototype; \\  ''​hostid''​ - //​(string)//​ ID of the discovered host or host prototype; \\ ''​parent_hostid''​ - //​(string)//​ ID of the host prototype from which the host has been created; \\ ''​parent_itemid''​ - //​(string)//​ ID of the LLD rule that created the discovered host; \\ ''​lastcheck''​ - //​(timestamp)//​ time when the host was last discovered; \\ ''​ts_delete''​ - //​(timestamp)//​ time when a host that is no longer discovered will be deleted. | 
-|selectInterfaces|query|Return ​the host interfaces in the ''​interfaces''​ property. \\ \\ Supports ''​count''​. | +|selectHttpTests|query|Return ​an ''​[[:​manual/​api/​reference/​httptest/​object|httpTests]]''​ property ​with host web scenarios.\\ \\ Supports ''​count''​. | 
-|selectInventory|boolean/​array|Return ​the host inventory from the host in the ''​inventory''​ property. \\ \\ Possible values are ''​true''​ to return all of the data, or an array of property names to return only specific properties.| +|selectInterfaces|query|Return ​an ''​[[:​manual/​api/​reference/​hostinterface/​object|interfaces]]''​ property ​with host interfaces.\\ \\ Supports ''​count''​. | 
-|selectItems|query|Return ​the items from the host in the ''​items''​ property. \\ \\ Supports ''​count''​. | +|selectInventory|query|Return ​an ''​[[:​manual/​api/​reference/​host/​object#​host_inventory|inventory]]''​ property ​with host inventory ​data.  
-|selectMacros|query|Return ​the macros from the host in the ''​macros''​ property. | +|selectItems|query|Return ​an ''​[[:​manual/​api/​reference/​item/​object|items]]''​ property ​with host items.\\ \\ Supports ''​count''​. | 
-|selectParentTemplates|query|Return ​the templates that the host is linked to in the ''​parentTemplates''​ property. \\ \\ Supports ''​count''​. | +|selectMacros|query|Return ​''​[[:​manual/​api/​reference/​usermacro/​object|macros]]''​ property ​with host macros 
-|selectScreens|query|Return ​the screens from the host in the ''​screens''​ property. \\ \\ Supports ''​count''​. | +|selectParentTemplates|query|Return ​a ''​[[:​manual/​api/​reference/​template/​object|parentTemplates]]''​ property with templates that the host is linked to.\\ \\ Supports ''​count''​. | 
-|selectTriggers|query|Return ​the triggers from the host in the ''​triggers''​ property. \\ \\ Supports ''​count''​. |+|selectScreens|query|Return ​''​[[:​manual/​api/​reference/​screen/​object|screens]]''​ property ​with host screens.\\ \\ Supports ''​count''​. | 
 +|selectTriggers|query|Return ​''​[[:​manual/​api/​reference/​trigger/​object|triggers]]''​ property ​with host triggers.\\ \\ Supports ''​count''​. |
 ^  ||| ^  |||
 |filter ​ | object |Return only those results that exactly match the given filter.\\ \\ Accepts an array, where the keys are property names, and the values are either a single value or an array of values to match against. \\ \\ Allows filtering by interface properties. | |filter ​ | object |Return only those results that exactly match the given filter.\\ \\ Accepts an array, where the keys are property names, and the values are either a single value or an array of values to match against. \\ \\ Allows filtering by interface properties. |
 | limitSelects | integer | Limits the number of records returned by subselects. \\  \\ Applies to the following subselects: \\ ''​selectParentTemplates''​ - results will be sorted by ''​host'';​ \\ ''​selectInterfaces'';​ \\ ''​selectItems''​ - sorted by ''​name'';​ \\ ''​selectDiscoveries''​ - sorted by ''​name'';​ \\ ''​selectTriggers''​ - sorted by ''​description'';​ \\ ''​selectGraphs''​ - sorted by ''​name'';​ \\ ''​selectApplications''​ - sorted by ''​name'';​ \\ ''​selectScreens''​ - sorted by ''​name''​. | | limitSelects | integer | Limits the number of records returned by subselects. \\  \\ Applies to the following subselects: \\ ''​selectParentTemplates''​ - results will be sorted by ''​host'';​ \\ ''​selectInterfaces'';​ \\ ''​selectItems''​ - sorted by ''​name'';​ \\ ''​selectDiscoveries''​ - sorted by ''​name'';​ \\ ''​selectTriggers''​ - sorted by ''​description'';​ \\ ''​selectGraphs''​ - sorted by ''​name'';​ \\ ''​selectApplications''​ - sorted by ''​name'';​ \\ ''​selectScreens''​ - sorted by ''​name''​. |
 |search ​ | object |Return results that match the given wildcard search.\\ \\ Accepts an array, where the keys are property names, and the values are strings to search for. If no additional options are given, this will perform a ''​LIKE "​%…%"''​ search.\\ \\ Allows searching by interface properties. Works only with text fields. | |search ​ | object |Return results that match the given wildcard search.\\ \\ Accepts an array, where the keys are property names, and the values are strings to search for. If no additional options are given, this will perform a ''​LIKE "​%…%"''​ search.\\ \\ Allows searching by interface properties. Works only with text fields. |
 +|searchInventory | object | Return only hosts that have inventory data matching the given wildcard search. \\ \\ This parameter is affected by the same additional parameters as ''​search''​. |
 |sortfield|string/​array| Sort the result by the given properties. \\ \\ Possible values are: ''​hostid'',​ ''​host'',​ ''​name'',​ ''​status''​. ​ | |sortfield|string/​array| Sort the result by the given properties. \\ \\ Possible values are: ''​hostid'',​ ''​host'',​ ''​name'',​ ''​status''​. ​ |
-|countOutput|flag|These parameters being common for all ''​get''​ methods are described in detail in the [[2.4:manual:​api:​reference_commentary#​common_get_method_parameters|reference commentary]]. ​ |+|countOutput|boolean|These parameters being common for all ''​get''​ methods are described in detail in the [[manual:​api:​reference_commentary#​common_get_method_parameters|reference commentary]]. ​ |
 | editable |boolean|:::​| | editable |boolean|:::​|
-| excludeSearch |flag|:::|+| excludeSearch |boolean|:::|
 | limit |integer|:::​| | limit |integer|:::​|
-| nodeids |string/​array|:::​| 
 | output |query|:::| | output |query|:::|
-| preservekeys |flag|:::|+| preservekeys |boolean|:::|
 | searchByAny |boolean|:::​| | searchByAny |boolean|:::​|
 | searchWildcardsEnabled |boolean|:::​| | searchWildcardsEnabled |boolean|:::​|
 | sortorder | string/​array | ::: | | sortorder | string/​array | ::: |
-| startSearch |flag|:::|+| startSearch |boolean|:::|
 ==== Return values ==== ==== Return values ====
  
Line 84: Line 87:
  
 Request: Request:
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
     "​method":​ "​host.get",​     "​method":​ "​host.get",​
     "​params":​ {     "​params":​ {
-        "​output":​ "​extend",​ 
         "​filter":​ {         "​filter":​ {
             "​host":​ [             "​host":​ [
Line 103: Line 105:
  
 Response: Response:
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 138: Line 140:
             "​jmx_errors_from":​ "​0",​             "​jmx_errors_from":​ "​0",​
             "​jmx_error":​ "",​             "​jmx_error":​ "",​
-            "​name":​ "​Zabbix server"​+            "​name":​ "​Zabbix server", 
 +            "​description":​ "The Zabbix monitoring server.",​ 
 +            "​tls_connect":​ "​1",​ 
 +            "​tls_accept":​ "​1",​ 
 +            "​tls_issuer":​ "",​ 
 +            "​tls_subject":​ "",​ 
 +            "​tls_psk_identity":​ "",​ 
 +            "​tls_psk":​ ""
         },         },
         {         {
Line 171: Line 180:
             "​jmx_errors_from":​ "​0",​             "​jmx_errors_from":​ "​0",​
             "​jmx_error":​ "",​             "​jmx_error":​ "",​
-            "​name":​ "Linux server"​+            "​name":​ "Linux server", 
 +            "​description":​ "",​ 
 +            "​tls_connect":​ "​1",​ 
 +            "​tls_accept":​ "​1",​ 
 +            "​tls_issuer":​ "",​ 
 +            "​tls_subject":​ "",​ 
 +            "​tls_psk_identity":​ "",​ 
 +            "​tls_psk":​ ""
         }         }
     ],     ],
Line 177: Line 193:
 } }
 </​code>​ </​code>​
- 
 === Retrieving host groups === === Retrieving host groups ===
  
Line 183: Line 198:
  
 Request: Request:
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 202: Line 217:
  
 Response: Response:
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 233: Line 248:
  
 Request: Request:
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 251: Line 266:
  
 Response: Response:
-<​code ​js>+<​code ​java>
 { {
     "​jsonrpc":​ "​2.0",​     "​jsonrpc":​ "​2.0",​
Line 272: Line 287:
 } }
 </​code>​ </​code>​
 +
 +=== Searching by host inventory data ===
 +
 +Retrieve hosts that contain "​Linux"​ in the host inventory "​OS"​ field.
 +
 +Request:
 +<code java>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​method":​ "​host.get",​
 +    "​params":​ {
 +        "​output":​ [
 +            "​host"​
 +        ],
 +        "​selectInventory":​ [
 +            "​os"​
 +        ],
 +        "​searchInventory":​ {
 +            "​os":​ "​Linux"​
 +        }
 +    },
 +    "​id":​ 2,
 +    "​auth":​ "​7f9e00124c75e8f25facd5c093f3e9a0"​
 +}
 +</​code>​
 +
 +Response:
 +<code java>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​result":​ [
 +        {
 +            "​hostid":​ "​10084",​
 +            "​host":​ "​Zabbix server",​
 +            "​inventory":​ {
 +                "​os":​ "Linux Ubuntu"​
 +            }
 +        },
 +        {
 +            "​hostid":​ "​10107",​
 +            "​host":​ "Linux server",​
 +            "​inventory":​ {
 +                "​os":​ "Linux Mint"
 +            }
 +        }
 +    ],
 +    "​id":​ 1
 +}
 +</​code>​
 +
 +=== Searching by host tags ===
 +
 +Retrieve hosts that have tag "Host name" equal to "Linux server"​.
 +
 +Request:
 +<code java>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​method":​ "​host.get",​
 +    "​params":​ {
 +        "​output":​ ["​hostid"​],​
 +        "​selectTags":​ "​extend",​
 +        "​evaltype":​ 0,
 +        "​tags":​ [
 +            {
 +                "​tag":​ "Host name",
 +                "​value":​ "Linux server",​
 +                "​operator":​ 1
 +            }
 +        ]
 +    },
 +    "​auth":​ "​7f9e00124c75e8f25facd5c093f3e9a0",​
 +    "​id":​ 1
 +}
 +</​code>​
 +
 +Response:
 +<code java>
 +{
 +    "​jsonrpc":​ "​2.0",​
 +    "​result":​ [
 +        {
 +            "​hostid":​ "​10085",​
 +            "​tags":​ [
 +                {
 +                    "​tag":​ "Host name",
 +                    "​value":​ "Linux server"​
 +                },
 +                {
 +                    "​tag":​ "​OS",​
 +                    "​value":​ "RHEL 7"
 +                }
 +            ]
 +        }
 +    ],
 +    "​id":​ 1
 +}
 +</​code>​
 +
 ==== See also ==== ==== See also ====
  
-  * [[2.4:​manual:​api:​reference:​host:​getobjects|host.getobjects]] +  * [[manual:​api:​reference:​hostgroup:​object#​host_group|Host group]] 
-  * [[2.4:manual:​api:​reference:​hostgroup:​object#​host_group|Host group]] +  * [[manual:​api:​reference:​template:​object#​template|Template]] 
-  * [[2.4:manual:​api:​reference:​template:​object#​template|Template]] +  * [[manual:​api:​reference:​usermacro:​object#​hosttemplate_level_macro|User macro]] 
-  * [[2.4:manual:​api:​reference:​usermacro:​object#​hosttemplate_level_macro|User macro]] +  * [[manual:​api:​reference:​hostinterface:​object#​host_interface|Host interface]] 
-  * [[2.4:manual:​api:​reference:​hostinterface:​object#​host_interface|Host interface]]+
 ==== Source ==== ==== Source ====
  
-CHost::​get() in //​frontends/​php/​api/​classes/​CHost.php//​.+CHost::​get() in //​frontends/​php/​include/classes/​api/​services/​CHost.php//​.