檢視次數:
要熟悉 API，請向 伺服器與工作負載保護 發送一些簡單的請求。

設置您的開發環境

您開發軟體的環境需要以下項目：
  • 網路存取伺服器與工作負載保護。
  • 如果您選擇使用 SDK 客戶端庫，請前往 Python SDK 頁面 下載客戶端庫並了解如何將其添加到您的開發環境中。
  • 您客戶端程式庫的程式語言執行環境。
秘訣
秘訣
要立即開始探索 API，您可以使用 HTTP 客戶端，例如 Postman、Paw 或 curl，而不是使用客戶端庫。

使用 伺服器與工作負載保護 驗證

伺服器與工作負載保護 使用 API 金鑰來驗證 HTTP 請求。
您驗證 HTTP 請求的方式取決於您使用的是新的 TrendAI™ 雲端 One 帳戶還是舊的傳統帳戶。有關這兩種類型帳戶的資訊，請參閱 TrendAI™ 雲端 One 帳戶的變更。

建立 API 金鑰

建立 API 金鑰以用於驗證您對 伺服器與工作負載保護 的請求：
在建立 API 金鑰時，您會獲得一個與該 API 金鑰相關聯的唯一密鑰。您需要在 HTTP 請求中包含此密鑰以進行身份驗證。您必須在提供密鑰時將其儲存，因為之後您將無法再次獲取該密鑰。

驗證請求

您所發出的每個 HTTP 請求都需要在標頭中進行授權。您如何執行該授權取決於您使用的是舊版 API 金鑰還是 TrendAI™ 雲端 One API 金鑰。

使用 TrendAI™ 雲端 One API 金鑰進行身份驗證

如果您使用 TrendAI™ 雲端 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 請求：
apiref_getpolicies=5b5e8bec-8e74-4ff9-bbb1-900f481afec9.png

使用 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>（適用於新帳戶）
  • 第二標題：
    • Key: api-version
    • 值：v1
舊版帳戶的範例 curl 命令：
curl -X GET https://&nbsp;localhost:4119/api/policies -H 'api-secret-key: 5:W+lC8YHIaYHeQuDbJZLkqwM5b8xjxla2pHtBNoiifF8=' -H 'api-version: v1'

使用用戶端程式庫

以下範例創建了一個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 伺服器與工作負載保護

    :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 伺服器與工作負載保護 host information to the api client configuration
    configuration = api.Configuration()
    configuration.host = 'https://&nbsp;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 請求。
apiref_fwrules=827c9ed7-74fc-4c90-989f-95de5c5926b4.png
API 參考還顯示了您在請求正文中使用的一系列參數。對於 搜尋防火牆規則，每個參數都是一個搜尋標準。在此範例中，我們搜尋 ID 為 3 的項目。

使用 HTTP 客戶端進行發佈

使用以下資訊在 Postman 或 Paw 中建立請求：
  • 請求類型：POST
  • URL: https://<伺服器與工作負載保護 hostname><port>/api/firewallrules/search，例如 https://localhost:4119/api/firewallrules/search
  • 第一個標題：
    • 金鑰：api-secret-key（適用於舊帳戶）或 Authorization（適用於新帳戶）
    • 值：您的密鑰秘密
  • 第二標題：
    • Key: api-version
    • 值：v1
  • 第三個標題：
    • Key: Content-Type
    • 值：application/json
另外，將以下原始代碼添加到正文中：
{
  "searchCriteria": [{
    "idTest":"equal",
    "idValue":3
  }]
}
範例 curl 命令：
curl -X POST https://&nbsp;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 伺服器與工作負載保護 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 伺服器與工作負載保護 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 伺服器與工作負載保護 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

獲取伺服器與工作負載保護版本

每個對正確驗證請求的回應都包含 伺服器與工作負載保護 實例的版本。X-DSM-Version 標頭包含版本，類似於以下範例：
X-DSM-Version = Deep Security/12.0.81

後續步驟