REST HTTP メソッド

この記事には、以下のトピックが含まれています。
casm173
この記事には、以下のトピックが含まれています。
REST API は、リソースを操作する以下の HTTP メソッドをサポートします。
  • POST (CREATE)はリソースを作成します。
  • GET (READ)は、リソースの表現を返します。
  • PUT (UPDATE)は既存のリソースを更新します。
  • DELETE はリソースを削除します。
このメソッドの基本的なセットを CRUD と呼びます。 各メソッドはすべての CA SDM リソース上で同じように動作します。 HTTP クライアント ライブラリが必要ですが、これはほとんどのプログラミング言語で利用できます。 以下のタスクを行う場合、HTML クライアント ライブラリを使用します。
  • 複数レベルの URI パスを使用して、関連付けられた(または関連する)リソースにアクセスし、変更する。
  • 操作するリソースのサーバに HTTP リクエストを送信する。
  • HTTP ヘッダを使用して、返されるオブジェクト属性を制御する。
Majic オブジェクト定義を更新し、CA SDM をリサイクルしたら、製品は該当する POJO (Plain Old Java Objects)を自動的に再生成し、REST Tomcat
webapps
ディレクトリに再展開します。
pdm_rest_util コマンド ライン ユーティリティを使用すると、REST Web サービスが必要とする Java コードを
手動で
生成、コンパイル、および展開できます。
応答
しない
属性リクエストは、NULL 属性値を示します。 REST の応答では、NULL 属性値が表示
されない
ため、クライアント コードを適宜変更してください。
REST Web サービスは、ローカル サーバ上の専用 domsrvr への接続を可能にすることで、ユーザに拡張性のある構成とさらなる柔軟性を提供します。 CA SDM Release 12.9 は、デフォルトで NX_REST_WEBSERVICE_DOMSRVR 変数を domsrvr に指定します。 NX.env を編集することでこの設定を変更できます。
CA SDM では REST のサンプル モバイル ユーザ インターフェースは無効にされており、REST Web サービスを介して Majic ファクトリがデフォルトで公開されています。
REST API は、DOUBLE タイプの Majic 属性をサポートしません。
以下の表に、REST API がリソースに対して HTTP メソッドを使用する方法を説明します。
リソース
CREATE
READ
UPDATE
DELETE
コレクション URL
例: http://mywebsite.com/resources/
コレクションにエントリを作成します。 新しいエントリに自動的に URL を割り当て、操作によってそれを返します。
URL およびコレクション メンバの他の詳細をリスト表示します。
N/A
N/A
エレメント URL
例: http://mywebsite.com/resources/item1
N/A
アドレス指定されたコレクション メンバの表現を取得します。
コレクションのアドレス指定されたメンバを更新し、メンバが存在しない場合は作成します。
アドレス指定されたコレクション メンバを削除します。
CRUD 操作用のサンプル URI パス
以下の表に、CRUD 操作用のサンプル URI パスを示します。
CRUD 操作
HTTP メソッド
名詞
サンプル URI パス
CREATE
Post
URI
/caisd-rest/chg
READ (複数)
GET
コレクション URI
/caisd-rest/chg
Read (複数、フィルタあり)
GET
コレクション URI
/caisd-rest/chg?WC=status%3D6001
Read (単一 ID)
GET
エントリ URI
/caisd-rest/chg/400001
Read (単一の COMMON_NAME)
GET
エントリ URI
/caisd-rest/chg/COMMON_NAME-21
Read (単一の REL_ATTR)
GET
エントリ URI
/caisd-rest/chgstat/REL_ATTR-OP
更新
PUT
エントリ URI
/caisd-rest/chg/40001
削除
DELETE
エントリ URI
/caisd-rest/grpmem/400001
COMMON_NAME と REL_ATTR では大文字と小文字が区別されます。 大文字を使用しないと、REST は HTTP-404 エラー コードを返します。
REST に関する考慮事項
REST メソッドについて、以下の情報を考慮してください。
  • POST 操作は、提供された表現からリソースを作成します。ただし、CA SDM は、内部的に属性値を追加または変更できます。 これらの値は、属性がトリガするビジネス オブジェクトのロジック、SPEL コード、メソッド、またはそれら両方に基づきます。 結果として、POST 操作は、作成した実際の表現をクライアントに返します。 この動作により、クライアントは、サーバに送信した表現と、作成した実際の表現とを一致させることができます。
  • GET 操作については、WHERE 節でスペースの代わりに
    %20
    を入力します。
REST の制限事項
REST API は、リソースのクエリまたは属性において、ドット付きの属性名参照をサポートして
いません
。 REST は、関係クエリにおいてドット付きの属性を含む BREL、QREL、LREL 属性を公開
しません
。 たとえば、base.maj 内の chg オブジェクトには以下の QREL 属性が含まれます。
workload_chg QREL chg DYNAMIC { WHERE "assignee = ? and active = 1" ; PARAM_NAMES { id } ; DOMSET chg_list; } ; change_tasks QREL wf DYNAMIC { WHERE "assignee = ? AND status.allow_task_update = 1 " ; PARAM_NAMES { id } ; DOMSET wf_list ; } ;
この例では、workload_chg QREL 属性が使用可能です。 change_tasks QREL は、WHERE 節にドット付き属性(status.allow_task_update)が含まれているため、使用できません。
REST とオブジェクト アクセス
多くの CA SDM コンポーネントがオブジェクトで構成されています。 これらのオブジェクトは、Majic というメタ言語で定義されています。 Majic ステートメントでは、オブジェクトの作成や既存オブジェクトの変更が可能なため、ビジネスの要件に合わせて、これらのオブジェクトをカスタマイズすることができます。 REST による CA SDM オブジェクトへのアクセスについて、以下のようにカスタマイズすることができます。
  • REST によるオブジェクトへのアクセスの可否
  • 各オブジェクトに対して許可される操作
CA SDM をインストールした状態では、REST によってすべてのオブジェクトにアクセスできます。 REST_OPERATIONS キーワードは、オブジェクトに対して実行できる操作を指定します。 デフォルトでは、すべてのオブジェクトに対して CREATE、READ および UPDATE 操作を行うことができます。 デフォルトのオブジェクトの中には、REST_OPERATIONS リストのオブジェクト定義に示されているように、DELETE 操作が可能なものもあります。 デフォルトのセットアップでは、REST_OPERATIONS キーワードを使用する必要は
ありません
。 オブジェクトへのアクセスを再設定して以下のタスクを行うことができます。
  • Majic MODIFY ステートメントを使用して、DELETE 以外の操作を削除または追加し、REST_OPERATIONS リストを上書きします。
    注:
    デフォルト オブジェクトに DELETE 操作を追加することはできません。
  • REST_OPERATIONS リストで NONE を指定することにより、REST からオブジェクトを完全に削除します。
rest_access リソース
rest_access リソースには、認証されたユーザの REST API アクセス情報が含まれています。 これは管理用のテーブルで、REST API を介してアクセスできるユーザのリストが含まれています。
以下のリストに、デフォルトの動作との相違点を示します。
  • POST
    REST アクセス オブジェクトを作成し、デフォルト値の一部として、アクセス キー、秘密鍵、および有効期限を返します。
  • GET
    REST アクセス情報を取得します(秘密鍵を除く)。
  • DELETE
    REST アクセス オブジェクトを削除します。
  • PUT
    Majic WRITE_NEW プロパティにより、secret_key、access_key、および連絡先の更新は許可されていません。
REST_OPERATIONS キーワード
Majic キーワードの REST_OPERATIONS は、かっこ付きのトークンのリストを使用します。 これらのトークンを使用して、オブジェクトに許可された REST 操作を指定できます。 キーワードをカスタマイズするには、オブジェクト定義および MODIFY 節を使用します。
REST_OPERATIONS キーワードの構文は以下のとおりです。
REST_OPERATIONS "[<OP>],[<OP>] | NONE";
  • OP
    CREATE、READ、UPDATE および DELETE 操作を指定します。
このキーワードは以下のステートメントを作成します。
REST_OPERATIONS "CREATE, READ, UPDATE DELETE"; REST_OPERATIONS "NONE";
実行中、CA SDM では以下の Majic の MODIFY ステートメントを使用した上書きが許可されます。
MODIFY FACTORY cr { REST_OPERATIONS "READ, UPDATE"; };
REST_OPERATIONS の構文例
以下の例では、操作を READ と UPDATE に制限するために cr オブジェクトを変更します。 オブジェクトの作成または削除を試行すると、「
HTTP error code 405 Method Not Allowed
のエラーが返されます。
CA SDM では、ほとんどのオブジェクトの REST_OPERATIONS プロパティのデフォルト値は、"CREATE READ UPDATE" に設定されています。 たとえば、cr、iss、および chg がこれに該当します。 オブジェクトによって CA SDM は、REST_OPERATIONS のデフォルト値を "CREATE READ UPDATE DELETE" に設定します。たとえば、rest_access や KCAT などの場合です。
MODIFY FACTORY cr { REST_OPERATIONS "READ UPDATE"; };
以下の例では、REST からアナウンスメントが完全に削除されます。
MODIFY FACTORY cnote { REST_OPERATIONS "NONE"; };
注:
MODIFY ステートメントで DELETE を使用することはできません。 NONE 操作は単独で使用します。MODIFY ステートメントで CREATE READ UPDATE と組み合わせることはできません。
REST API サーブレットの設定
Web 展開記述子
web.xml
ファイルで、REST API の追加設定を指定できます。 ファイル
$NX_ROOT/site/rest/web.xml.tpl
はテンプレートとして提供されているため、変更しないでください。 初めて CA Service Desk Manager を起動すると、このテンプレートから同じディレクトリに
web.xml
ファイルが作成されます。 このファイルを変更して、WAR ファイルの一部として展開できます。
利用可能なパラメータ
ExternalBaseURI
このオプション設定では、応答に含まれるハイパーリンクのカスタム REST API アドレスを指定できます。 これは、ロード バランサ、リバース プロキシ サーバ、外部ホスト名、https アドレスなどが存在するサイトで役立ちます。REST API Web アプリケーション名(caisd-rest など)がこの値に含まれていることを確認します。 サンプル デフォルト値は http://host:8050/caisd-rest です。
以下の手順に従います。
  1. すべての CA Service Desk Manager サービスを停止します。
  2. $NX_ROOT/site/rest/ フォルダに移動して、
    web.xml
    ファイルを編集します。
  3. ファイル内で REST API 外部アドレス セクションを見つけて、以下の要素のコメント化を解除します。
    <context-param>
    <param-name>ExternalBaseURI</param-name>
    <param-value>http://host:port_number/caisd-rest</param-value
    >
    </context-param>
    host:port_number
    を適切な外部アドレスに置き換えます。
  4. ファイルを保存して閉じます。
  5. CA Service Desk Manager サービスを再起動します。
    Tomcat が正常に起動しないか、またはエラーを報告する場合は、ファイルを再作成できます。
更新操作での NULL 値
HTTP ヘッダ
X-AttrsToNull
を設定し、更新操作のために NULL 値を属性に割り当てることができます。 このヘッダは、カンマ区切りの属性名のリストを使用します。 重複する場合、ヘッダ値はリクエスト本文内の属性より優先されます。 BREL および QREL タイプの属性は適用されませんが、SREL 属性は適用されます。
例 1
:リクエスト チケットの
call_back_date
属性を NULL に更新します。 この例では、
call_back_date
を NULL に設定するには、
call_back_flag
が 1 以外である必要があります。
HTTP URL: PUT /caisd-rest/cr/400055HTTP ヘッダ X-AttrsToNull: call_back_dateペイロード(XML): <cr><call_back_flag>0</call_back_flag></cr>
例 2
: 連絡先の電子メール アドレスを NULL に更新します。
HTTP URL: PUT /caisd-rest/cnt/U'ADE6396E2A3D9E4A958AC522521C5A35'HTTP ヘッダ X-AttrsToNull: email_addressペイロード(XML): <cnt></cnt>
上記の例ではすべての HTTP ヘッダは表示されません。
BLREL での作業
BLREL キーワードは、LREL テーブルを参照している Majic 属性を参照します。 これらの属性は 3 ファクトリ関係の一部です。 BLREL 属性は、CA SDM の以前のリリースでは LREL 属性と呼ばれていましたが、BREL 属性に変更されました。 この名前により、BLREL を、2 ファクトリ関係である旧 BREL 属性と識別できます。
この 3 ファクトリ関係の一例は、グループとメンバの関係です。 この関係は grp オブジェクト、cnt オブジェクト、および grpmem オブジェクトが表す LREL テーブル オブジェクトから構成されます。 この 3 ファクトリ関係では、2 つの BLREL 属性は常に共通の LREL テーブルを参照します。 グループ/メンバの関係において、両方の BLREL 属性が同じオブジェクトの一部であるケースはよくありますが、常にそうであるわけではありません。
以下の例では、CA SDM が Majic ファイル内で BLREL 属性を定義する方法が示されています。
OBJECT cnt { ... member_list BREL grpmem group DYNAMIC { LREL member; } ; group_list BREL grpmem member DYNAMIC { LREL group; } ; }
オブジェクトの属性は、アクティブなシステム上で bop_sinfo コマンドを実行することにより、いつでも表示することができます。
bop_sinfo -d grpmem
LREL テーブル レコードは、異なる 2 つのテーブルのレコード間の関連付けを作成します。 グループ/メンバの関係について、grpmem レコードはこの関連付けを作成する LREL テーブルです。 グループが多くのメンバを持つことができ、また、メンバは多くのグループに所属することができるため、これは多対多の関係です。
WHERE 節を使用したリソース検索
REST Web サービスでは、GET リクエストに
WC
(WHERE 節)クエリを使用できます。 REST Web サービスでは、GET リクエストに WC (WHERE 節)クエリを使用できます。 REST は SQL クエリ表記法をサポートし、Majic クエリ表記法を限定的にサポートします。 たとえば、属性のドット区切り表記法は、製品(SOAP)の他の領域で渡された場合に渡されます。 URL に WC パラメータを追加しない場合、ページ サイズおよび最大サイズを上限とするすべてのレコードが返されます。
以下の情報について検討します。
  • すべてのリクエストで、パーセント(%)のエンコーディングを使用してから、サーバに送信してください。 たとえば、「=」(等号)の代わりに
    「%3D
    」と入力します。
  • WC パラメータは、メッセージ ヘッダではなく URI の一部であるため、ブックマークの設定が可能です。
  • WC クエリ パラメータはコレクションの GET リクエストにのみ適用されます。
例: 姓が「ServiceDesk」と等しい連絡先レコードの検索
http://<host>:<REST port>/caisd-rest/cnt?WC=last_name%3D'ServiceDesk'
例: 優先度 2 のインシデントの検索
/in?WC=priority%3D4
例における「4」の値は、優先度 2 のレコードの REL_ATTR 値を示しています。
優先度などの SREL 属性を参照する場合、WC パラメータ内で REL_ATTR 値を使用します。
例: [概要]フィールドに「test%」を含むインシデントの検索
/in?WC=summary%20LIKE%20'test%25'
有効な URI パスのパターン
URI パス レベルおよびリソースにより、すべてのリソース パスおよびサブリソース パスで、4 つすべての HTTP メソッドが公開されているわけではありません。 以下のリストに、公開されているメソッドを示します。
  • /caisd-rest/<ファクトリ>
例:
/caisd-rest/cr
GET はオブジェクトを検索し、オブジェクトのコレクションを返します。
POST はオブジェクトを作成し、作成したオブジェクトを返します。
  • /caisd-rest/<ファクトリ>/<オブジェクト ID>
例:
/caisd-rest/cr/400001
GET は、1 つのオブジェクトの詳細を返します。
PUT はオブジェクトを更新します。
DELETE はオブジェクトを削除します。 ただし、これは許可されている場合に限ります。
  • /caisd-rest/<ファクトリ>/<オブジェクト ID>/<属性名(SREL)>
例:
/caisd-rest/chg/400001/status
GET は、SREL 属性オブジェクトの詳細を返します。ID がわかっている場合に SREL オブジェクトに直接アクセスするのと同じ動作になります。 例: /caisd-rest/crs/5200
  • /caisd-rest/<オブジェクト>/<オブジェクト ID>/<属性名(BREL)>
例:
/caisd-rest/chg/400001/act_log
GET は、BREL が参照しているタイプのオブジェクトのコレクションを返します。
  • /caisd-rest/<ファクトリ>/<オブジェクト ID>/<属性名(BLREL)>
例:
/caisd-rest/chg/400001/attachments
GET は、BLREL が参照しているタイプのオブジェクトのコレクションを返します(LREL レコード)。
  • /caisd-rest/<ファクトリ>/<オブジェクト ID>/<属性名(QREL)>
例:
/caisd-rest/chg/400001/workflow
GET は、QREL が参照しているタイプのオブジェクトのコレクションを返します。
検索結果の並べ替え
CA SDM Web サービスでは、URI の一部として含まれている SORT クエリ パラメータを使用して、検索結果を並べ替えることができます。 並べ替えの順序指定用に属性のリストを指定できます。 また、ASC を指定すると昇順、DESC を指定すると降順に並べ替えることができます。
デフォルトの動作では、DBMS が ORDER BY 節に提供しているのと同じサポートが SORT パラメータでも提供されます。 たとえば、ASC または DESC を省略すると、DBMS は自動的に ASC を使用する可能性があります。 URI で SORT パラメータを指定しないと、DBMS はデフォルトで
id ASC
を使用します。
この動作は、以下の例のように、コレクションの GET リクエストにのみ適用されます。
GET http://<host>:<REST-port>/caisd-rest/<fac name> GET http://myserver:8080/caisd-rest/cr?SORT=priority DESC, severity ASC
以下の情報について検討します。
  • すべてのリクエストをエンコードした後にサーバに送信する
    必要があります
    。 たとえば、スペースの代わりに
    %20
    と入力します。
  • SORT パラメータで指定されたすべてのオブジェクト属性は、オブジェクト属性の X-Obj-Attrs リストに自動的に追加されます。 この動作により、並べ替え用に選択した属性が、確実に応答の一部となります。
  • SORT パラメータは、メッセージ ヘッダではなく URI の一部であるため、ブックマーク設定が可能です。
注:
X-Obj-Attrs ヘッダを指定しない場合、応答の一部として常に表示される、ID、REL_ATTR および COMMON_Name がデフォルトでリスト表示されます。
検索結果のナビゲーション
検索結果表示でのナビゲーションを向上するために、ATOM リンクが提供されています。 このリンクを使用すると、検索結果のレコードが多すぎる場合、前後のリストに移動することができます。 デフォルトでは、コレクションの GET 結果には、最大 25 レコード含まれます。 ページ長と最大表示レコード数を設定するには、rest_webservice_list_page_length および rest_webservice_list_max_length オプションを使用します。
ATOM リンクは、該当するレコードが存在する場合にのみ表示されます。 ページにリストの最初のレコードが含まれる場合、REST は「
前へ
」のリストへのリンクを表示しません。 同様に、表示できるレコードがさらに存在する場合にのみ、REST は「
次へ
」および「
すべて
」のリストへのリンクを表示します。
また、自分の戻り値サイズのリストに
サイズ
のパラメータを指定できます。
サイズ
を指定しない場合、REST は rest_webservice_list_page_length で指定されたデフォルト値を取ります。 開始ページを指定しない場合、REST はデフォルトの 1 の値を取ります。
例: 特定のレコード数を返させるリクエスト
この例では、10 レコード返すようリクエストします。
http://myserver:8050/caisd-rest/cnt?start=11&size=10
この結果セットに 50 レコードが含まれる場合、以下のリンクが表示されます。
<link href="http://myserver:8050/caisd-rest/cnt?start=1&size=10" rel="previous"/> <link href="http://myserver:8050/caisd-rest/cnt?start=21&size=10" rel="next"/> <link href="http://myserver:8050/caisd-rest/chg?start=1&size=50" rel="all"/>
注:
結果セットに最大数を超えるレコードが含まれている場合、「すべて」リンクは表示されません。
HTTP ステータスおよびエラー コード
すべての HTTP 応答には HTTP ステータス コードが含まれます。 成功した HTTP 応答コードの番号は 200 ~ 399 の値になります。 標準の HTTP エラー コードの番号は 400 ~ 599 の値になります。
各 HTTP メソッドが成功または失敗した場合に REST API が返すコード番号を以下のリストに示します。
  • GET (単一)
    200、400、401、404 409
  • GET (コレクション)
    200、400、401
  • PUT
    200、400、401、404 409
  • DELETE
    204、400、401、409
  • POST
    201、400、401、409
注:
PUT と DELETE の操作について、API は、ID の妥当性を最初に判定
しません
。 代わりに、API は、クエリの更新と削除を直接実行しようとします。 エラーが発生した場合、API は「
409 Conflict
」コードを返します。 この状況で、API が「
404 Not Found
」コードを返した場合、パフォーマンスは低下します。
また、その他の状況におけるエラー メッセージを以下に示します。
  • HTTP リクエストには無効またはアクセス不能な URI アドレスが含まれる場合、サーバは「
    404 Not Found
    」応答コードを返します。
  • HTTP リクエストに、有効な URI に対するサポートされていない HTTP メソッドが含まれる場合、サーバは「
    405 Method Not Allowed
    」応答コードを返します。
  • HTTP リクエストが、サポートされていないメディア タイプを(Accept ヘッダによって)リクエストした場合、サーバは「
    406 Not Acceptable
    」応答コードを返します。
  • HTTP リクエストがサポートされていないメディア タイプ(Content-Type ヘッダ)を送信した場合、サーバは「
    415 Unsupported Media Type
    」応答コードを返します。
  • さまざまな構文または内部的な Web サーバ エラーの場合、「500」の内部エラーが返される場合があります。
コード対応の制限事項
HTTP で利用可能なコード数には制限があるため、CA SDM のすべてのエラーが HTTP エラー コードに対応しているわけではありません。 可能な場合、エラーを一致させて、対応する HTTP エラー コードを返しますが、ほとんどのバックエンド プロセス エラーでは、一般的な「
400 Bad Request
」コードが返されます。 エラーの概要はメッセージに示されています。
以下のエラー メッセージは対応する HTTP エラー コードと一致しています。 その他のものについては、すべてエラー コード 400 が使用されます。
  • CA SDM に存在しないリソースのリクエストでは、「
    404 Not Found
    」エラー コードが返されます。
  • 一意ではない COMMON_NAME 値を使用した場合のように、複数の一致が返されるリソース リクエストを行った場合は、「
    409 Conflict
    」エラー コードが返されます。
  • 認証失敗、または各機能へのアクセス セキュリティによりアクセスできないリソースに対してリクエストを行った場合、「
    401 Unauthorized
    」エラー コードが返されます。
既知のステータス コード
以下のリストでは、API が返す既知のステータス コードについて説明します。 エラーのタイプによっては、Web サーバまたは CXF フレームワークの他のコードが存在する場合があります。
  • 200
    OK
    正常な戻り値であることを示します。
  • 201
    作成
    新しいレコードであることを示します。
  • 204
    No Content
    応答の本文が空であることを示します。
  • 304
    Not Modified
    レコードが更新されなかったことを示します。
  • 400
    Bad Request
    ユーザまたはバックエンドのサーバの問題により、エラーが発生したことを示します。
  • 401
    Unauthorized
    関数 Access のエラー、またはその他の認証エラーであることを示します。
  • 404
    未検出
    レコードが見つからないことを示します。
  • 405
    Method Not Allowed
    HTTP メソッドがサポートされていないことを示します。
  • 406
    Not Acceptable
    リクエストされたフォーマットがサポートされていないことを示します。
  • 409
    Conflict
    指定した識別子に対して複数のレコードが見つかったことを示します。
  • 415
    Unsupported Media Type
    指定したフォーマットがサポートされていないことを示します。
  • 500
    Internal Server Error
    サーバまたは CXF フレームワークのエラーであることを示します。
Atom フィード
Atom フィードはレコードのリストを表しているため、CA SDM は、URI パスによるコレクションの GET を通じて Atom フィードをサポートしています。 この実装では、WC、start、size などの、REST Web サービスがサポートするすべてのクエリ パラメータがサポートされています。 さらにこの実装では、2 つのクエリ パラメータ、EntryTitle および EntrySummary が追加的にサポートされ、Atom エントリ タイトルおよび概要エレメントと Majic 属性間のマッピングを指定できます。
EntryTitle=<Majic attribute name> EntrySummary=<Majic attribute name>
注:
これらのパラメータを指定
しない
場合、REST はデフォルトのタイトルおよび概要の値として COMMON_NAME を使用します。
以下のサンプルは、これらのクエリ パラメータを示しています。
GET /caisd-rest/cnt?size=2&EntryTitle=userid&EntrySummary=notes HTTP/1.1 Accept: application/atom+xml
以下のサンプルは、Atom による応答を示しています。
<?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom"> <author> <name>CA Service Desk Manager</name> </author> <title type="text">REST API Atom feed</title> <id>http://myserver:8050/caisd-rest/cnt</id> <updated>2012-01-17T17:56:04.301Z</updated> <link href="http://myserver:8050/caisd-rest/cnt?start=3&#38;size=2" rel="next"/> <link href="http://myserver:8050/caisd-rest/cnt?start=1&#38;size=12" rel="all"/> <link href="http://myserver:8050/caisd-rest/cnt" rel="self"/> <entry> <author> <name>CA Service Desk Manager</name> </author> <title type="text">System_AM_User</title> <id>http://myserver:8050/caisd-rest/cnt/U'16226C765005B94E957E0F477DEF1B1C'</id> <updated>1970-01-01T00:00:00.000Z</updated> <summary type="text"> User for Asset Management Integration</summary> <content type="application/xml"> <cnt id="U'16226C765005B94E957E0F477DEF1B1C'" REL_ATTR="U'16226C765005B94E957E0F477DEF1B1C'" COMMON_NAME="System_AM_User" xmlns=""> <link href="http://myserver:8050/caisd-rest/cnt/U'16226C765005B94E957E0F477DEF1B1C'" rel="self"/> </cnt> </content> </entry> <entry> <author> <name>CA Service Desk Manager</name> </author> <title type="text">cavizuser</title> <id>http://myserver:8050/caisd-rest/cnt/U'17DEA1027C7C3746B6F25DB6604EEE23'</id> <updated>1970-01-01T00:00:00.000Z</updated> <summary type="text">Username used by Visualizer for accessing CA Service Desk Manager using Web Services</summary> <content type="application/xml"> <cnt id="U'17DEA1027C7C3746B6F25DB6604EEE23'" REL_ATTR="U'17DEA1027C7C3746B6F25DB6604EEE23'" COMMON_NAME="System_CMDB_Visualizer_User" xmlns=""> <link href="http://myserver:8050/caisd-rest/cnt/U'17DEA1027C7C3746B6F25DB6604EEE23'" rel="self"/> </cnt> </content> </entry> </feed>
データ形式リクエスト時の REST の追加サポート
REST Web サービスでは、URI を使用した、他の表現形式の指定方法もサポートされています。 この Web サービスは、HTTP の Accept ヘッダでの表現形式の指定と同様の方法で動作します。
例 1:
GET /caisd-rest/chg/400001.xml HTTP/1.1
GET /caisd-rest/chg/400001.json HTTP/1.1
GET /caisd-rest/chg.feed HTTP/1.1
例 2:
GET /caisd-rest/chg/400001?_type=xml HTTP/1.1
GET /caisd-rest/chg/400001?_type=json HTTP/1.1
GET /caisd-rest/chg?_type=atom HTTP/1.1
以下の情報について検討します。
  • 表現形式が URI と "Accept" ヘッダの両方で指定されている場合、URI での指定が優先されます。
  • 表現形式がいかなる方法でも指定されていない場合、デフォルトでは、表現は XML 形式で返されます。
  • _type=
    」クエリ パラメータは、すべてのパラメータに優先します。
CA SDM の役割の権限
SOAP Web サービスと同様、REST Web サービスのアクセス キー作成(ログイン操作)には、ユーザに REST Web サービスにアクセスするための権限があるかどうかの検証動作が含まれています。 SOAP ではこの検証は、Web サービスおよび API 役割ルックアップ フィールドによって、アクセス タイプ詳細フォームで制御されます。 REST では、「REST Web サービス API 役割」という名前の新しいルックアップ フィールドが REST の検証を制御します。 このフィールドには 1 つの役割のみ関連付けることができ、このフィールドはユーザのデフォルトの役割となります。 このルックアップ フィールドが空の場合、このアクセス タイプに属するユーザは REST Web サービス インターフェースを経由して CA SDM にアクセスする権限がありません。
さらに、REST Web サービスは、Web クライアント インターフェースの一部である、添付された役割リストと同じリストをサポートしています。 REST ユーザは、リクエストの一部として追加メッセージ ヘッダを渡すことにより、添付された役割(連絡先レコードの役割を含みます)のリストとは異なる枠割を選択できます。
例: リクエストに管理者役割を使用
POST /caisd-rest/cnt HTTP/1.1 Host: hostname Date: Mon, 21 Apr 2011 19:37:58 +0000 X-Role: 10002
REST Java サンプル コード
CA SDM は、サンプル コードを提供しています。NX_ROOT/samples/sdk/rest/java ディレクトリにあります。 これらのサンプル ファイルを使用して、SOAP Web サービス サンプルのように、自分の環境内でカスタム Java クライアント コードを作成することができます。 このディレクトリには、README.txt ファイル内のサンプル プログラムをコンパイルおよび実行するための手順が含まれます。 各 Java ファイルには、追加の手順およびサンプル入力パラメータが記載されています。 \rest\java 内のディレクトリと、提供されるサンプルを以下に示します。
  • test1_basic
  • SampleBasicAuth.java
    基本認証スキームによる、ユーザ名/パスワードを使用したアクセス キーの取得方法を示します。
  • SampleCRUDOperations.java
    インシデント チケットに対して単純な CRUD 操作(Create、Read、Update、Delete)を実行する方法を示します。 CA SDM 内の他のすべてのオブジェクトで同じ方法を使用できます。
  • test2_auths
  • SampleBOPSIDAuth.java
    BOPSID トークンを使用して、アクセス キーを取得する方法を示します。 この CA SDM のトークンは、SOAP Web サービスなどの他の CA SDM のインターフェースから取得できます。
  • SampleEEMAuth.java
    CA EEM アーチファクト/トークンを使用してアクセス キーを取得する方法を示します。 このトークンは、認証サーバとして CA EEM を使用する他のアプリケーションから取得できます。
  • SampleSDMAuth.java
    CA SDM カスタム認証スキームによる、ユーザ名/パスワードを使用したアクセス キーおよび秘密鍵の取得方法を示します。
  • SampleUsingSecretKey.java
    秘密鍵を使用して、REST API リクエスト(連絡先リストの取得)を行う方法を示します。 CA SDM カスタム認証操作から取得した秘密鍵を使用して、設定可能なデータ量を暗号化します。 このスキームを使用するすべてのリクエストは、秘密鍵によって検証されます。
  • test3_attachments
  • SampleNewResourceWithAttachment.java
    一度の手順で、ドキュメントの添付された変更要求チケットを新規作成する方法を示します。
  • SampleAttachFileToResource.java
    既存の変更要求チケットにドキュメントを添付する方法を示します。
  • test4_xrels
  • SampleGetQRELDetails.java
    QREL 属性の詳細を取得する方法を示します。 このサンプルでは、chg.children の詳細が取得されます。 BREL および BLREL 属性に対しても同じ方法を適用できます。
  • SampleCreateBRELResource.java
    BREL 属性用に新しいレコードを作成する方法を示します。 このサンプルでは、既存の変更要求に新しいログ コメント アクティビティが追加されます。 BLREL 属性用に新しいレコードを作成する場合も、同じ方法を適用できます。
サンプル プログラムの作成と実行
サンプルの Java プログラムを作成および実行して、ユーザの環境内でテストすることができます。
以下の手順に従います。
  1. サンプル プログラムが存在するサブディレクトリに、rest_java_test.bat.txt (Windows の場合)または rest_java_test.sh.txt (UNIX の場合)をコピーします。
  2. 拡張子「.txt」を削除し、コピーしたファイルの名前を変更します。
  3. コピーしたファイルを編集し、最初の 3 つの SET 変数がユーザの CA SDM インストールに対して正しいことを確認します。
  4. 実行する Java ファイルを編集し、設定可能な変数がユーザの CA SDM インストールに対して正しく設定されていることを確認します。 ページ最上部のコメントを確認します。
CA SDM の認証方式
CA SDM の NX_ROOT/samples/sdk/rest/java ディレクトリには、サンプル コードがあります。 このディレクトリには、サンプル プログラムのコンパイルおよび実行方法の手順も格納されています。 REST Web サービスは、以下のセキュリティ認証スキームをサポートしています。
REST 秘密鍵認証
REST 秘密鍵認証は、カスタム化された、安全な HMAC メカニズムを使用します。 この認証方式により CA SDM では、ユーザのアイデンティティを検証し、リクエストが検証済み登録ユーザから送信されていることも検証できます。 この認証を正常に行うには、それぞれのリクエストで、リクエスト送信者のアイデンティティに関する情報が提供されている必要があります。
HMAC_ALGORITHM は、HmacSHA1、HmacSHA256、HmacSHA384、HmacSHA512、および HmacMD5 が有効な HMAC アルゴリズムをサポートしています。 デフォルトでは、REQUEST_METHOD、REQUEST_URI、および QUERY_STRING (存在する場合)がシグネチャの計算に使用されます。 また、date、x-obj-attrs、および content-typ などの他のヘッダ フィールドを使用してシグネチャを計算することもできます。 これらのフィールドを追加するには、NX.env ファイルで以下の NX 変数を 設定します。
@NX_STRING_TO_SIGN_FIELDS=date,x-obj-attrs,content-type
注:
クライアント側でシグネチャを計算する場合は、STRING_TO_SIGN_FIELDS オプションの場合と同じフィールドをまったく同じ順序で使用してください。
  • アクセス キー
    アクセス キーは、ログイン認証の成功後に CA SDM クライアントに割り当てられる値です。 リクエストは、アクセス キーを使用して、リクエスト元のクライアントを識別します。 ただし、アクセス キーはリクエスト パラメータとして送信されるため、保護されていません。 CA SDM にリクエストを送信することにより、誰でもアクセス キーを使用できるようになる可能性があります。 そのため、認証には秘密鍵が必要となります。 REST は、CA SDM のセッション ID をアクセス キーとして使用します。
  • 秘密鍵
    CA SDM に正常にログインすると、製品により秘密鍵とアクセス キーがクライアントに割り当てられます。 なりすましからユーザを保護するために、クライアントは、CA SDM がアイデンティティの確認用に使用する追加情報を提供する必要があります。 CA SDM は、REST アクセス キーの作成中に、40 文字の秘密鍵を自動的に生成します。
以下に認証手順を説明します。
  1. クライアントは、基本認証スタイルを使用してユーザ認証情報を SSL で提供し、REST URI (POST /caisd-rest/rest_access)によってアクセスキーと秘密鍵を取得します。
  2. それ以降の各 HTTP リクエストで、クライアントは秘密鍵を使用します。NX_STRING_TO_SIGN_FIELDS は、ヘッダ フィールド、NX_HMAC_ALGORITHM 変数は、ハッシュ関数を提供します。 この関数は、リクエスト シグネチャを計算します(HMAC: Keyed-Hash based Message Authentication Code )。
  3. クライアントは、リクエスト データ、シグネチャおよびアクセス キーを CA SDM に送信します。
  4. CA SDM は、アクセス キーを使用して、永続性ストアから秘密鍵をルックアップします。
  5. CA SDM は、リクエスト データと秘密鍵を使用して、シグネチャを生成します。この際、クライアントが使用したのと同じハッシュ アルゴリズムが使用されます。
  6. CA SDM が生成したシグネチャが、クライアントが送信したシグネチャと一致する場合、CA SDM は正規のリクエストと判断します。 それ以外の場合、CA SDM はリクエストを破棄し、エラーを返します。
REST BOPSID 認証
1 つのインターフェースを介して CA SDM にログインした後で、BOPSID トークンを使用して別のインターフェースから CA SDM にアクセスできます。 BOPSID トークンにより、起動したアプリケーションは、シングル サインオンなどのログインを必要とせずにユーザを認証できます。 CA SDM がユーザを認証した後、アプリケーションは boplgin から BOPSID を要求できます。 この使い捨てのトークンがユーザとセッションを識別します。 Boplgin は、BOPSID を受信すると、ユーザ ID とセッションを返します。 また、Boplgin は、トークンの作成から 5 分以内にリクエストの検証を受信しない場合、BOPSID をキャンセルします。
BOPSID トークンを渡すための HTTP メッセージ ヘッダの例を以下に示します。
POST /caisd-rest/rest_access HTTP/1.1 Host: hostname Date: Mon, 21 Apr 2012 19:37:58 +0000 X-BOPSID: <BOPSID token>
注:
REST Web サービスから BOPSID トークンを取得するには、/caisd-rest/bopsid に POST リクエストを送信します。
REST 基本認証
基本認証スキームでは、クライアントの認証情報にユーザ名とパスワードが含まれると仮定されています。パスワードは保護されており、クライアントとサーバしか知りません。
受信リクエストにクライアントの認証情報が含まれていない場合、サーバは認証のチャレンジを含む 401 応答を送り返します。 このチャレンジは "基本" トークンと、以下の例のような、保護領域名を指定する名前値のペアから構成されます
WWW-Authenticate: Basic realm="<USDK> 12.9"
サーバから 401 応答を受信すると、クライアント(ブラウザなど)は、その領域に関連付けられたユーザ名とパスワードの入力を求めます。 クライアント フォローアップ リクエストの認証ヘッダには "基本" トークンと、Base64 でエンコードされたユーザ名、パスワードおよびコロンのグループが含まれている必要があります。
POST /caisd-rest/rest_access HTTP/1.1 Host: hostname Date: Mon, 21 Apr 2012 19:37:58 +0000 Authorization: Basic QWRtaW46Zm9vYmFy
REST は base64 を使用して認証情報を複合し、ユーザ名/パスワードと比較し、boplgin によって認証情報を検証します。 検証が成功すると、サーバは要求されたリソースへのアクセスを許可します。
ユーザがユーザ名とパスワードの代わりに BOPSID を送信すると、 CA SDM は boplgin メソッドの validate_bopsid() を使用します。 基本認証スキームの使用に不安を感じる場合は、オプション マネージャ オプション NX_REST_WEBSERVICE_DISABLE_BASIC_AUTH を Yes に設定すれば無効にすることができます。
重要: 基本認証は秘密鍵方式ほど安全ではありません。 ただし、SSL 接続で基本認証を使用すれば、セキュリティを向上させることができます。
外部の CA EEM アーチファクト認証
REST リクエストに対して CA EEM アーチファクト認証を使用することができます。 クライアントは、事前定義済みの顧客ヘッダ(X-ExtAuthArtifact、X-UserName)を使用して、ユーザ名を持つ アーチファクトを送信します。 このヘッダ エントリが受信リクエストに表示されると、セキュリティ インターセプタは boplgin に VALIDATE_ARTIFACT メッセージを送信して、ログインの検証を行います。
CA EEM アーチファクトの使用例を以下に示します。
POST /caisd-rest/rest_access HTTP/1.1 Host: hostname Date: Mon, 21 Apr 2012 19:37:58 +0000 X-ExtAuthArtifact: <EEM Artifact token> X-UserName: <username>
チケットに対する CRUD 操作
REST API は、ユーザが REST API を使用してチケットを処理できるように Java のサンプル コードを提供しています。 これらのファイルには以下の操作が含まれます。
  • ハードコードされたサンプル データで変更要求を作成する。
  • 最近作成された変更要求をステータス更新により更新する。
  • インシデントを作成し、コンソール上にインシデント番号を表示する。
  • Where 節を使用してインシデント番号のリストを取得し、コンソール上に表示する。
BREL、QREL および BLREL の処理
REST API は、ユーザが REST API の BREL および QREL 属性を使用してチケットを処理できるように Java のサンプル コードを提供しています。 BREL、QREL および BLREL 属性は、GET 操作のみサポートしています。 ファイルには以下の操作が含まれます。
  • ドキュメント化された複数ステップのプロセスを使用して BREL を作成します。 たとえば、変更要求にアクティビティ ログを追加します。 QREL の場合は、ある変更要求の子として複数の変更要求を作成します。 BLREL の場合は、複数の構成アイテムを変更要求に追加します。
  • BREL、QREL または BLREL 属性の URI を返す属性のリストを取得し、コンソール上に表示します。
  • URI で BREL、QREL または BLREL 属性のコレクションを取得し、コンソール上に表示します。 例: /caisd-rest/chg/40001/act_log
チケット用添付ファイルの管理
REST API は、ユーザが REST API を使用してチケットを処理できるように Java のサンプル コードを提供しています。 ファイルには以下の操作が含まれます。
  • インシデントを作成します。
  • 添付ファイルを作成する。
  • 添付ファイルをインシデントに追加する(2 ステップ)。
  • 添付ファイル付きのインシデントを作成する(1 ステップ)。
  • インシデントから添付ファイルを削除する。
  • 添付ファイルのダウンロード
    添付ファイルをダウンロードするには、以下の手順に従います。
    1. ファイルをダウンロードするには、以下の HTTP リクエストを発行します。
      GET /caisd-rest/attmnt/<attmnt id>/file-resource
      ここで、「file resource」はプレーン テキストです。
      たとえば、添付ファイル レコード 400015 に関連付けられているファイルをダウンロードするには、以下のリクエストを発行します。
      GET /caisd-rest/attmnt/400015/file-resource
      ファイル ダウンロードの応答コンテンツ タイプは
      application/octet-stream です。
      Apache Commons HTTP Client などのクライアントでは、このコンテンツ タイプは簡単に操作することができます。 Apache Commons HTTP Client を使用した完全な作業のサンプルについては、
      NX_ROOT\samples\sdk\rest\java\test3_attachments
      ディレクトリにある
      SampleDownloadAttachment.java
      ファイルを確認します。
CA SDM のリソースの例
例では、REST API が Create、Read、Update および Delete (CRUD)の基本的な HTTP 操作を CA SDM オブジェクトに対してどのように使用するかを示します。 例を使用すると、REST 操作がすべての CA SDM オブジェクトに対して同じように動作することを理解できます。
読みやすくするために、例ではすべての HTTP メッセージ ヘッダは表示せず、関連する情報のみ示しています。
例: 添付ファイル付きの変更リクエストの作成
この REST API 例では、変更要求チケットと添付ファイルを作成する複雑な使用例が示されます。
MIME タイプの「application/xml」と「text/xml」は置き換え可能です。 「application/xml」を使用することをお勧めします。 text/*-MIME タイプの文字は、HTTP ヘッダで特に明記されていない限り、us-ascii 文字です。 実際、XML プロローグ(<?xml version=”1.0” encoding=”UTF-8”?> など)で定義されているエンコーディングは無視されます。
以下の例は、リクエストを示しています。
POST /caisd-rest/chg/?repositoryId=1002&AttachmentId=att1&serverName=HOSTNAME&mimeType=doc&description=Desc HTTP/1.1 Content-Type: multipart/form-data X-AccessKey: 51461077 User-Agent: Jakarta Commons-HttpClient/3.0.1 Host: hostname:8050 Content-Length: 1045 --Vschb1Sy2JD93ODUnWVAkRxp3IoXIMgXd Content-Disposition: form-data; name="chg" Content-Type: application/xml; charset=US-ASCII Content-Transfer-Encoding: 8bit <chg><description>Attachments Testing</description><status COMMON_NAME="RFC" REL_ATTR="RFC" id="40020"><link rel="self" href="http://hostname:8050/caisd-rest/chgstat/40020"/></status><summary>Attachment test</summary><requestor COMMON_NAME="ServiceDesk" REL_ATTR="U'279B25DD051D0A47B54880D86700397F'" id="U'279B25DD051D0A47B54880D86700397F'"><link rel="self" href="http://hostname:8050/caisd-rest/cnt/U'279B25DD051D0A47B54880D86700397F'"/></requestor></chg> --Vschb1Sy2JD93ODUnWVAkRxp3IoXIMgXd Content-Disposition: form-data; name="Test.txt"; filename="Test.txt" Content-Type: application/octet-stream; charset=ISO-8859-1 Content-Transfer-Encoding: binary
以下の例は、応答を示しています。
HTTP/1.1 201 Created Content-Type: application/xml;charset=UTF-8 Location: http://hostname:8050/caisd-rest/chg/400202 <chg id="400202" REL_ATTR="400202" COMMON_NAME="1047"> <link href="http://hostname:8050/caisd-rest/chg/400202" rel="self"/> </chg>
例: リソースの作成
この REST API の例では、リソースの作成方法を示します。 この例では、REST API は変更要求チケットを作成します。
以下の例は、リクエストを示しています。
POST /caisd-rest/chg HTTP/1.1 Host: hostname Accept: application/xml Content-Type: application/xml;charset=UTF-8 X-Obj-Attrs: chg_ref_num <chg> <summary>Created via REST API</summary> <requestor REL_ATTR="U'793ED69B4E87A545BD8E911834D829FC'"/> </chg>
以下の例は、応答を示しています。
HTTP/1.1 201 Created Content-Type: application/xml;charset=UTF-8 Location: http://hostname:8050/caisd-rest/chg/400001 <?xml version="1.0" encoding="UTF-8"?> <chg id="400003" REL_ATTR="400003" COMMON_NAME="23"> <link href="http://hostname:8050/caisd-rest/chg/400003" rel="self"/> <chg_ref_num>23</chg_ref_num> </chg>
例: リソースの削除
この REST API の例では、リソースの削除方法を示します。
削除できないオブジェクトもあります。 ほとんどのオブジェクトでは、delete_flag の true/false への更新、または、ステータスのアクティブ/非アクティブへの更新のみサポートされています。 これらのアクションを実行する場合、DELETE リクエストではなく UPDATE リクエストを使用します。
以下の例は、リクエストを示しています。
DELETE /caisd-rest/grpmem/400001 HTTP/1.1 Host: hostname
以下の例は、応答を示しています。
HTTP/1.1 204 No Content Content-Type: application/xml;charset=UTF-8 Content-Length: 0
例: アクセス キーの削除
この REST API の例では、CA SDM のアクセス キーの削除方法を示します。
以下の例は、リクエストを示しています。
DELETE /caisd-rest/rest_access/1201703106 HTTP/1.1 Host: hostname
以下の例は、応答を示しています。
HTTP/1.1 204 No Content Content-Type: application/xml;charset=UTF-8 Content-Length: 0
例: リソースを非アクティブとしてマーク
この REST API の例では、リソースを非アクティブとしてマークする方法を示します。
大半の CA SDM オブジェクトでは、非アクティブにマークすることのみがサポートされており、実際に削除することはできません。
以下の例は、リクエストを示しています。
PUT /caisd-rest/loc/U'0502D608F9122B48B7C9DAB9E0457F94' HTTP/1.1 Host: hostname Content-Type: application/xml;charset=UTF-8 X-Obj-Attrs: delete_flag <loc id="U'0502D608F9122B48B7C9DAB9E0457F94'"> <delete_flag COMMON_NAME="Inactive"/> </loc>
以下の例は、応答を示しています。
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <loc id="U'0502D608F9122B48B7C9DAB9E0457F94'" REL_ATTR="U'0502D608F9122B48B7C9DAB9E0457F94'" COMMON_NAME="Stadium 1"> <link href="http://hostname:8050/caisd-rest/loc/U'0502D608F9122B48B7C9DAB9E0457F94'" rel="self"/> <delete_flag id="4552" REL_ATTR="1" COMMON_NAME="Inactive"> <link href="http://hostname:8050/caisd-rest/actbool/4552" rel="self"/> </delete_flag> </loc>
例: BOPSID トークンの取得
BOPSID トークンはシングル サインオン機能を提供する、使い捨ての認証トークンです。 この REST API の例では、Web クライアントへのログインに使用するために BOPSID トークンを取得する方法を示します。
以下の例は、リクエストを示しています。
POST /caisd-rest/bopsid HTTP/1.1 Host: hostname.ca.com Accept: application/xml <bopsid/>
以下の例は、応答を示しています。
HTTP/1.1 201 OK Content-Type: application/xml;charset=UTF-8 <bopsid> <bopsid_val>987982618</bopsid_val> </bopsid>
例: アクセス キーの取得
この REST API 例では、ユーザ ID 「ServiceDesk」用にアクセス キー(ログイン)を取得する方法を示します。 認証されていないユーザから秘密鍵を盗まれないようにするため、この操作は、SSL を使用して行います。 force_unique_userid オプション マネージャ オプションを常に有効にしてください。 このオプションが無効にされた状態で、同じログイン ID を持つ複数の連絡先レコードが存在すると、データ パーティション、マルチテナンシー、セキュリティおよび他の機能に関する問題が発生する場合があります。
以下の例は、リクエストを示しています。
POST /caisd-rest/rest_access HTTP/1.1 Host: hostname Content-Type: application/xml;charset=UTF-8 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== <rest_access/>
以下の例は、応答を示しています。
HTTP/1.1 201 Created Content-Type: application/xml <?xml version="1.0" encoding="UTF-8"?> <rest_access id="400001" REL_ATTR="400001" COMMON_NAME="770921656"> <link href="http://hostname:8050/caisd-rest/rest_access/400001" rel="self"/> <access_key>770921656</access_key> <expiration_date>1335276895</expiration_date> </rest_access>
例: リソース コレクションの取得
この REST API 例では、リソース コレクションの取得方法を示します。 この例では、REST API は、すべての変更要求チケット オブジェクトのコレクションを取得します。
ルート ノード(collection_chg など)には、リストのナビゲートに使用される「previous (前へ)」、「next (次へ)」、「all (すべて)」などのリンク エレメントも存在します。
以下の例は、リクエストを示しています。
GET /caisd-rest/chg HTTP/1.1 Host: hostname Accept: application/xml
以下の例は、応答を示しています。
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <collection_chg> <chg id="400001" REL_ATTR="400001" COMMON_NAME="21"> <link href="http://hostname:8050/caisd-rest/chg/400001" rel="self"/> </chg> <chg id="400002" REL_ATTR="400002" COMMON_NAME="22"> <link href="http://hostname:8050/caisd-rest/chg/400002" rel="self"/> </chg> </collection_chg>
例: Where 節を使用したリソース コレクションの取得
この REST API 例では、Where 節を使用した、リソース コレクションの取得方法を示します。 この例で、REST API は、「クローズ」ステータスのすべてのリクエスト(cr)チケット オブジェクトのコレクションを取得します。
BREL クエリがサポートされています。
以下はリクエストの例です。
GET /caisd-rest/cr?WC=status%3D'cl' GET /caisd-rest/cr?WC=status%3D'op'%20and%20active%3D0 Host: hostname Accept: application/xml X-Obj-Attrs: ref_num, priority
以下の例は、応答を示しています。
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <collection_cr COUNT="3" TOTAL_COUNT="3"> <cr id="2903" REL_ATTR="cr:2903" COMMON_NAME="AM:12"> <link href="http://hostname:8050/caisd-rest/cr/2903" rel="self"/> <priority id="502" REL_ATTR="3" COMMON_NAME="3"> <link href="http://hostname:8050/caisd-rest/pri/502" rel="self"/> </priority> <ref_num>AM:12</ref_num> </cr> <cr id="2907" REL_ATTR="cr:2907" COMMON_NAME="AM:14"> <link href="http://hostname:8050/caisd-rest/cr/2907" rel="self"/> <priority id="502" REL_ATTR="3" COMMON_NAME="3"> <link href="http://hostname:8050/caisd-rest/pri/502" rel="self"/> </priority> <ref_num>AM:14</ref_num> </cr> <cr id="3105" REL_ATTR="cr:3105" COMMON_NAME="UAPM:13"> <link href="http://hostname:8050/caisd-rest/cr/3105" rel="self"/> <priority id="502" REL_ATTR="3" COMMON_NAME="3"> <link href="http://hostname:8050/caisd-rest/pri/502" rel="self"/> </priority> <ref_num>UAPM:13</ref_num> </cr> </collection_cr>
例: 特定リソースの取得
この REST API 例では、ID、COMMON_NAME または REL_ATTR を使用して、特定のリソースを取得する方法を示します。 この例で、REST API は、一意の変更要求チケット オブジェクト ID 400001 の詳細を取得します。
以下は、ID を使用したリクエストの例です。
GET /caisd-rest/chg/400001 HTTP/1.1 Host: hostname.ca.com Accept: application/xml X-Obj-Attrs: chg_ref_num, summary, requestor, status
以下は、COMMON_NAME を使用したリクエストの例です。
GET /caisd-rest/chg/COMMON_NAME-32 HTTP/1.1
以下は、REL_ATTR を使用したリクエストの例です。
GET /caisd-rest/chg/REL_ATTR-chg:400001 HTTP/1.1
以下の例は、応答を示しています。
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <chg id="400001" REL_ATTR="400001" COMMON_NAME="21"> <link href="http://hostname:8050/caisd-rest/chg/400001" rel="self"/> <chg_ref_num>21</chg_ref_num> <requestor id="U'793ED69B4E87A545BD8E911834D829FC'" REL_ATTR="U'793ED69B4E87A545BD8E911834D829FC'" COMMON_NAME="System_AHD_generated"> <link href="http://hostname:8050/caisd-rest/cnt/U'793ED69B4E87A545BD8E911834D829FC'" rel="self"/> </requestor> <status id="40020" REL_ATTR="RFC" COMMON_NAME="RFC"> <link href="http://hostname:8050/caisd-rest/chgstat/40020" rel="self"/> </status> <summary>Testing</summary>
例: サブリソースの取得
この REST API の例では、サブリソースの取得方法を示します。
以下の例は、リクエストを示しています。
GET /caisd-rest/chg/400001/status HTTP/1.1 Host: hostname Accept: application/xml X-Obj-Attrs: code, sym, description HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <chgstat id="40020" REL_ATTR="RFC" COMMON_NAME="RFC"> <link href="http://hostname:8050/caisd-rest/chgstat/40020" rel="self"/> <code>RFC</code> <description>Request for Change is in draft form</description> <sym>RFC</sym> </chgstat>
例: リソースの更新
この REST API の例では、リソースの更新方法を示します。 この例で、REST API は、変更要求チケット ID 400003 の概要フィールドを更新します。
以下の例は、リクエストを示しています。
PUT /caisd-rest/chg/400003 HTTP/1.1 Host: hostname Content-Type: application/xml;charset=UTF-8 X-Obj-Attrs: chg_ref_num, summary <chg id="400003"> <summary>Summary updated via REST API</summary> </chg>
以下の例は、応答を示しています。
HTTP/1.1 200 OK Content-Type: application/xml <?xml version="1.0" encoding="UTF-8"?> <chg id="400003" REL_ATTR="400003" COMMON_NAME="23"> <link href="http://hostname:8050/caisd-rest/chg/400003" rel="self"/> <chg_ref_num>23</chg_ref_num> <summary>Summary updated via REST API</summary> </chg>
例: BLREL レコードの取得
この例では、BLREL レコードの取得方法を示します。
以下の例は、リクエストを示しています。
GET /caisd-rest/grpmem HTTP/1.1 Host: localhost Accept: application/xml X-Obj-Attrs: *
以下の例は、応答を示しています。
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <collection_grpmem COUNT="3" START="1" TOTAL_COUNT="3"> <grpmem id="400001" REL_ATTR="grpmem:400001" COMMON_NAME="400001"> <link href="http://localhost:8050/caisd-rest/grpmem/400001" rel="self"/> <group id="U'CFCC2DC94B3A66448C085B07E7286CAA'" REL_ATTR="U'CFCC2DC94B3A66448C085B07E7286CAA'" COMMON_NAME="Unicef"> <link href="http://localhost:8050/caisd-rest/grp/U'CFCC2DC94B3A66448C085B07E7286CAA'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'3F05B7450203AD449BFB8088D991A03E'" REL_ATTR="U'3F05B7450203AD449BFB8088D991A03E'" COMMON_NAME="System_SD_User"> <link href="http://localhost:8050/caisd-rest/cnt/U'3F05B7450203AD449BFB8088D991A03E'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400001</persistent_id> <producer_id>grpmem</producer_id> </grpmem> <grpmem id="400002" REL_ATTR="grpmem:400002" COMMON_NAME="400002"> <link href="http://localhost:8050/caisd-rest/grpmem/400002" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://localhost:8050/caisd-rest/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'FCF9A8AC6381AA4386C9B10EE382E10B'" REL_ATTR="U'FCF9A8AC6381AA4386C9B10EE382E10B'" COMMON_NAME="System_MA_User"> <link href="http://localhost:8050/caisd-rest/cnt/U'FCF9A8AC6381AA4386C9B10EE382E10B'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400002</persistent_id> <producer_id>grpmem</producer_id> </grpmem> <grpmem id="400003" REL_ATTR="grpmem:400003" COMMON_NAME="400003"> <link href="http://localhost:8050/caisd-rest/grpmem/400003" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://localhost:8050/caisd-rest/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'16226C765005B94E957E0F477DEF1B1C'" REL_ATTR="U'16226C765005B94E957E0F477DEF1B1C'" COMMON_NAME="System_AM_User"> <link href="http://localhost:8050/caisd-rest/cnt/U'16226C765005B94E957E0F477DEF1B1C'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400003</persistent_id> <producer_id>grpmem</producer_id> </grpmem> </collection_grpmem>
このサンプルは、以下の関連付けを表現する 3 つの grpmem レコードを返します。
  • グループ Unicef <-> メンバ System_SD_User
  • グループ Apache <-> メンバ System_MA_User
  • グループ Apache <-> メンバ System_AM_User
例: グループと関連付けられた LREL レコードのリストの取得
以下の例は、REL_ATTR 値が U'55E3CCE805756B4F8084D63E05E6C216' である グループ Apache と関連付けられた 2 つの grpmem レコードを返します。 以下の点に注意してください。
  • グループ Apache <-> メンバ System_MA_User
  • グループ Apache <-> メンバ System_AM_User
以下の例は、リクエストを示しています。
GET /caisd-rest/grpmem?WC=group%3DU%2755E3CCE805756B4F8084D63E05E6C216%27 HTTP/1.1 Host: hostname Accept: application/xml X-Obj-Attrs: *
以下の例は、応答を示しています。
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <collection_grpmem COUNT="2" START="1" TOTAL_COUNT="2"> <grpmem id="400002" REL_ATTR="grpmem:400002" COMMON_NAME="400002"> <link href="http://hostname:8050/caisd-rest/grpmem/400002" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://hostname:8050/caisd-rest/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'FCF9A8AC6381AA4386C9B10EE382E10B'" REL_ATTR="U'FCF9A8AC6381AA4386C9B10EE382E10B'" COMMON_NAME="System_MA_User"> <link href="http://hostname:8050/caisd-rest/cnt/U'FCF9A8AC6381AA4386C9B10EE382E10B'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400002</persistent_id> <producer_id>grpmem</producer_id> </grpmem> <grpmem id="400003" REL_ATTR="grpmem:400003" COMMON_NAME="400003"> <link href="http://hostname:8050/caisd-rest/grpmem/400003" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://hostname:8050/caisd-rest/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'16226C765005B94E957E0F477DEF1B1C'" REL_ATTR="U'16226C765005B94E957E0F477DEF1B1C'" COMMON_NAME="System_AM_User"> <link href="http://hostname:8050/caisd-rest/cnt/U'16226C765005B94E957E0F477DEF1B1C'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400003</persistent_id> <producer_id>grpmem</producer_id> </grpmem> </collection_grpmem>
例: BLREL レコードの作成
以下の例では、既存の連絡先 System_SA_User をグループ Apache のメンバとして追加します。 各レコードの COMMON_NAME 値を使用します。
グループ Apache <-> メンバ System_SA_User
以下の例は、リクエストを示しています。
POST /caisd-rest/grpmem HTTP/1.1 Host: hostname Accept: application/xml Content-Type: application/xml;charset=UTF-8 X-Obj-Attrs: * <grpmem> <group id="U'55E3CCE805756B4F8084D63E05E6C216'"/> <manager_flag>0</manager_flag> <member id="U'E70DFE4817614C06BE9E5991A96A6015'"/> <notify_flag>1</notify_flag> </grpmem>
以下の例は、応答を示しています。
HTTP/1.1 201 Created Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <grpmem id="400005" REL_ATTR="grpmem:400005" COMMON_NAME="400005"> <link href="http://hostname:8050/caisd-rest3/grpmem/400005" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://hostname:8050/caisd-rest3/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'E70DFE4817614C06BE9E5991A96A6015'" REL_ATTR="U'E70DFE4817614C06BE9E5991A96A6015'" COMMON_NAME="System_SA_User"> <link href="http://hostname:8050/caisd-rest3/cnt/U'E70DFE4817614C06BE9E5991A96A6015'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400005</persistent_id> <producer_id>grpmem</producer_id> </grpmem>
例: BLREL レコードの更新
以下の例では、追加されたレコードの関係を更新し、メンバ System_SA_User をマネージャとして設定します。
以下の例は、リクエストを示しています。
PUT /caisd-rest/grpmem/400005 HTTP/1.1 Host: hostname Accept: application/xml Content-Type: application/xml;charset=UTF-8 X-Obj-Attrs: * <grpmem> <manager_flag>1</manager_flag> </grpmem>
以下の例は、応答を示しています。
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <grpmem id="400005" REL_ATTR="grpmem:400005" COMMON_NAME="400005"> <link href="http://hostname:8050/caisd-rest3/grpmem/400005" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://hostname:8050/caisd-rest3/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>1</manager_flag> <member id="U'E70DFE4817614C06BE9E5991A96A6015'" REL_ATTR="U'E70DFE4817614C06BE9E5991A96A6015'" COMMON_NAME="System_SA_User"> <link href="http://hostname:8050/caisd-rest3/cnt/U'E70DFE4817614C06BE9E5991A96A6015'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400005</persistent_id> <producer_id>grpmem</producer_id> </grpmem>
例: BLREL レコードの削除
以下の例では、グループ Apache からメンバ System_MA_User を削除します。 この例ではメンバ レコードおよびグループ レコードは削除されません。 削除されるのは両者の関連付けのみです。 grpmem レコードは物理的に削除されます。
以下の例は、リクエストを示しています。
DELETE /caisd-rest/grpmem/400002 HTTP/1.1 Host: hostname
以下の例は、応答を示しています。
HTTP/1.1 204 No Content Content-Type: application/xml;charset=UTF-8 Content-Length: 0
Additional REST API settings can be configured via web deployment descriptor web.xml file. File $NX_ROOT\site\rest\web.xml.tpl is provided as a template and should not be modified. On first run, SDM will create a new file web.xml from template into the same directory. Users can modify this file, which will be included in the WAR file to be deployed. Updating Servlet Configuration Parameters To make updates, perform the following steps: * Shutdown SDM * Open file $NX_ROOT/site/rest/web.xml for editing * Find the parameter to be updated inside <param-name> tag * Carefully update the value inside corresponding <param-value> tag * Save file * Startup SDM If for any reason, REST Tomcat fails to start or reports errors due to the above changes, you can start fresh by creating a new web.xml file from template $NX_ROOT/site/rest/web.xml.tpl. Available Parameters ExternalBaseURI This optional setting allows you to provide a custom REST API address for hyperlinks included in the response body. This is useful for sites that have load balancers, reverse proxy servers, external hostnames, https addresses, etc. Make sure the REST API web app name such as “caisd-rest” is included in this value. The sample default value is http://host:8050/caisd-rest