API 回應 | Trend Micro Service Central

API 回應

本節說明 Apex Central 如何回應 API 要求。

將授權要求傳送到預定 API 之後，Apex Central 會傳回 JSON 格式的回應物件。回應格式視所存取的資源而定。

產生 API 回應

Apex Central 會傳回 JSON 格式的回應，並採用標準 HTTP 回應碼。

Apex Central 會以下列格式傳回 JSON 格式的回應物件：

{
    'Data': (if provided, a JSON object representing the return value of the API), 
    'Meta': {
        'Result': (an integer indicating the result of this API call), 
        'ErrorCode': (an integer indicating the nature of an encountered error), 
        'ErrorMsg': (a string describing the error code) 
    }, 
    'PermissionCtrl': (an object indicating the permissions assigned to the logged-on user account for accessing Apex Central features),
    'FeatureCtrl': (an object indicating the Apex Central deployment model),
    'SystemCtrl': (an object indicating the suspicious object distribution role of the Apex Central server)
}

下表提供回應主體中部分欄位的詳細資訊。

表 1. 回應主體欄位
欄位	詳細資訊
PermissionCtrl	permission：整數，指出指派給已登入使用者帳號的權限 255：完全控制 1：唯讀 elements：對於大多數 Apex Central API，此值一律為 "null" 或 "None"。
FeatureCtrl	mode：整數，指出部署模式 0：Apex Central as a Service 1：Apex Central 內部部署伺服器
SystemCtrl	TmcmSoDist_Role：字串，指出可疑物件散佈角色 "edge"：將可疑物件清單傳送至中樞伺服器的節點伺服器 "hub"：從節點伺服器接收可疑物件清單的中樞伺服器 "none"：未設定任何預設設定

下表列出可能的回應。

表 2. 產生 API 回應
HTTP 狀態碼	回應狀態	回應主體
200	成功	{ 'Data': (if provided, a JSON object representing the return value of the API), 'Meta': { 'Result': (an integer indicating the result code of this API call), 'ErrorCode': (an integer indicating the nature of an encountered error), 'ErrorMsg': (a string describing the error code) }, 'PermissionCtrl': {'permission': '255', 'elements': None}, 'FeatureCtrl': {'mode': '0'}, 'SystemCtrl': {'TmcmSoDist_Role': 'none'} }
400	未成功，因為參數無效	{ 'Data': (if provided, a JSON object representing the return value of the API), 'Meta': { 'Result': (an integer indicating the result code of this API call), 'ErrorCode': (an integer indicating the nature of an encountered error), 'ErrorMsg': (a string describing the error code) }, 'PermissionCtrl': {'permission': '255', 'elements': None}, 'FeatureCtrl': {'mode': '0'}, 'SystemCtrl': {'TmcmSoDist_Role': 'none'} }
401	未成功，因為授權錯誤	{ 'Data': (if provided, a JSON object representing the return value of the API), 'Meta': { 'Result': (an integer indicating the result code of this API call), 'ErrorCode': (an integer indicating the nature of an encountered error), 'ErrorMsg': (a string describing the error code) }, 'PermissionCtrl': {'permission': '255', 'elements': None}, 'FeatureCtrl': {'mode': '0'}, 'SystemCtrl': {'TmcmSoDist_Role': 'none'} }
500	未知的錯誤	{ 'Data': (if provided, a JSON object representing the return value of the API), 'Meta': { 'Result': (an integer indicating the result code of this API call), 'ErrorCode': (an integer indicating the nature of an encountered error), 'ErrorMsg': (a string describing the error code) }, 'PermissionCtrl': {'permission': '255', 'elements': None}, 'FeatureCtrl': {'mode': '0'}, 'SystemCtrl': {'TmcmSoDist_Role': 'none'} }

伺服器和 Security Agent API 回應

本節說明適用於伺服器和 Security Agent API 的 JSON 格式的回應及標準 HTTP 回應碼。

Apex Central 會以下列格式傳回 JSON 格式的回應物件：

{
 "result_code":(an integer indicating the result of this API call),
 "result_description":"(a string describing the result code)",
 "result_content":"(if provided, a JSON object representing the return value of the API)"
}

重要:

回應主體中的 result_description 欄位會依實際現況變更。如果您的應用程式依賴於 Apex Central API 回應，請使用 result_code 值。

如需 result_code 狀態值的完整清單，請參閱API 結果碼。

下表列出可能的回應。

表 3. 伺服器和 Security Agent API 回應
HTTP 狀態碼	回應狀態	回應主體
200	成功	{ "result_code":(an integer indicating the result of this API call), "result_description":"(a string describing the result code)", "result_content":"(if provided, a JSON object representing the return value of the API)" }
400	未成功，因為參數無效	{ "result_code":(an integer indicating the result of this API call), "result_description":"(a string describing the result code)", "result_content":"" }
401	未成功，因為授權錯誤	{ "result_code":(an integer indicating the result of this API call), "result_description":"(a string describing the result code)", "result_content":"" }
500	未知的錯誤	{ "result_code":(an integer indicating the result of this API call), "result_description":"(a string describing the result code)", "result_content":"" }

API 結果碼

Apex Central 使用標準 HTTP 回應碼。

下表列出 Apex Central 自動化 API 結果碼和對應的說明：

結果碼	說明
1	作業成功
-2	驗證未成功：未提供驗證 Token。
-3	驗證未成功：驗證 Token 格式錯誤
-4	驗證未成功：驗證 Token 版本不受支援
-5	驗證未成功：應用程式 ID 無效
-6	驗證未成功：驗證 Token 已到期
-7	驗證未成功：驗證 Token 簽章無效
-8	驗證未成功：要求總和檢查碼無效
-9	驗證未成功：驗證 Token 簽章演算法不受支援
-21	輸入的參數無效
-22	處理行動無效
-50	HTTP 方法不受支援
-99	內部伺服器錯誤
-102	用戶端處理行動未成功：不支援多個相符項目
-103	用戶端處理行動未成功：無法隔離向另一部 Apex Central 伺服器報告的用戶端
-104	用戶端處理行動未成功：無法連線到遠端伺服器
-105	用戶端處理行動未成功：找不到目標伺服器
-106	用戶端處理行動未成功：目標伺服器由子 Apex Central 伺服器管理
-107	用戶端處理行動未成功：目標伺服器不支援指令
-1101	可疑物件處理行動未成功：超過數量上限
-1102	可疑物件處理行動未成功：無法產生已上傳檔案的掃瞄預先過濾，檔案有可能因防毒而遭到封鎖

上層主題

Apex Central 自動化 API