檢視次數:
秘訣
秘訣
本文說明如何為舊版帳戶建立 API 金鑰。
如果您使用的是新的 Trend Micro Cloud One 帳戶，請參閱 管理 API 金鑰。
要使用 SDK 創建 API 金鑰，您首先需要獲取要與 API 金鑰關聯的角色 ID。您還需要使用現有的 API 金鑰來驗證呼叫。如果尚未創建 API 金鑰，您可以使用用戶名和密碼來創建第一個 API 金鑰。

獲取角色 ID 上層主題

獲取角色 ID 以指派角色給 API 金鑰。當您不知道角色的 ID 時，您可以搜尋該角色，然後獲取角色 ID。
例如，一個生成電腦防護狀態報告的程式需要對所有電腦的讀取權限。Server & Workload Security保護 預設提供的審核員角色提供對電腦和政策的唯讀權限，適合此任務。
如果您想要建立角色，請參閱使用角色控制存取。
請使用以下一般步驟來搜尋角色並取得 ID。關於搜尋的詳細資訊，請參閱 搜尋資源。

步驟

  1. 建立一個SearchCriteria物件來定義搜尋條件。
  2. 將 SearchCriteria 添加到 SearchFilter。
  3. 創建一個AdministratorRolesApi對象並使用它來執行搜索。
  4. 從返回的Role對象中獲取ID。

接下來需執行的動作

以下範例按名稱搜尋角色。
檢視來源
# Store the role ID - default is None
role_id = None

# Search criteria
name_criteria = api.SearchCriteria()
name_criteria.field_name = "name"
name_criteria.string_value = role_name
name_criteria.string_test = "equal"

# Search filter
role_filter = api.SearchFilter()
role_filter.search_criteria = [name_criteria]

# Perform the search and obtain the ID of the returned role
admin_roles_api = api.AdministratorRolesApi(api.ApiClient(configuration))
roles = admin_roles_api.search_administrator_roles(api_version, search_filter=role_filter)

if len(roles.roles) > 0:
    role_id = roles.roles[0].id

return roles.roles[0].id
另請參閱 API 參考中的 搜尋管理員角色 操作。

使用 SDK 建立 API 金鑰 上層主題

要使用 SDK，請建立一個 API 金鑰，創建一個 ApiKey 物件，並設置與 API 金鑰關聯的角色名稱和 ID。您還可以指定以下可選屬性：
  • 描述
  • 時區
  • 區域設置
  • 到期日
使用 APIKeysApi 物件在 Server & Workload Security保護 上建立 API 金鑰。返回的 ApiKey 物件包含密鑰。
要使用 API 來建立 API 金鑰，請使用 建立 API 金鑰 操作的 /api/apikeys 端點。
以下範例會建立一個用於稽核目的的 API 金鑰。該金鑰在建立後兩週內過期。
檢視來源
# Set key properties
time_to_expiry_in_ms = 14 * 24 * 60 * 60 * 1000
current_time_in_ms = int(round(time.time() * 1000))

key = api.ApiKey()
key.key_name = key_name
key.description = "Read-only access"
key.role_id = "2"
key.locale = "en-US"
key.time_zone = "Asia/Tokyo"
key.expiry_date = current_time_in_ms + time_to_expiry_in_ms # expires in 2 weeks

# Create the key on Server & Workload Security保護
api_keys_api = api.APIKeysApi(api.ApiClient(configuration))
return api_keys_api.create_api_key(key, api_version)
如需有關驗證 API 呼叫的資訊，請參閱 使用 Server & Workload Security保護 驗證。

使用用戶名和密碼創建 API 金鑰 上層主題

若尚未建立 API 金鑰，您可以使用 API 和使用者名稱及密碼來建立第一個 API 金鑰以自動化任務：

步驟

  1. 使用 /api/sessions 資源來獲取有效的會話 Cookie 和請求 ID。
  2. 使用會話 Cookie 和請求 ID 在 /api/apikeys 資源中創建 API 金鑰。

接下來需執行的動作

建立後，使用 API 金鑰來進行後續對 Server & Workload Security保護 的呼叫。

獲取會話 Cookie 和請求 ID 上層主題

使用 HTTP 客戶端（如 Postman、Paw 或 cURL）向 /api/sessions 資源發送 POST 請求。回應包括包含會話 ID 的 cookie，回應正文包含請求 ID。
注意
注意
/api/sessions 資源目前在 SDK 中不可用。
使用以下資訊來建立請求：
  • 請求類型：POST
  • URL: https://<Server & Workload Security保護 主機名稱>:<port>/api/sessions，例如 https://localhost:4119/api/sessions
  • 第一個標題：
    • 名稱：api-version
    • 值：v1
  • 第二標題：
    • 名稱：Content-type
    • 值：application/json
  • 正文（如有必要，請包括tenantName和mfaCode）：
    {
  "userName": "myUserName",
  "password": "myPassword"
}
這是一個範例的 cURL 命令。回應的 cookies 會儲存在 cookie.txt 檔案中。
curl -i -X POST \
  https://&nbsp;localhost:4119/api/sessions \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'api-version: v1' \
  -c cookie.txt \
  -d '{
"userName": "myUserName",
"password": "myPassword"
}'
Set-Cookie 回應標頭包含 sID cookie 中的會話 ID。回應主體包含作為 RID 值的回應 ID。回應類似於以下範例：
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1;mode=block
Cache-Control: no-cache,no-store
Pragma: no-cache
Set-Cookie: sID=D5EE2AC155601C895B33B701080D40A6; Path=/; Secure; HttpOnly
Content-Type: application/json
Content-Length: 141
Date: Wed, 24 Oct 2018 15:29:53 GMT

{
    "administratorID": 1,
    "created": 1540309893123,
    "lastActivity": 1540309893123,
    "accessType": "webService",
    "RID": "77DFF81036170DBF92CB71E4559512B9"
}

使用會話 Cookie 和請求 ID 創建 API 金鑰 上層主題

使用 HTTP 客戶端（如 Postman、Paw 或 cURL）向 /api/apikeys 資源發送 POST 請求。使用從 /api/sessions 資源獲取的會話 Cookie 和回應 ID 來驗證此呼叫。
注意
注意
目前 SDK 不支援使用會話 ID 和資源 ID 進行驗證。
使用以下資訊來建立請求：
  • 請求類型：POST
  • URL: https://<Server & Workload Security保護 主機名稱>:<port>/api/apikeys，例如 https://localhost:4119/api/sessions
  • 第一個標題：
    • 名稱：api-version
    • 值：v1
  • 第二標題：
    • 名稱：Content-type
    • 值：application/json
  • 第三個標題：
    • 名稱：rID
    • 值：您從sessions資源獲取的請求 ID，例如77DFF81036170DBF92CB71E4559512B9
  • Cookie：包括您從 /api/sessions 資源收到的 sID cookie。
  • 正文:
    {
  "keyName": "First Key",
  "description": "Created using a request ID",
  "roleID: 1
}
    如需有關取得角色 ID 的資訊，請參閱 取得角色 ID。
這是一個範例 cURL 命令。會話 cookie 通過 cookie.txt 文件包含在內。
curl -X POST \
  https://&nbsp;192.168.60.128:4119/api/apikeys \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 6f81da09-e5e2-421b-a38a-d5679f50608d' \
  -H 'api-version: v1' \
  -H 'rID: 77DFF81036170DBF92CB71E4559512B9' \
  -b cookie.txt \
  -d '{
  "keyName": "First Key",
  "description": "Created using a request ID",
  "roleID": 1
}'
回應主體包括作為secretKey值的密鑰，類似於以下範例：
{
    "keyName": "First Key",
    "description": "Created using a request ID",
    "locale": "en-US",
    "roleID": 1,
    "timeZone": "America/New_York",
    "active": true,
    "created": 1540310105209,
    "unsuccessfulSignInAttempts": 0,
    "secretKey": "8:4rFctPvno+dxntueMcso4F61SUZMFVt3I6SczG7ysOA=",
    "serviceAccount": false,
    "ID": 8
}
保存 secretKey，以便您稍後在 API 調用的 api-secret-key 標頭中使用它。