Search for resources

• Boolean: Search on boolean values.
• Choice: Search fields that have a defined set of valid values
• ID: Search unique ID's
• Null: Search on null values
• Numeric: Search on numeric values
• String: Search on string values
• Date range: Search on date values

Tip As mentioned in Notes about Resource Property Values, when you use the API directly, you use 0 to represent a null value. However, to search for a null value you use a Null search. You do not perform a numeric search for 0.

• The name of the field (the property of the resource) that you are searching -- note that field names are case-sensitive
• A value to search for (or, for date values, a range of dates)
• An operator to test against field values (this does not apply to date-value searches)
• The maximum number of items to return (default is 5000)

Tip When performing an ID search, you do not include the name of the field as it is assumed to be the ID field.

# Set search criteria
search_criteria = api.SearchCriteria()
search_criteria.field_name = "name"
search_criteria.string_test = "equal"
search_criteria.string_value = name

# Create a search filter
search_filter = api.SearchFilter(None, [search_criteria])
search_filter.max_items = 1

# Perform the search
policies_api = api.PoliciesApi(api.ApiClient(configuration))
policies_api.search_policies(api_version, search_filter=search_filter)

# Set search criteria for platform
policy_criteria = api.SearchCriteria()
policy_criteria.field_name = "policyID"
policy_criteria.numeric_test = "equal"
policy_criteria.numeric_value = policy_id

# Set search criteria for relay
relay_criteria = api.SearchCriteria()
relay_criteria.field_name = "relayListID"
relay_criteria.numeric_test = "equal"
relay_criteria.numeric_value = relay_list_id

# Create the search filter
search_filter = api.SearchFilter(None, [policy_criteria, relay_criteria])

Searchable fields

1. Click an operation that returns the type of resource that you are searching. For example, the Describe a Computer operation returns a computer resource.
2. Click 200 successful operation in the Responses section.
3. Read the description of the field. The descriptions of searchable fields contain "Searchable as datatype", where datatype can be String, Numeric, ID, Date, Boolean, and Choice.

• The locale field of any object
• Most fields that have an object as a value, such as the policySettings field of a Policy object (see "Search computer sub-objects" below for exceptions).

Search computer sub-objects

{
    "hostName": "gui2-336",
    "displayName": "",
    "description": "",
    ...
    "interfaces": {
      "name": "ethernet",
      ...
    },
    "ec2VirtualMachineSummary": {
      "accountID": "123456789012",
      "availabilityZone": "ap-northeast-1",
      ...
    },
    ...
    "ID": 201
}

Tip Use the expand parameter when you search to include only the information that you need in the returned computer objects. For more information, see "Minimize computer response size" in the Performance Tips guide.

# Search criteria
computer_criteria = api.SearchCriteria()
computer_criteria.field_name = "ec2VirtualMachineSummary/accountID"
computer_criteria.string_test = "equal"
computer_criteria.string_value = account_id

# Search filter
max_items = None
search_filter = api.SearchFilter(max_items, computer_criteria)

# Include only the EC2 virtual machine summary in the returned computers
expand = api.Expand(api.Expand.ec2_virtual_machine_summary)

# Perform the search
computers_api = api.ComputersApi(api.ApiClient(configuration))

return computers_api.search_computers(api_version, search_filter=search_filter, expand=expand.list(), overrides=False)

Field names in Python code

1. Capitalize the letter that directly follows each underscore.
2. Delete each underscore.

Use wildcards in string searches

• %: Matches zero or more characters
• _; Matches 1 character

# Create the search criteria
search_criteria = api.SearchCriteria()
search_criteria.field_name = "name"
search_criteria.string_test = "equal"
search_criteria.string_value = "Base%"

Tip To disable wildcard searches, set the `stringWildcards` property of the `SearchCriteria` object to `false`. search_criteria.string_wildcards = "false"

Perform a date-range search

• FirstDate: The earlier date in the range. The default value is the earliest possible date.
• FirstDateInclusive: A boolean value that indicates whether the range includes the FirstDate (true) or not (false). The default value is false.
• LastDate: The later date in the range. The default value is the latest possible date.
• LastDateInclusive: A boolean value that indicates whether the range includes the LasteDate (true) or not (false). The default value is false.

# Time that rules were last updated
current_time_in_ms = int(round(time.time() * 1000))
last_updated_in_ms = current_time_in_ms - (num_days * 24 * 60 * 60 * 1000)

# Set search criteria for the date range
search_criteria = api.SearchCriteria()
search_criteria.field_name = "lastUpdated"
search_criteria.first_date_value = last_updated_in_ms
search_criteria.last_date_value = current_time_in_ms
search_criteria.first_date_inclusive = True
search_criteria.last_date_inclusive = True

# Create a search filter
search_filter = api.SearchFilter(None, [search_criteria])

# Perform the search
intrusion_prevention_rules_api = api.IntrusionPreventionRulesApi(api.ApiClient(configuration))
return intrusion_prevention_rules_api.search_intrusion_prevention_rules(api_version, search_filter=search_filter)

Search for null values

# Search criteria
computer_criteria = api.SearchCriteria()
computer_criteria.field_name = "lastSendPolicySuccess"
computer_criteria.null_test = True

# Search filter
max_items = None
search_filter = api.SearchFilter(max_items, computer_criteria)

# Include minimal information in the returned computers
expand = api.Expand(api.Expand.none)

# Perform the search
computers_api = api.ComputersApi(api.ApiClient(configuration))

return computers_api.search_computers(api_version, search_filter=search_filter, expand=expand.list(), overrides=False)

Sort order

• Boolean, Choice, Null, and String searches: Sorted by the ID of the returned object, in ascending order.
• ID searches: Sorted by ID. The operator determines whether the order is ascending or descending:
  • less-than and less-than-or-equal: descending
  • All other operators: ascending
• Numeric searches: Sorted by the field that is searched. The operator determines whether the order is ascending or descending:
  • less-than and less-than-or-equal: descending
  • All other operators: ascending
  When multiple search results have the same value for the searched field, those objects are secondarily sorted by ID.
• Date searches: Sorted by the field that is searched. The date range parameters that are provided for the search determine the sort order:
  • Only LastDate is provided: descending
  • Any other combination: ascending
  When multiple search results have the same value for the searched date field, those objects are secondarily sorted by ID.
• Multiple search criteria: Searches that use multiple search criteria are sorted by ID (ascending), regardless of the default sort order of the individual criteria.

Limit search results and paging

• Search by ID using the greater-than operator
• Use maxItems to estabish the page size
• Calculate the value of the ID to search on based on the highest ID in the previous page of results.

# Set search criteria
search_criteria = api.SearchCriteria()
search_criteria.id_value = 0
search_criteria.id_test = "greater-than"

# Create a search filter with maximum returned items
page_size = 10
search_filter = api.SearchFilter()
search_filter.max_items = page_size
search_filter.search_criteria = [search_criteria]

# Include the minimum information in the returned Computer objects
expand = api.Expand(api.Expand.none)

# Perform the search and do work on the results
computers_api = api.ComputersApi(api.ApiClient(configuration))
paged_computers = []


while True:
    computers = computers_api.search_computers(api_version, search_filter=search_filter, expand=expand.list(), overrides=False)
    num_found = len(computers.computers)
    current_paged_computers = []
    if num_found == 0:
        print("No computers found.")
        break

    for computer in computers.computers:
        current_paged_computers.append(computer)

    paged_computers.append(current_paged_computers)

    # Get the ID of the last computer in the page and return it with the number of computers on the page
    last_id = computers.computers[-1].id
    search_criteria.id_value = last_id
    print("Last ID: " + str(last_id), "Computers found: " + str(num_found))

return paged_computers