Verwenden Sie die Legacy-REST-API

Wann die Legacy-REST-API verwendet werden sollte

Hinweis Endpunkte werden kontinuierlich zur Server- und Workload Protection-API hinzugefügt. Überprüfen Sie regelmäßig diese Tabelle auf Änderungen.

Richten Sie Ihre Umgebung ein, um die REST-API zu verwenden

1. Laden Sie das Deep Security Web-Services-SDK herunter
2. Erstellen Sie ein Benutzerkonto, das ein REST-API-Client verwenden kann

Laden Sie das Web-Services-SDK herunter

Erstellen Sie eine Webdienstrolle und einen Benutzer

1. Navigieren Sie in der Server- und Workload Protection Konsole zu Administration → Benutzerverwaltung → Rollen.
2. Klicken Sie auf Neu.
3. Deaktivieren Sie Allow Access to Workload Security Manager User Interface und aktivieren Sie Allow Access to Web Service API.
4. Wenn alle anderen Konfigurationen abgeschlossen sind, klicken Sie auf Speichern.
5. Laden Sie einen Benutzer ein, dem Konto beizutreten, wie hier beschrieben.
6. Geben Sie die erforderlichen Eigenschaften für den Benutzer an. Wählen Sie für die Eigenschaft Rolle die Rolle aus, die Sie gerade erstellt haben.
7. Notieren Sie sich den Benutzernamen und das Passwort des neuen Benutzerkontos.

Entwickeln Sie eine REST-API-Clientanwendung

Grundlegender API-Zugriff

Verwalten Sie Ihre Sitzungen

• Beenden Sie API-Sitzungen, wenn sie nicht mehr benötigt werden. Server- und Workload Protection begrenzt die Anzahl der Sitzungen, die gleichzeitig aktiv sein können. Ihre Anwendung sollte ihre Sitzungen beenden, um die maximale Anzahl gleichzeitiger Sitzungen nicht zu erreichen. Rufen Sie die /rest/authentication/logout-URL auf, um die Sitzung zu beenden.
• Sitzungen laufen nach einem konfigurierbaren Zeitraum ab. Um die Anzahl der gleichzeitigen Sitzungen pro Benutzer und die Sitzungszeitüberschreitung zu ändern, gehen Sie zu Administration → System Settings → Sicherheit.

Verwenden Sie den bereitgestellten Java REST API-Client

Beispiel-Java-Code

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- und Workload Protection 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();

	}
	
}

Verwenden Sie den Beispiel-Java-Code

1. Klicken Sie in Eclipse auf Datei → Importieren.
2. Wählen Sie Allgemein → Existing Projects into Workspace als Importquelle aus.
3. Klicken Sie auf Durchsuchen und wählen Sie den Beispielordner des Deep Security Web-Services-SDK als Stammverzeichnis aus.
4. Stellen Sie sicher, dass das REST API Samples-Projekt ausgewählt ist, und klicken Sie auf Fertig stellen.

HTTP-Statuscodes

Fehlermeldungen

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

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

Tipp Um die Verwendung eines XML-Antwortkörpers zu erzwingen, fügen Sie Ihrer Anfrage einen Accept-Header mit dem Wert application/xml hinzu.

API-Aufrufe, die javax.ws.rs.core.Response zurückgeben

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

Besondere Überlegungen

Geben Sie Daten in Abfrageparametern an