Child pages
  • UAPI - Filter Output

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 

Introduction

Excerpt

You can use additional parameters to filter UAPI output.

Filter output

UAPI filters use four basic parameters:

parameterTypeDescriptionPossible values
api.filter BooleanWhether to enable filtering.
  • 1 — Enable filtering.
  • 0 — Disable filtering.
api.filter_columnstringThe return to match against.The name of one of the function's returns.
api.filter_termstringThe value to match.An integer or string value.
api.filter_typestring

The match type.

  • If the api.filter_term value is an integer, use a numeric operator.
  • If the api.filter_term value is a string, use a string operator.

This parameter defaults to contains.

Numeric operators:

  • eq — The column equals to the match value.
  • lt — The column is less than the match value. This match type cannot handle unlimited values.

  • lt_handle_unlimited — The column is less than the match value. This match type can handle unlimited values.

  • gt — The column is greater than the match value. This match type cannot handle unlimited values.
  • gt_handle_unlimited — The column is greater than the match value. This match type can handle unlimited values.
  • ne — The column does not equal to the match value.

    Note
    titleNote:

    We introduced the ne operator in cPanel & WHM version 56.


String operators:

  • contains — The column contains the match value's string. Not case-sensitive.

  • begins The column begins with the match value's string. Not case-sensitive.

  • ends The column ends with the match value's string. Not case-sensitive.

  • matches The column matches the value as a regular expression.

Other operators:

  • defined — The column contains a value.
  • undefined — The column does not contain a value.

    Note
    titleNote:

    We introduced the defined and undefined operators in cPanel & WHM version 58.


 

Examples

The following example function calls execute the Email::list_lists  function and filter the results to return email accounts with private mailing list archives.

Localtab Group


Localtab
activetrue
titlecPanel or Webmail Session URL


Code Block
languagetext
/execute/Email/list_lists?api.filter=1&api.filter_column=archive_private&api.filter_term=1&api.filter_type=eq

Include Page
LIB:_CallUAPIFromBrowserLink
LIB:_CallUAPIFromBrowserLink


Localtab
titleLiveAPI PHP Class


Code Block
languagephp
linenumberstrue
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List all of the mailing lists with private archives.
$private_lists = $cpanel->api2(
    'Email', 'list_lists', 
    array(
        'api.filter'          => '1',
        'api.filter_column'   => 'archive_private',
        'api.filter_term'     => '1',
        'api.filter_type'     => 'eq',
    ) 
);

Include Page
LIB:_LiveAPIPHPLink
LIB:_LiveAPIPHPLink


Localtab
titleLiveAPI Perl Class


Code Block
languageperl
linenumberstrue
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List all of the mailing lists with private archives.
my $private_lists = $cpliveapi->api2(
    'Email', 'list_lists',
    { 
        'api.filter'          => '1',
        'api.filter_column'   => 'archive_private',
        'api.filter_term'     => '1',
        'api.filter_type'     => 'eq',
    }
);

Include Page
LIB:_LiveAPIPerlLink
LIB:_LiveAPIPerlLink


Localtab
titlecPanel Template Toolkit


Code Block
languagexml
linenumberstrue
<!-- List all of the mailing lists with private archives. -->
[% execute('Email', 'list_lists', { 'api.filter' => '1', 'api.filter_column' => 'archive_private', 'api.filter_term' => '1', 'api.filter_type' => 'eq', }) %]

Include Page
LIB:_TTLink
LIB:_TTLink


Localtab
titleCommand Line


Code Block
uapi --user=username Email list_lists api.filter=1 api.filter_column=archive_private api.fitlerfilter_term=1 api.filter_type=eq



Localtab
titleOutput (JSON)


Code Block
languagetext
linenumberstrue
{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": [
    {
      "listid": "mylist_example.com",
      "accesstype":"public",
      "desthost": "hostname.example.com",
      "diskused": "17647",
      "humandiskused": "17.23 KB",
      "listadmin":"admin@example.com",
      "list": "mylist@example.com",
      "advertised": "0",
      "archive_private": "1",
      "subscribe_policy": "1"
    }
    {
      "listid": "superlist_example.com",
      "accesstype":"public",
      "desthost": "hostname.example.com",
      "diskused": "90120",
      "humandiskused": "90.12 KB",
      "listadmin":"charlie@example.com",
      "list": "superlist@example.com",
      "advertised": "1",
      "archive_private": "1",
      "subscribe_policy": "1"
    }
    {
      "listid": "list1_example.com",
      "accesstype":"public",
      "desthost": "hostname.example.com",
      "diskused": "16040",
      "humandiskused": "16.04 KB",
      "listadmin":"user@example.com",
      "list": "list1@example.com",
      "advertised": "1",
      "archive_private": "1",
      "subscribe_policy": "1"
    }
  ],
  "metadata": {
    "transformed": 1
  }
}



Use multiple filters

To use multiple filters on a single UAPI call, append an underscore (_) and a number to the end of each filter parameter.

For example, use the following parameters to pass two sets of filter information:

  • Pass the first set of filter information to the api.filter_type_0api_filter_column_0, and api_filter_term_0 parameters.
  • Pass the second set of filter information to the  api.filter_type_1 api_filter_column_1 , and  api_filter_term_1 parameters.
Note
titleNote:

Do not include more than one api.filter boolean parameter. 

For example, the following examples filter the Email::list_lists function's output to mailing lists that have private archives and do not display on the Mailman directory page.

 

Localtab Group


Localtab
activetrue
titlecPanel or Webmail Session URL


Code Block
languagetext
/execute/Email/list_lists?api.filter=1&api.filter_column_0=archive_private&api.filter_term_0=1&api.filter_type_0=eq&api.filter_column_1=advertised&api.filter_term_1=0&api.filter_type_1=eq

Include Page
LIB:_CallUAPIFromBrowserLink
LIB:_CallUAPIFromBrowserLink


Localtab
titleLiveAPI PHP Class


Code Block
languagephp
linenumberstrue
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List all of the mailing lists with private archives that do
// not display on the Mailman directory page.
$very_private_lists = $cpanel->uapi(
    'Email', 'list_lists', 
    array(
        'api.filter'            => '1',
        'api.filter_column_0'   => 'archive_private',
        'api.filter_term_0'     => '1',
        'api.filter_type_0'     => 'eq',
        'api.filter_column_1'   => 'advertised',
        'api.filter_term_1'     => '0',
        'api.filter_type_1'     => 'eq',
    ) 
);

Include Page
LIB:_LiveAPIPHPLink
LIB:_LiveAPIPHPLink


Localtab
titleLiveAPI Perl Class


Code Block
languageperl
linenumberstrue
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List all of the mailing lists with private archives that do
# not display on the Mailman directory page.
my $very_private_lists = $cpliveapi->uapi(
    'Email', 'list_lists',
    { 
        'api.filter'            => '1',
        'api.filter_column_0'   => 'archive_private',
        'api.filter_term_0'     => '1',
        'api.filter_type_0'     => 'eq',
        'api.filter_column_1'   => 'advertised',
        'api.filter_term_1'     => '0',
        'api.filter_type_1'     => 'eq',
    }
);

Include Page
LIB:_LiveAPIPerlLink
LIB:_LiveAPIPerlLink


Localtab
titlecPanel Template Toolkit


Code Block
languagexml
linenumberstrue
<!-- List all of the mailing lists with private archives that do not display on the Mailman directory page. -->
[% execute('Email', 'list_lists', { 'api.filter' => '1', 'api.filter_column_0' => 'archive_private', 'api.filter_term_0' => '1', 'api.filter_type_0' => 'eq','api.filter_column_1' => 'advertised', 'api.filter_term_1' => '0', 'api.filter_type_1' => 'eq', }) %]

Include Page
LIB:_TTLink
LIB:_TTLink


Localtab
titleCommand Line


Code Block
uapi --user=username Email list_lists api.filter=1 api.filter_column_0=archive_private api.fitlerfilter_term_0=1 api.filter_type_0=eq api.filter_column_1=advertised api.filter_term_1=0 api.filter_type_1=eq



Localtab
titleOutput (JSON)


Code Block
languagetext
linenumberstrue
{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": [
    {
      "listid": "mylist_example.com",
      "accesstype":"public",
      "desthost": "hostname.example.com",
      "diskused": "17647",
      "humandiskused": "17.23 KB",
      "listadmin":"admin@example.com",
      "list": "mylist@example.com",
      "advertised": "0",
      "archive_private": "1",
      "subscribe_policy": "1"
    }
  ],
  "metadata": {
    "transformed": 1
  }
}