.. _filters: Filters =================== aXAPI filters work with GET methods to specify that only certain records of interest will appear in the responses. Without filters, all the records are returned by default. The aXAPI filter mechanisms provide two aspects of control for all the GET methods. Both of the following mechanisms can work together. * `Paging Mechanism`_ - handles a huge amount of data records under an aXAPI endpoint. * `Field Filtering Mechanism`_ - picks up special data records that match specified fields. The stats and oper filters work a bit differently for the GET methods, so their usage is limited to a subset of URIs. * `Statistics Data Filtering`_ - for use with URIs that include the ``/stats`` endpoint. * `Oper Endpoint Filtering`_ - for use with URIs that include the ``/oper`` endpoint. The user tag filters are limited to a subset of SSL Insight objects. They are used to automatically mark an object that is created in the SSLi Services GUI. * `User Tag Filtering`_ - for use with SSLi objects that include the **"user-tag":"Security"** property. Paging Mechanism ---------------------- The paging mechanism helps to break up large responses into more manageable chunks. The filter keywords ``total``, ``start``, and ``count`` are reserved for the paging mechanism. * total - shows how many records currently exist. * start - indicates an index from which those records will be returned. * count - indicates a limitation. It controls how many records should be returned. For example, if there are four slb servers, the ``total=true`` filter shows the total count of slb servers:: curl -k GET https://10.10.10.10/axapi/v3/slb/server?total=true \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "total-count":4 } If there are four slb servers, the ``start=3`` filter shows the server at index number 3: [d1, d2, s1, **s2**]:: curl -k GET https://10.10.10.10/axapi/v3/slb/server?start=3 \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "server-list": [ { "name":"s2", "host":"1.1.1.2", "action":"enable", "template-server":"default", "health-check-disable":0, "conn-limit":8000000, "no-logging":0, "weight":1, "slow-start":0, "spoofing-cache":0, "stats-data-action":"stats-data-enable", "extended-stats":0, "uuid":"a7ec1a00-3270-11df-a8af-000d480a65d0", "a10-url":"/axapi/v3/slb/server/s2" } ] } If there are four slb servers, the ``start=1&count=1`` filters show a list of servers starting at index number 1, but only a list of 1: [d1, **d2**, s1, s2]:: curl -k GET https://10.10.10.10/axapi/v3/slb/server?start=1&count=1 \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "server-list": [ { "name":"d2", "host":"1.1.1.4", "action":"enable", "template-server":"default", "health-check-disable":0, "conn-limit":8000000, "no-logging":0, "weight":1, "slow-start":0, "spoofing-cache":0, "stats-data-action":"stats-data-enable", "extended-stats":0, "uuid":"b059da1a-3270-11df-a8af-000d480a65d0", "a10-url":"/axapi/v3/slb/server/d2" } ] } Field Filtering Mechanism ---------------------- Field filtering is used to select a matched set of instances as returned records. A filtering keyword is simply a field keyword defined within the schema file. Currently, only the string type field can be supported. The matching rule is that a field’s value contains the specified string from filter. For example, the field ``name`` is used as a filter to find slb servers whose names contain the character **s**:: curl -k GET https://10.10.10.10/axapi/v3/slb/server?name=s \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "server-list": [ { "name":"s1", "host":"1.1.1.1", "action":"disable", "template-server":"default", "health-check-disable":0, "conn-limit":8000000, "no-logging":0, "weight":1, "slow-start":0, "spoofing-cache":0, "stats-data-action":"stats-data-enable", "extended-stats":0, "uuid":"a25672e8-3270-11df-a8af-000d480a65d0", "a10-url":"/axapi/v3/slb/server/s1" }, { "name":"s2", "host":"1.1.1.2", "action":"enable", "template-server":"default", "health-check-disable":0, "conn-limit":8000000, "no-logging":0, "weight":1, "slow-start":0, "spoofing-cache":0, "stats-data-action":"stats-data-enable", "extended-stats":0, "uuid":"a7ec1a00-3270-11df-a8af-000d480a65d0", "a10-url":"/axapi/v3/slb/server/s2" } ] } The combination of multiple fields as filters means an AND relationship, such as using the ``name`` & ``action`` fields to find slb servers that start with s and are enabled:: curl -k GET https://10.10.10.10/axapi/v3/slb/server?name=s&action=enable \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "server-list": [ { "name":"s2", "host":"1.1.1.2", "action":"enable", "template-server":"default", "health-check-disable":0, "conn-limit":8000000, "no-logging":0, "weight":1, "slow-start":0, "spoofing-cache":0, "stats-data-action":"stats-data-enable", "extended-stats":0, "uuid":"a7ec1a00-3270-11df-a8af-000d480a65d0", "a10-url":"/axapi/v3/slb/server/s2" } ] } It is possible to use field filtering and paging mechanisms together, such as using the ``name`` field with the ``total`` & ``count`` filters to find the total number of slb servers whose names start with s, starting from index number 0, but only a list of 1:: curl -k GET https://10.10.10.10/axapi/v3/slb/server?name=s&start=0&count=1 \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "server-list": [ { "name":"s1", "host":"1.1.1.1", "action":"disable", "template-server":"default", "health-check-disable":0, "conn-limit":8000000, "no-logging":0, "weight":1, "slow-start":0, "spoofing-cache":0, "stats-data-action":"stats-data-enable", "extended-stats":0, "uuid":"a25672e8-3270-11df-a8af-000d480a65d0", "a10-url":"/axapi/v3/slb/server/s1" } ] } Statistics Data Filtering ---------------------- Some schema files define extended statistics data. To get this part of the data, you need to use the corresponding filter within the URIs that include the ``/stats`` endpoint. For example, slb virtual port has such statistics data, according to its L7 protocol. **Basic Statistics** The basic statistics are available at the statistics data URI: /axapi/v3/slb/virtual-server/{name}/port/{port-number}+{protocol}/stats:: curl -k GET https://10.10.10.10/axapi/v3/slb/virtual-server/vs1/port/80+http/stats \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Response { "port": { "stats": { "curr_conn": 0, "total_l4_conn": 0, "total_l7_conn": 0, "total_tcp_conn": 0, "total_conn": 0, "total_fwd_bytes": 0, "total_fwd_pkts": 0, "total_rev_bytes": 0, "total_rev_pkts": 0, "total_dns_pkts": 0, "total_mf_dns_pkts": 0, "es_total_failure_actions": 0, "compression_bytes_before": 0, "compression_bytes_after": 0, "compression_hit": 0, "compression_miss": 0, "compression_miss_no_client": 0, "compression_miss_template_exclusion": 0, "curr_req": 0, "total_req": 0, "total_req_succ": 0, "peak_conn": 0, "curr_conn_rate": 0, "last_rsp_time": 0, "fastest_rsp_time": 0, "slowest_rsp_time": 0 }, "a10-url": "/axapi/v3/slb/virtual-server/vs1/port/80+http/stats", "port-number": 80, "protocol": "http" } } **Extended HTTP Statistics** The extended statistics for the slb virtual port are available with the addition of the ``http_vport=true`` filter:: curl -k GET https://10.10.10.10/axapi/v3/slb/virtual-server/vs1/port/80+http/stats?http_vport=true \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "port": { "stats": { "http_vport": { "status_200": 0, "status_201": 0, "status_202": 0, "status_203": 0, "status_204": 0, "status_205": 0, "status_206": 0, "status_207": 0, "status_100": 0, "status_101": 0, "status_102": 0, "status_103": 0, "status_300": 0, "status_301": 0, "status_302": 0, "status_303": 0, "status_304": 0, "status_305": 0, "status_306": 0, "status_307": 0, "status_400": 0, "status_401": 0, "status_402": 0, "status_403": 0, "status_404": 0, "status_405": 0, "status_406": 0, "status_407": 0, "status_408": 0, "status_409": 0, "status_410": 0, "status_411": 0, "status_412": 0, "status_413": 0, "status_414": 0, "status_415": 0, "status_416": 0, "status_417": 0, "status_418": 0, "status_422": 0, "status_423": 0, "status_424": 0, "status_425": 0, "status_426": 0, "status_449": 0, "status_450": 0, "status_500": 0, "status_501": 0, "status_502": 0, "status_503": 0, "status_504": 0, "status_504_ax": 0, "status_505": 0, "status_506": 0, "status_507": 0, "status_508": 0, "status_509": 0, "status_510": 0, "status_1xx": 0, "status_2xx": 0, "status_3xx": 0, "status_4xx": 0, "status_5xx": 0, "status_6xx": 0, "status_unknown": 0, "ws_handshake_request": 0, "ws_handshake_success": 0, "ws_client_switch": 0, "ws_server_switch": 0, "REQ_10u": 0, "REQ_20u": 0, "REQ_50u": 0, "REQ_100u": 0, "REQ_200u": 0, "REQ_500u": 0, "REQ_1m": 0, "REQ_2m": 0, "REQ_5m": 0, "REQ_10m": 0, "REQ_20m": 0, "REQ_50m": 0, "REQ_100m": 0, "REQ_200m": 0, "REQ_500m": 0, "REQ_1s": 0, "REQ_2s": 0, "REQ_5s": 0, "REQ_OVER_5s": 0 } }, "a10-url": "/axapi/v3/slb/virtual-server/vs1/port/80+http/stats", "port-number": 80, "protocol": "http" } } .. note:: The paging mechanism and field filtering mechanism cannot work with extended statistics filtering. **Reserved Filter Statistics** For typical config endpoints, there is a reserved ON/OFF filter called ``stats`` for getting config data and basic statistics data at the same time:: curl -k GET https://10.10.10.10/axapi/v3/slb/virtual-server/vs1/port/80+http?stats=true \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "port": { "port-number": 80, "protocol": "http", "range": 0, "conn-limit": 8000000, "reset": 0, "no-logging": 0, "use-alternate-port": 0, "action": "enable", "def-selection-if-pref-failed": "def-selection-if-pref-failed", "skip-rev-hash": 0, "message-switching": 0, "force-routing-mode": 0, "reset-on-server-selection-fail": 0, "clientip-sticky-nat": 0, "extended-stats": 0, "snat-on-vip": 0, "stats-data-action": "stats-data-enable", "syn-cookie": 0, "no-auto-up-on-aflex": 0, "no-dest-nat": 0, "scaleout-bucket-count": 32, "auto": 0, "ipinip": 0, "rtp-sip-call-id-match": 0, "use-rcv-hop-for-resp": 0, "redirect-to-https": 0, "template-virtual-port": "default", "uuid": "6e9cb4dc-3278-11df-a8af-000d480a65d0", "stats": { "curr_conn": 0, "total_l4_conn": 0, "total_l7_conn": 0, "total_tcp_conn": 0, "total_conn": 0, "total_fwd_bytes": 0, "total_fwd_pkts": 0, "total_rev_bytes": 0, "total_rev_pkts": 0, "total_dns_pkts": 0, "total_mf_dns_pkts": 0, "es_total_failure_actions": 0, "compression_bytes_before": 0, "compression_bytes_after": 0, "compression_hit": 0, "compression_miss": 0, "compression_miss_no_client": 0, "compression_miss_template_exclusion": 0, "curr_req": 0, "total_req": 0, "total_req_succ": 0, "peak_conn": 0, "curr_conn_rate": 0, "last_rsp_time": 0, "fastest_rsp_time": 0, "slowest_rsp_time": 0 } } } .. note:: This is not a ``/stats`` endpoint, but the addition of a ``?stats=true`` filter. The extended statistics cannot work in this way. Oper Endpoint Filtering ---------------------- The oper endpoints end with the keyword ``/oper``. These are used to retrieve dynamic operational status information from the back-end to see things like available memory, status of fans, admins logged in, etc. Filters are now also available for getting the status plus available extras such as total number of elements, a single record, and the configuration. The valid filters are defined by the oper field in the schema file. As the field filtering mechanism does, it accepts a string value. The paging mechanism is also supported. As of now, its scope is not the object instance. Instead, it works for oper fields within a multiple block. Used by itself, the ``/oper`` endpoint will show operational data for each element within a collection or intermediate resource:: curl -k GET https://10.10.10.10/axapi/v3/admin-session/oper \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Response { "admin-session": { "oper" : { "session-list": [ { "sid":"1", "name":"admin", "src_ip":"10.10.10.11", "type":"WEB", "cfg_mode":"No" }, { "sid":"*3", "name":"admin", "src_ip":"10.10.10.12", "type":"WEBSERVICE", "cfg_mode":"No" } ] }, "a10-url":"/axapi/v3/admin-session/oper" } } Used with the ``total`` paging mechanism, it will find the total number of elements at an endpoint. The back-end determines if oper field filtering mechanism works or not:: curl -k GET https://10.10.10.10/axapi/v3/admin-session/oper?total=true \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "total-count":2 } In the following example, the ``start`` paging mechanism is used to find a single object instance record at an endpoint. The back-end determines if oper field filtering mechanism works or not:: curl -k GET https://10.10.10.10/axapi/v3/slb/server/s2/oper?start=0 \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "server": { "oper": { "state": "Down" }, "a10-url": "/axapi/v3/slb/server/s2/oper", "name": "s2" } } For typical config endpoints, there is a reserved ON/OFF filter called ``oper`` for getting config data and basic operational data at the same time:: curl -k GET https://10.10.10.10/axapi/v3/slb/server/s1?oper=true \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "server": { "name":"s1", "host":"1.1.1.1", "action":"disable", "template-server":"default", "health-check-disable":0, "conn-limit":8000000, "no-logging":0, "weight":1, "slow-start":0, "spoofing-cache":0, "stats-data-action":"stats-data-enable", "extended-stats":0, "uuid":"a25672e8-3270-11df-a8af-000d480a65d0", "oper" : { "state":"Disabled" } } } .. note:: This is not the ``/oper`` endpoint, but the addition of the ``?oper=true`` filter. User Tag Filtering ---------------------- The user tag filter is used by the GUI to group SSLi objects together by auto-configuring them with the **Security** string in the **user-tag** property. You can use these tags to filter your search results based on the string. For example, when you create SSLi Services objects in the GUI for SSLi_vip_001, they will automatically be tagged with **user-tag Security** as seen in the ``show run`` command of the CLI:: ! slb server SSLi_vip_001_server_001 100.100.100.8 user-tag Security port 0 tcp ... ! slb service-group SSLi_vip_001_SSLi tcp user-tag Security member SSLi_vip_001_server_001 8080 ... ! slb template client-ssl SSLi_vip_001_client_ssl user-tag Security forward-proxy-bypass web-category health-and-medicine ... ! slb virtual-server SSLi_vip_001 0.0.0.0 acl name acl_SSLi_vip_001 user-tag Security port 0 tcp ... ! end In the case of searching by tag to retrieve all your SLB Security servers, you can use the ``user-tag=Security`` filter on your GET request. In the response, you will see the output of **"user-tag":"Security"** in the SLB servers that were auto-configured with that property:: curl -k GET https://10.10.10.10/axapi/v3/slb/server?user-tag=Security \ -H "Content-Type:application/json" \ -H "Authorization: A10 c223169c3ab18f9e3826b9df215c2b" #Filtered Response { "server-list": [ { "name":"SSLi_vip_001_server_001", "host":"100.100.100.8", "action":"enable", "template-server":"default", "health-check-disable":0, "conn-limit":8000000, "no-logging":0, "weight":1, "slow-start":0, "spoofing-cache":0, "stats-data-action":"stats-data-enable", "extended-stats":0, "uuid":"f63899d6-c91e-11e5-ae81-fa163e0b5a56", "user-tag":"Security", "port-list": [ { "port-number":0, "protocol":"tcp", "range":0, "template-port":"default", "action":"enable", "no-ssl":0, "health-check-disable":1, "weight":1, "conn-limit":8000000, "no-logging":0, "stats-data-action":"stats-data-enable", "extended-stats":0, "uuid":"f63aa1cc-c91e-11e5-ae81-fa163e0b5a56", "a10-url":"/axapi/v3/slb/server/SSLi_vip_001_server_001/port/0+tcp" }, { "port-number":0, "protocol":"udp", "template-port":"default", "action":"enable", "no-ssl":0, "health-check-disable":1, "weight":1, "conn-limit":8000000, "no-logging":0, "stats-data-action":"stats-data-enable", "extended-stats":0, "uuid":"f63be096-c91e-11e5-ae81-fa163e0b5a56", "a10-url":"/axapi/v3/slb/server/SSLi_vip_001_server_001/port/0+udp" }, { "port-number":8080, "protocol":"tcp", "range":0, "template-port":"default", "action":"enable", "no-ssl":0, "health-check-disable":1, "weight":1, "conn-limit":8000000, "no-logging":0, "stats-data-action":"stats-data-enable", "extended-stats":0, "uuid":"f63be776-c91e-11e5-ae81-fa163e0b5a56", "a10-url":"/axapi/v3/slb/server/SSLi_vip_001_server_001/port/8080+tcp" } ], "a10-url":"/axapi/v3/slb/server/SSLi_vip_001_server_001" } ] }