このページのトピック
APIを使用して最初のリクエストを送信する
APIに慣れるには、いくつかの簡単な要求をWorkload Securityに送信してください。
開発環境を設定する
ソフトウェアを開発する環境には、次の項目が必要です。
- Workload Security。
- SDKクライアントライブラリ(使用する場合)Python SDKの ページにアクセスして、クライアントライブラリをダウンロードし、開発環境に追加する方法を学習してください。
- クライアントライブラリのプログラミング言語のランタイム環境です。
APIをすぐに調べるには、クライアントライブラリを使用する代わりに、 Postman, Paw、または curlなどのHTTPクライアントを使用できます。
Workload Security
Workload Security はHTTP要求の認証にAPIキーを使用します。
HTTPリクエストの認証方法は、新しい Trend Micro Cloud One アカウントを使用しているか、従来のアカウントを使用しているかによって異なります。2種類のアカウントの詳細については、Trend Micro Cloud One アカウントの変更を参照してください。
APIキーを作成する
Workload Securityでのリクエストの認証に使用するAPIキーを作成します。
- 従来のアカウントのAPIキーの作成方法については、APIキーの作成と管理を参照してください。
- 新しい Trend Micro Cloud One アカウントのAPIキーを作成する方法については、APIキーの管理を参照してください。
APIキーが作成されると、APIキーに関連付けられた一意の秘密キーが提供されます。この秘密鍵は、認証用のHTTP要求に含める必要があります。秘密鍵は、秘密鍵が提供された時点で保存する必要があります。秘密鍵を取得できるのは他にはないからです。
要求の認証
HTTP要求ごとに、ヘッダの認証が必要です。認証を実行する方法は、従来のAPIキーと Trend Micro Cloud One APIキーのどちらを使用しているかによって異なります。
Trend Micro Cloud One APIキーを使用して認証する
Trend Micro Cloud One APIキーを使用している場合は、リクエストごとに秘密鍵を含む認証ヘッダが必要です。次に例を示します。
GET /api/policies HTTP/1.1
Host: localhost:4119
Authorization: ApiKey 1tBOlis4aGpMyygC26YKZMgU2fW:7864DcPqkWFHNngXHnn9VgWSuGtUoj52n3tTZSqkvucLDJ9jJJvbrBZMBJBigsS5wT
api-version: v1
従来のAPIキーを使用して認証する
従来のAPIキーを使用している場合は、次のリクエストの例に示すように、各リクエストに秘密鍵を含む api-secret-key
ヘッダが含まれている必要があります。
GET /api/policies HTTP/1.1
Host: localhost:4119
api-secret-key: 2:vJC6lckDygB6FYURIvR0WK2ZTAhIY8rb0Amy9UMn4mo=
api-version: v1
クライアントライブラリを使用する場合は、 ApiClient
のインスタンスを取得し、秘密鍵を使用するようにを設定します。設定はグローバルに行われるため、以後APIへのすべての呼び出しは秘密鍵を使用して認証されます。次のGETおよびPOSTの例では、 ApiClient
を作成および設定する方法を示します。
マネージャは、シークレットを使用して要求を認証します。各APIキーは、実行可能な処理を決定する役割に関連付けられています。
GET要求を実行する: ポリシーの
APIの探索を開始するには、APIリファレンスの[ポリシー]セクションにあるリストポリシー操作に進んでください。List Policies
が policies
エンドポイントでのGET要求であることに注意してください。
HTTPクライアントを使用する
リクエストをすぐに送信するには、Postman、Paw、またはcurlを使用します。次の情報を使用して要求を作成します。
- URL:
https://<Manager host name>:<port>/api/policies
、たとえばhttps://localhost:4119/api/policies
- 最初のヘッダ:
- キー:
api-secret-key
(従来のアカウントの場合)またはAuthorization
(新しいアカウントの場合) - 値:
<your key secret>
(従来のアカウントの場合)またはApiKey <your key value>
(新しいアカウントの場合)
- キー:
- 2番目のヘッダ:
- キー:
api-version
- 値:
v1
- キー:
従来のアカウントのcurlコマンドの例:
curl -X GET https:// localhost:4119/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:// 192.168.17.149:4119/api'
# 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://192.168.17.149:4119/api'
configuration.api_key['api-secret-key'] = '2:l069trAePqPRxZUfBqyw442z1DWm9s4u0F/g9bewnFE='
コマンドプロンプト(Windows)またはターミナル(Linux)を開き、次のコマンドを入力します。
python first_steps_get_example.py
POST要求を実行する: ファイアウォールルールを検索する
ファイアウォールルールを検索するPOST要求を実行します。APIリファレンスで、 firewallrules
エンドポイントの 検索 ファイアウォール ルール 操作(ファイアウォール ルールセクション)は、パス firewallrules/search
に対するPOST要求です。
APIリファレンスには、要求本文で使用する一連のパラメータも表示されます。 Search Firewall Rules
の場合、各パラメータは検索基準です。この例では、3というIDを検索します。
投稿にHTTPクライアントを使用する
PostmanまたはPawで要求を作成するには、次の情報を使用します。
- 要求の種類:
POST
- URL:
https://<Workload Security hostname><ポート>/api/firewallrules/search
、たとえばhttps://localhost:4119/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 https:// localhost:4119/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://192.168.17.149:4119/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://192.168.17.149:4119/api'</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