リソースを検索する

検索は、タスクを自動化する場合に便利な強力なツールです。APIの各エンドポイントは、リソースを検索するための操作を提供します。たとえば、 /api/computers エンドポイントの Search Computers 操作を使用して、コンピュータを検索できます。

検索操作を使用するには、1つ以上の検索条件を含む検索フィルタオブジェクトを指定します。検索条件オブジェクトには、次の種類の検索を設定するためのプロパティが含まれます。

  • ブール: ブール値を検索します。
  • 選択肢: 有効な値が定義された検索フィールド
  • ID: 一意のIDを検索する
  • Null: ヌル値を検索する
  • 数値: 数値による検索
  • 文字列: 文字列値を検索する
  • 日付範囲: 日付値で検索

複数の条件を使用する検索では、すべての条件を満たす結果が返されます。

リソースプロパティ値に関する注意事項で説明したように、APIを直接使用する場合は、0を使用してnull値を表します。ただし、NULL値を検索するには、Null検索を使用します。0の数値検索は実行しません。

検索条件には次の項目が含まれます。

  • 検索しているフィールドの名前(リソースのプロパティ)。  -- フィールド名は大文字と小文字が区別されます。
  • 検索する値(または、日付の値の場合は日付の範囲)
  • フィールド値に対してテストする演算子(日付/時刻検索には適用されません)
  • 返される項目の最大数(初期設定は5000)

ID検索を実行する際には、IDフィールドと見なされるフィールドの名前は含めないでください。

検索する値のタイプによって、利用可能な演算子が決まります。

Type 演算子
ブール true(初期設定)
false
選択肢(有効な値のセットが定義されているフィールドの場合) 等しい(初期設定)
等しくない
日付 日付関連検索では日付範囲が使用されており、オペレータは明示的に使用していません。
ID(一意のIDの場合) 等しい(初期設定)
より大きい
より大きい - または - 等しい
より小さい
より小さいまたは等しい
等しくない
Null true(初期設定:trueはnullを示します)
false
数値 等しい(初期設定)
より大きい
より大きい - または - 等しい
より小さい
より小さいまたは等しい
等しくない
文字列 等しい
等しくない

次の例では、ポリシー名に対して簡単な検索を実行します。

ソースを表示

# 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])

API呼び出しの認証の詳細については、 Workload Securityを参照してください。

検索可能なフィールド

APIレファレンス/参照情報 は、検索可能なリソースのフィールドを示します。操作の応答オブジェクト内のフィールドの情報を確認できます。

  1. 検索するリソースの種類を返す操作をクリックします。たとえば、 Describe a Computer 操作は、コンピュータリソースを返します。
  2. [回答]セクションの[ 200正常な操作 ]をクリックします。
  3. フィールドの説明を参照してください。検索可能なフィールドの説明には、「検索可能 データ型」が含まれます。ここで、 データ型 には、String、Numeric、ID、Date、Boolean、およびChoiceを指定できます。

フィールド名は大文字と小文字が区別されます。

次のフィールドは検索できません。

  • 任意のオブジェクトの locale フィールド
  • Policy オブジェクトの policySettings フィールドなど、オブジェクトを値として持つフィールドの大部分(「除外対象のコンピュータのサブオブジェクトの検索」を参照)。

検索できないフィールドを検索すると、 Invalid SearchFilter: unknown fieldName: platformに似たエラーが表示されます。

検索コンピュータのサブオブジェクト

値としてオブジェクトを持つフィールドは通常検索できませんが、コンピュータクラスにはいくつかの除外があります。たとえば、 ec2VirtualMachineSummary フィールドの値はオブジェクトで、 accountIDavailabilityZoneなど、そのオブジェクトのフィールドのいくつかを検索できます。同様に、コンピュータ interfacesname フィールドを検索できます。(検索可能なサブオブジェクトの詳細については、 Describe a Computer 操作のレスポンススキーマ( APIリファレンス) を参照してください。)次のJSONは、コンピュータオブジェクトのデータ構造内のこれらのサブオブジェクトを示しています。

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

検索条件では、サブオブジェクトのフィールド名はパスとして表されます(例: ec2VirtualMachineSummary/publicIPAddress および interfaces/name)。

戻り値のコンピュータオブジェクトに必要な情報のみを含めるように検索する場合は、 expand パラメータを使用します。詳細については、 パフォーマンスヒント ガイドの「コンピュータの応答サイズを最小化する」を参照してください。

コンピュータ下位オブジェクトで検索すると、 expandnone に設定されている場合を除いて、サブオブジェクトが自動的に返された Computer オブジェクトに含まれます(サブオブジェクトは返されません)。たとえば、EC2アカウントIDで検索し、 expandtasksに設定されている場合、返された Computer オブジェクトには tasks プロパティと ec2VirtualMachineSummary プロパティが含まれます。  expandec2VirtualMachineSummaryに設定されている場合、返される Computer オブジェクトには ec2VirtualMachineSummary プロパティが含まれます。

ソースを表示

# 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)

Pythonコード内のフィールド名

Pythonクライアントライブラリを使用する場合は、検索で正しいフィールド名を使用するようにしてください。いくつかのフィールド名は、複数の連結された単語で構成され、 侵入防御 ルールの lastUpdated プロパティなど、ラクダ文字の文字を使用します。対応するPythonプロパティでは、アンダースコア( (_) )の文字を使用して、ラクダ文字(例:  last_updated)の代わりに連結された単語を区切ります。フィールドを検索する場合は、検索するフィールド名(lastUpdated)を指定し、クラスプロパティ(last_updated)には指定しないでください。

不適切なフィールド名を使用すると、メッセージ Invalid SearchFilter: unknown fieldNameでエラーが発生します。

次のアルゴリズムを使用して、Pythonクラスのプロパティをフィールド名に変換します。プロパティ名に1つ以上のアンダースコア( (_):)が含まれている場合

  1. 各アンダースコアの直後にある文字を大文字にします。
  2. アンダースコア(_)を1つずつ削除します。

文字列検索でのワイルドカードの使用

文字列検索では、文字列値に次の2つのワイルドカードを使用できます。

  • %:ゼロ個以上の文字に一致します。
  • _; 1文字に一致

たとえば、文字列値 %SecurityWorkload Securityに一致し、 Securityにも一致します。文字列値 version_version1に一致し、 versionに一致しません。リテラル % または _ 文字を検索する場合は、ワイルドカードを無効にできます。ただし、ワイルドカードの使用は初期設定で有効になっています。次の検索フィルタを使用して、「Base Policy」という名前のポリシーを検索できます。

# Create the search criteria
search_criteria = api.SearchCriteria()
search_criteria.field_name = "name"
search_criteria.string_test = "equal"
search_criteria.string_value = "Base%"
ワイルドカード検索を無効にするには、 `SearchCriteria` オブジェクトの `stringWildcards` プロパティを `false`に設定します。
search_criteria.string_wildcards = "false"

日付範囲の検索を実行する

指定された2つの日付に該当する日付値を含むフィールドを検索できます。次の検索条件フィールドは、日付範囲を定義します。

  • FirstDate: 範囲の前の日付。初期設定値は可能な限り早い日付です。
  • FirstDateInclusive: 範囲にFirstDateが含まれるか(true)、含まれないか(false)を示すブール値。初期設定値はfalseです。
  • LastDate: 範囲内の後の日付。初期設定値は最新の日付です。
  • LastDateInclusive:  範囲にLasteDateが含まれるか(true)、含まれないか(false)を示すブール値。初期設定値はfalseです。

FirstDate および LastDate の値は、1970年1月1日(GMT)からのミリ秒数で表されます。

次の例では、 侵入防御 ルールが、最後にアップデートされた日時に基づいて検索します。

ソースを表示

# 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)

「APIレファレンス/参照情報」の「 検索 侵入防御 ルール 操作」も参照してください。API呼び出しの認証の詳細については、 Workload Securityを参照してください。

ヌル値を検索する

ヌルテスト検索を使用して、フィールドに値がないかどうかに基づいてリソースを検索します(ヌル), または任意の値)。  たとえば、コンピュータの lastSendPolicySuccess フィールドには、コンピュータのポリシーが正常にアップデートされた最後の時刻が表示されます。ポリシーアップデートを受信していないコンピュータを検索するには、そのフィールドに対してヌルテスト検索を実行します。

このタイプの検索の場合、検索条件には検索するフィールドの名前、値のないリソース(null_test = true)、または任意の値(null_test = false)を検索するかどうかが含まれます。

次の例では、ポリシーアップデートを受信していないコンピュータを検索します。

ソースを表示

# 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)

詳細については、APIリファレンスの 検索コンピュータ 操作をレファレンス/参照情報。

並べ替え順序

検索条件の特性によって、検索結果の並べ替え順序が決まります。

  • ブール値、選択値、Null、および文字列の検索: 戻されたオブジェクトのIDによってソートされます(昇順)。
  • ID検索: IDでソートオペレータは、注文が昇順か降順かを判断します。

    • より小さいおよびより小さいより小さいか等しい:降順
    • その他すべての演算子:昇順
  • 数値検索: 検索するフィールドでソートします。オペレータは、注文が昇順か降順かを判断します。

    • より小さいおよびより小さいより小さいか等しい:降順
    • その他すべての演算子:昇順

    複数の検索結果が検索されたフィールドで同じ値を持つ場合、それらのオブジェクトは2次的にIDでソートされます。

  • 日付検索: 検索するフィールドでソートします。検索に指定された日付範囲のパラメータによって、並べ替え順序が決まります。

    • 提供されるのはLastDateのみです:降順
    • 他の組み合わせ:昇順

    複数の検索結果が検索された日付フィールドの値が同じ場合、これらのオブジェクトは2次的にIDでソートされます。

  • 複数の検索条件: 複数の検索条件を使用する検索は、IDごとにソートされます(昇順), 個々の条件の初期設定のソート順に関係なく)。

SearchFilterオブジェクトを使用すると、初期設定の並べ替え順序を、返されるオブジェクトのIDでオーバーライドできます。

検索結果とページングを制限する

検索フィルタの maxItems フィールドを使用して、返されるオブジェクトの数を制限します。返されるオブジェクトの最大数は、初期設定では5000で、5000を超えることはできません。

maxItems フィールドを使用して、ID検索の結果のページングを実装することもできます。

  • 大なり演算子を使用したIDによる検索
  • maxItemsを使用してページサイズを設定する
  • 結果の前のページで最も高いIDに基づいて検索するIDの値を計算します。

次の例は、検索を使用して一連のページ内のすべてのコンピュータを取得する方法を示しています。

ソースを表示

# 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

また、APIレファレンス/参照情報の 検索コンピュータ 操作も参照してください。API呼び出しの認証の詳細については、 Workload Securityを参照してください。