APIに慣れるために、簡単なリクエストをWorkload Securityに送信できます。

開発環境を設定する

ソフトウェアを開発する環境には、次のものが必要です。
  • Workload Security。
  • SDKクライアントライブラリを使用する場合は、Python SDKページにアクセスしてクライアントライブラリをダウンロードし、開発環境に追加する方法を学んでください。
  • クライアントライブラリのプログラミング言語のランタイム環境です。
クライアントライブラリを使用せずにすぐにAPIの探索を開始するには、PostmanPaw、またはcurlなどのHTTPクライアントを使用できます。

Workload Securityで認証する

Workload Security はHTTP要求の認証にAPIキーを使用します。
HTTPリクエストを認証する方法は、新しいTrend Cloud Oneアカウントを使用しているか、従来のアカウントを使用しているかによって異なります。詳細については、Trend Cloud Oneアカウントの変更を参照してください。

APIキーを作成する

Workload Securityでのリクエストの認証に使用するAPIキーを作成するには、以下を参照してください。
APIキーを作成すると、APIキーに関連付けられた一意の秘密鍵が提供されます。この秘密鍵は、認証用のHTTP要求に含めます。秘密鍵は提供された時点で保管する必要があります。

要求の認証

作成する各HTTPリクエストには、ヘッダ内の承認が必要です。認証方法は、従来のAPIキーとTrend Cloud One APIキーのどちらを使用しているかによって異なります。

Trend Cloud One APIキーを使用した認証

Trend Cloud One APIキーを使用している場合、次のリクエスト例に示すように、リクエストごとにシークレットキーを含む認証ヘッダが必要です。
GET /api/policies HTTP/1.1
Host: https://workload.<region>.cloudone.trendmicro.com/
Authorization: ApiKey 1tBOlis4aGpMyygC26YKZMgU2fW:7864DcPqkWFHNngXHnn9VgWSuGtUoj52n3tTZSqkvucLDJ9jJJvbrBZMBJBigsS5wT
api-version: v1

従来のAPIキーを使用して認証する

レガシーAPIキーを使用している場合、各リクエストには、次の例のリクエストに示されているように、シークレットキーを含むapi-secret-keyヘッダーを含める必要があります。
GET /api/policies HTTP/1.1
Host: https://workload.<region>.cloudone.trendmicro.com/
api-secret-key: 2:vJC6lckDygB6FYURIvR0WK2ZTAhIY8rb0Amy9UMn4mo=
api-version: v1
クライアントライブラリを使用する場合、ApiClientのインスタンスを取得し、シークレットキーを使用するように設定します。この設定はグローバルであり、その後のすべてのAPI呼び出しはシークレットキーを使用して認証されます。以下のGETおよびPOSTの例は、ApiClientを作成および設定する方法を示しています。
マネージャは、シークレットを使用して要求を認証します。各APIキーは、実行可能な処理を決定する役割に関連付けられています。

GETリクエストを実行: ポリシーの一覧

APIの探索を開始するには、APIレファレンスのポリシーセクションにあるList Policies操作に移動します。List PoliciespoliciesエンドポイントへのGETリクエストであることに注意してください。
apiref_getpolicies=daad924c-2a14-4286-9851-926f2ce5b2aa.png

HTTPクライアントを使用する

リクエストをすぐに送信するには、Postman、Paw、またはcurlを使用します。次の情報を使用して要求を作成します。
  • URL: https://<manager_host_name>:<port>/api/policies、例えばhttps://workload.<region>.cloudone.trendmicro.com/api/policies
  • 最初のヘッダ:
    • キー: api-secret-key(レガシーアカウント用) またはAuthorization(新規アカウント用)
    • 値: <your_key_secret>(レガシーアカウントの場合) またはApiKey <your_key_value>(新しいアカウントの場合)
  • 2番目のヘッダ:
    • キー: api-version
    • 値: v1
従来のアカウントのcurlコマンドの例:
curl -X GET workload.<region>.cloudone.trendmicro.com/api/policies -H 'api-secret-key: 5:W+lC8YHIaYHeQuDbJZLkqwM5b8xjxla2pHtBNoiifF8=' -H 'api-version: v1'

クライアントライブラリを使用する

次の例では、Workload Securityで認証を構成するApiClientオブジェクトを作成します。次にPoliciesApiオブジェクトを作成し、すべてのポリシーを一覧表示するために使用します。
first_steps_get_example.pyという名前のファイルを作成し、次のサンプルコードをファイルにコピーしてください。
import deepsecurity as api
from deepsecurity.rest import ApiException as api_exception

def get_policies_list(api, configuration, api_version, api_exception):
    """ Gets a list of policies on Workload Security

    :return: A PoliciesApi object that contains a list of policies.
    """
    # Create a PoliciesApi object
    policies_api = api.PoliciesApi(api.ApiClient(configuration))

    # List policies using version v1 of the API
    policies_list = policies_api.list_policies(api_version)
    # View the list of policies
    return policies_list

if __name__ == '__main__':
    # Add Workload Security host information to the api client configuration
    configuration = api.Configuration()
    configuration.host = 'https://workload.<region>.cloudone.trendmicro.com/'

    # Authentication
    configuration.api_key['api-secret-key'] = '2:l069trAePqPRxZUfBqyw442z1DWm9s4u0F/g9bewnFE='

    # Version
    api_version = 'v1'

    print(get_policies_list(api, configuration, api_version, api_exception))
次のコードを探し、環境に応じてURLと秘密鍵を変更します。
configuration.host = 'https://workload.<region>.cloudone.trendmicro.com/'
configuration.api_key['api-secret-key'] = '2:l069trAePqPRxZUfBqyw442z1DWm9s4u0F/g9bewnFE='
コマンドプロンプト(Windows)またはターミナル(Linux)を開き、次のコマンドを入力します。
python first_steps_get_example.py

POSTリクエストを実行: ファイアウォールルールを検索

ファイアウォールルールを検索するためにPOSTリクエストを実行します。APIレファレンスのファイアウォールルールの検索操作 (ファイアウォールルールセクション) では、firewallrulesエンドポイントに対するPOSTリクエストはfirewallrules/searchパスに送信されます。
apiref_fwrules=196bbe40-f1c9-4f17-bbb5-799a5a936a14.png
APIレファレンスには、リクエスト本文で使用する一連のパラメータも表示されます。Search Firewall Rulesの場合、各パラメータは検索条件です。この例では、IDが3の検索が実行されます。

投稿にHTTPクライアントを使用する

PostmanまたはPawで要求を作成するには、次の情報を使用します。
  • リクエストタイプ: POST
  • URL: https://<workload_security_hostname><port>/api/firewallrules/search、例えばhttps://workload.<region>.cloudone.trendmicro.com/api/firewallrules/search
  • 最初のヘッダ:
    • キー: api-secret-key(レガシーアカウント用) またはAuthorization(新規アカウント用)
    • 値:鍵の秘密
  • 2番目のヘッダ:
    • キー: api-version
    • 値: v1
  • 3番目のヘッダ:
    • キー: Content-Type
    • 値: application/json
また、次の生コードを本文に追加します。
{
  "searchCriteria": [{
    "idTest":"equal",
    "idValue":3
  }]
}
例curlコマンド:
curl -X POST workload.<region>.cloudone.trendmicro.com/api/firewallrules/search \
-H 'Cache-Control: no-cache' \
-H 'api-secret-key: 3:zNi5ag8xPGpfEMElV0GxAIpTs5Ji8BQoCtXaTAgKkVM=' \
-H 'api-version: v1' \
-H 'content-type: application/json' \
-d '{
  "searchCriteria": [{
    "idTest":"equal",
    "idValue":3
  }]
}'

クライアントライブラリを使用して投稿する

次の例では、検索条件を定義するSearchFilterオブジェクトを作成します。次に、SearchFilterオブジェクトをModuleFirewallApiオブジェクトのsearchFirewallRulesメソッドのパラメーターとして使用します。
first_steps_post_example.pyという名前のファイルを作成し、次のサンプルコードをそのファイルにコピーしてください。
import deepsecurity as api
from deepsecurity.rest import ApiException as api_exception

def search_firewall_rules(api, configuration, api_version, api_exception):
    """ Searches the firewall rules for any rule that contains DHCP in the rule name.

    :param api: The Workload Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Workload Security API exception module.
    :return: A list containing all firewall rules that match the search criteria.

    """

    # Define the search criteria
    search_criteria = api.SearchCriteria()
    search_criteria.field_name = "name"
    search_criteria.string_value = "%DHCP%"
    search_criteria.string_test = "equal"
    search_criteria.string_wildcards = True

    # Create search filter to find the rule
    search_filter = api.SearchFilter(None,[search_criteria])

    # Create a FirewallRulesApi object
    firewall_rules_api = api.FirewallRulesApi(api.ApiClient(configuration))

    # Perform the search
    firewall_rules = firewall_rules_api.search_firewall_rules(api_version, search_filter=search_filter)
    firewall_rules_list = []
    for rule in firewall_rules.firewall_rules:
        firewall_rules_list.append(rule)

    return firewall_rules

if __name__ == '__main__':
    # Add Workload Security host information to the api client configuration
    configuration = api.Configuration()
    configuration.host = 'https://workload.<region>.cloudone.trendmicro.com/api'

    # Authentication
    configuration.api_key['api-secret-key'] = '2:l069trAePqPRxZUfBqyw442z1DWm9s4u0F/g9bewnFE='

    # Version
    api_version = 'v1'
    print(search_firewall_rules(api, configuration, api_version, api_exception))
次のコードを探し、環境に応じてURLと秘密鍵を変更します。
configuration.host = 'https://workload.<region>.cloudone.trendmicro.com/'</code></li>
configuration.api_key['api-secret-key'] = '2:l069trAePqPRxZUfBqyw442z1DWm9s4u0F/g9bewnFE='
コマンドプロンプト(Windows)またはターミナル(Linux)を開き、次のコマンドを入力します。
python first_steps_post_example.py

Workload Securityの取得バージョン

正しく認証された要求に対する各応答には、 Workload Security インスタンスのバージョンが含まれます。X-DSM-Versionヘッダには、次の例のようなバージョンが含まれています。
X-DSM-Version = Deep Security/12.0.81

次の手順