旧バージョンのREST API

元のバージョンのDeep Securityで元々リリースされていたREST APIは引き続き使用できますが、非推奨となっており、新機能は追加されません。可能な場合は、 Workload Security APIを使用して、新機能と継続的なサポートを利用する必要があります。

関連項目：従来のREST APIリファレンスドキュメント

レガシーREST APIで必要な機能が提供され、それらの機能がWorkload Security APIでまだ提供されていない場合、引き続きレガシーREST APIを使用する必要があります。次の表は、Workload Security APIにおけるREST APIの機能の概要を示しています。

エンドポイントが Workload Security APIに継続して追加されています。定期的にこのテーブルの変更を確認してください。

REST APIを使用するように環境を設定する

次のタスクを実行して、REST APIを使用した開発環境を準備します。

1. Deep Security WebサービスSDKのダウンロード
2. REST APIクライアントで使用できるユーザアカウントを作成する

WebサービスSDKのダウンロード

WebサービスSDK ZIPファイルをダウンロードして解凍します。

Deep Security WebサービスSDK

ZIPファイルには、REST APIドキュメント、Javaクライアントアプリケーションの開発に役立つJavaクライアントライブラリ、およびこのライブラリを使用するサンプルが含まれています。別の言語を使用している場合、またはJavaを使用していて独自のRESTクライアントテクノロジを使用する場合は、REST APIリファレンスドキュメントを使用してAPI呼び出しの構文を学習してください。このリファレンスでは、各オペレーションについて、HTTPパスとオペレーション (GET、PUTなど) を含むHTTP構文、およびAPIコールとの間でやり取りされるデータの構造について説明します。

コンテンツの完全なリストやその他の重要な情報については、ZIPのReadmeファイルを参照してください。

Webサービスの役割とユーザを作成する

Deep Security WebサービスAPIエンドポイント（SOAPおよびRESTの両方）にアクセスするための権限と、REST APIで使用するその他の機能を持つ役割を作成します。セキュリティ上の理由から、API呼び出し専用の役割とユーザを作成する必要があります。

REST APIでは、コンピュータ権限、セキュリティプロファイル権限、およびユーザ権限など、すべての役割アクセスコントロールが適用されます。たとえば、特定のコンピュータを表示できるWebサービスAPIの役割を作成する場合、そのユーザとして認証されるREST APIクライアントは指定されたコンピュータのみを表示できます。

1. Workload Security コンソールで、 [管理]→[ユーザ管理]→[ロール]の順に選択します。
2. [新規] をクリックします。
3. [ Workload Security Managerユーザインタフェース へのアクセスを許可]の選択を解除し、[ WebサービスAPIへのアクセスを許可]を選択します。
4. 他の設定がすべて完了したら、[保存] をクリックします。
5. アカウントに参加するようユーザを招待。
6. ユーザに必要なプロパティを指定します。[Role]プロパティで、作成した役割を選択します。
7. 新しいユーザアカウントのユーザ名とパスワードを書き留めておきます。

REST APIクライアントアプリケーションの開発

APIのドキュメントに従って、任意のプログラミング言語を使用して、REST APIを呼び出すコードを記述します。XMLまたはJSONエンコードをサポートするプログラミング言語、およびHTTPプロトコルとHTTPSプロトコルを使用できます。

関連項目：従来のREST APIリファレンスドキュメント

Basic APIへのアクセス

REST APIへのすべてのアクセスは、REST APIエンドポイント https://app.deepsecurity.trendmicro.com/restによって行われます。

REST APIでは標準のHTTPメカニズムが使用されるため、HTTP GETを使用した認証を行わずに一部の操作にアクセスできるため、Webブラウザからこれらのメソッドにアクセスできます。たとえば、次のURLはREST APIバージョンをブラウザに返します。

https://dsm.example.com:4119/rest/apiVersion

ただし、ほとんどのREST APIコールでは認証が必要です。呼び出しを認証するには、セッション識別子（SID）をGETメソッドとDELETEメソッドのクエリパラメータとして、またはPUTメソッドとPOSTメソッドのメッセージ本文として指定します。セッションIDを取得するには、APIへのアクセスが許可されたユーザのユーザ名とパスワードを使用して /rest/authentication/login URLを呼び出します。

セッションを管理する

セッションを管理するには、次の処理を実行します。

• APIセッションが不要になった場合にAPIセッションを終了します。Workload Security では、一度にアクティブにできるセッションの数を制限します。最大同時セッション数に達するのを避けるために、アプリケーションはセッションを終了する必要があります。セッションを終了するには、 /rest/authentication/logout URLを呼び出します。
• セッションは、設定可能な期間が経過した後にタイムアウトします。ユーザごとに許可される同時セッション数とセッションタイムアウトを変更するには、 [管理]→[システム設定]→[セキュリティ]を選択します。

Javaコードの例 は、このプロセスを示しています。

提供されているJava REST APIクライアント

提供されるJava REST APIクライアントは、 RESTEasy Client Framework および Apache HTTPComponentsプロジェクトに基づいています。このフレームワークは、JAX-RSアノテーションでマークアップされたJavaインタフェースを使用し、 Workload Securityと通信できるインタフェースの実装を生成します。Java REST APIクライアントは、すべてのオブジェクトのシリアル化と非シリアル化、HTTP URL、およびHTTPメソッドを処理します。

Java REST APIクライアントを使用するには、アプリケーションのクラスパスのlibフォルダにJARファイルを含めます。 JARファイルが他のサードパーティライブラリに依存している。詳細については、samplesディレクトリにあるEclipseプロジェクトの pom.xml ファイルを参照してください。

すべてのAPIのインタフェースは、Javaパッケージ com.trendmicro.ds.platform.rest.apiにあります。 APIとの間で送受信されるすべてのオブジェクトは、Javaパッケージ com.trendmicro.ds.platform.rest.object およびサブパッケージに含まれています。

Javaコードの例

次のサンプルコードでは、Java REST APIクライアントを使用して Workload Securityで認証を行います。

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 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コードの使用

Sample Javaコードはsamplesフォルダに含まれています。サンプルは、EclipseワークスペースにインポートできるEclipseプロジェクトの一部です。

1. Eclipseで、[File]→[Import]の順にクリックします。
2. インポート元として [General]→[Existing Projects into Workspace]を選択します。
3. [Browse]をクリックし、 Deep Security Web Services SDKのサンプルフォルダをルートとして選択します。
4. REST API Samples プロジェクトが選択されていることを確認し、[ Finish ]をクリックします。

Eclipse内でサンプルファイルを実行するには、ファイルを開き、[Run]→[Run As]→[Java Application] をクリックします。サンプルには、[Run Configurations]画面で設定する必要があるコマンドライン引数が必要です。

HTTPステータスコード

REST APIでは、標準HTTPステータスコードを使用してリクエストのステータスが返されます。次の表は、使用されるレスポンスコードと、それらが返される状況を示しています。

エラー応答

API呼び出しで 200 OK以外のステータスコードが返された場合、通常、応答本文には次の例のようなJSONコードが含まれます。

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

一部のコールには、次の例のようにJSONではなくXMLコードが含まれます。

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

XMLレスポンス本文を強制的に使用するには、 リクエストにapplication/xmlの値とともにAccept ヘッダを追加します。

このエラーメッセージは、問題のデバッグに役立ちますが、アプリケーションのエンドユーザにプレゼンテーションするのには適していません。

javax.ws.rs.core.Responseを返すAPI呼び出し

いくつかのAPIコールは、javax.ws.rs.core.Response型のオブジェクトを返すものとしてドキュメント化されています。これらのコールは、HTTPステータスコード以上のものを返すものと考えることができます。

提供されたJava REST APIクライアントを使用する場合、そのようなコールを無視するのではなく、その結果を取得することが重要です。Response オブジェクトを取得したら、RESTEasy Client Frameworkの説明に従って、サーバとの接続を手動で接続プールに解放する必要があります。たとえば、次のとおりです。

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

特別な考慮事項

クエリパラメータ

検索クエリで日付を指定する場合は、 RFC 822のセクション5に記載されている日付エンコードルールを使用してエンコードします。ただし、年は、 RFC 1123のセクション5.2.14に従って、2桁ではなく4桁でエンコードする必要があります。たとえば、 November 31 2012 at 3:45 PM Eastern Standard Time を 31 Nov 2012 15:45:00 -0500としてエンコードします。

Javaでは、 java.text.SimpleDateFormat と日付形式パターン dd MMM yyyy HH:mm:ss zzzを使用してこれらの日付をエンコードできます。

たとえば、セッションIDが DC5A4AA79326DF3E149A26EA2DA6B0C7の場合、 November 31 2012 at 3:45 PM Eastern Standard Timeの後に次のURLがすべてのホスト保護情報を照会します。ここで、日付エンコードの空白は %20でURLエンコードされています。

https://dsm.example.com:4119/rest/monitoring/usages/hosts/protection?sID=DC5A4AA79326DF3E149A26EA2DA6B0C7&from=31%20Nov%202012%2015:45:00%20-0500