使用傳統 REST API

何時使用傳統 REST API

注意 端點不斷被添加到Server & Workload Security保護 API。請定期檢查此表以了解變更。

將您的環境設置為使用 REST API

1. 下載 Deep Security Web Services SDK
2. 建立 REST API 用戶端可以使用的使用者帳號

下載 Web Services SDK

建立 Web 服務角色和使用者

1. 在 Server & Workload Security保護 主控台中，依次選擇 Administration → User Management → Roles。
2. 點選 New。
3. 取消選取Allow Access to Workload Security Manager User Interface並選取Allow Access to Web Service API。
4. 當所有其他設定完成後，點選儲存。
5. 邀請用戶加入帳戶，詳情請參閱此處。
6. 提供使用者所需的屬性。對於角色屬性，選擇您剛剛創建的角色。
7. 請記下新的使用者帳號用戶名和密碼。

開發一個 REST API 客戶端應用程式

基本 API 存取

管理您的會話

• 當 API 會話不再需要時終止它們。Server & Workload Security保護 限制同一時間內可以啟動的會話數量。您的應用程式應該終止其會話以避免達到最大同時會話數量。調用 /rest/authentication/logout URL 來結束會話。
• 會話在可配置的時間段後逾時。要更改每個用戶允許的並發會話數量和會話逾時，請轉到Administration → System Settings → Security。

使用提供的 Java REST API 客戶端

範例 Java 代碼

import javax.ws.rs.core.Response.Status;

import org.jboss.resteasy.client.ClientResponse;
import org.jboss.resteasy.client.ClientResponseFailure;
import org.jboss.resteasy.client.ProxyFactory;
import org.jboss.resteasy.client.core.executors.ApacheHttpClient4Executor;
import org.jboss.resteasy.plugins.providers.RegisterBuiltin;
import org.jboss.resteasy.spi.ResteasyProviderFactory;

import com.trendmicro.ds.platform.rest.api.IAuthenticationAPI;
import com.trendmicro.ds.platform.rest.message.error.ErrorMessage;
import com.trendmicro.ds.platform.rest.object.DSCredentials;

public class AuthenticateSample {

	public static void main(String[] args) {
		// URL for the REST API. Change this as appropriate. 
		String restApiUrl = "https://10.0.0.5:4119/rest";
		
		// The user name to use for authentication. Change this as appropriate.
		String username = "admin";
		
		// The user's password. Change this as appropriate.
		String password = "supersecretpassword";

		// Variable to store the session identifier (SID).
		String sID = null;

		// RESTEasy client framework initialization that only needs to be done once per VM
		RegisterBuiltin.register(ResteasyProviderFactory.getInstance());

		// An object that will execute HTTP requests
		ApacheHttpClient4Executor executor = new ApacheHttpClient4Executor();

		// Create the object that will communicate with the authentication API.
		IAuthenticationAPI authClient = ProxyFactory.create(IAuthenticationAPI.class, restApiUrl, executor);

		// Create the object to pass to the authentication call.
		DSCredentials credentials = new DSCredentials();
		credentials.setUserName(username);
		credentials.setPassword(password);

			try {
				System.out.println("Attempting to authenticate to Server & Workload Security保護 REST API...");
				sID = authClient.login(credentials);
	
				System.out.println("Authentication successful.");
				System.out.println("Authentication session ID string received: " + sID);

			} catch (ClientResponseFailure e) {
				// This is a special type of exception that means the server threw
				// an exception because there was a problem with the credentials.
				// It's important to handle these exceptions explicitly or the
				// connection to the server won't be released back in to the
				// underlying connection pool, meaning any subsequent API calls would fail.
				// See the RESTEasy Client Framework documentation for more details. 
				ClientResponse<?> clientResponse = e.getResponse();

				// Try to parse the error response in to an instance of the special
				// ErrorMessage class and display the result.
				Status status = clientResponse.getResponseStatus();
				System.out.println("Server returned error status code " + status.getStatusCode() + " (" + status + ")");
				ErrorMessage errorMessage = clientResponse.getEntity(ErrorMessage.class);
				System.out.println("Returned error message: " + errorMessage.getMessage());

			} catch (Exception e) {
				// Some other error happened, most likely related to network communication problems.
				System.out.println("There was an error during authentication.");
				e.printStackTrace();
			
			} finally {
				if (sID != null) {
					// Make sure to always log out.
					System.out.println("");
					System.out.println("Ending session...");
					authClient.endSession(sID);
					System.out.println("End session successful.");
					// make sure the session ID isn't accidentally re-used.
					sID = null;
				}
			}
		
			// Cleanup: force the HTTP Client to close any open sockets
			executor.close();

	}
	
}

使用範例 Java 代碼

1. 在 Eclipse 中，點選 File → Import。
2. 選擇 General → Existing Projects into Workspace 作為匯入來源。
3. 點選Browse並選擇 Deep Security Web Services SDK 的範例資料夾作為根目錄。
4. 確保選擇了REST API Samples專案，然後點選Finish。

HTTP 狀態碼

錯誤回應

{
   "error": {
      "message": "The Activation Code KA47-R947M-KDLUZ-A8WLF-WM6A3-LOL is invalid."
   }
}

<error>
	<message>Error message string</message>
</error>

秘訣 要強制使用 XML 回應主體，請在您的請求中添加值為 application/xml 的 Accept 標頭。

返回 javax.ws.rs.core.Response 的 API 調用

org.jboss.resteasy.client.ClientResponse<?> clientResponse = (ClientResponse<?>)apiObject.methodThatReturnsResponse(methodParameters);
clientResponse.releaseConnection();

特殊考量

在查詢參數中指定日期