概要
シスコは、Cisco Service Portal（Service Portal）に定義されているエンティティにアクセスするための、標準的な REST（Representational State Transfer）の API および Java スタブを一式提供しています。これらは、まとめて nsAPI と呼ばれます。
nsAPI では、組み込みのセッション サポートを使用して認証が行われます。エンティティに対するアクセス権限は、Service Portal アプリケーションでユーザに対して定義されたロールベース アクセス コントロール（RBAC）のオブジェクト レベル権限によって制御されます。
nsAPI を使用すると、外部アプリケーションおよび Portal Manager ソリューションとの統合が可能です。ポータル機能は、Java、JavaScript、HTML や Ext JS を使用して作成されたポートレットの設計およびレンダリング、つまり、ポータルの UI フレームワークをサポートしています。このようなポートレットの中で nsAPI を呼び出すことによって、必要なエンティティの情報を取得し、特定のタイプのエンティティのデータを更新可能にすることができます。ポータル モジュールの詳細については、『 Cisco Service Portal Designer Guide 』に説明があります。
サポートされるエンティティ
nsAPI でサポートされるエンティティは、次のカテゴリに分けられます。
|
|
|
定義データ |
カテゴリ サービス 提供サービス エージェント |
ディレクトリ データ |
組織単位 個人 グループ アカウント |
トランザクション データ |
契約 要求 要求エントリ 承認 タスク |
Lifecycle Center データ |
サービス項目の詳細 すべてのサービス項目 標準 |
Portal Designer データ |
コンテンツのカスタマイズ テーブル |
操作
次のタイプの操作が、nsAPI でサポートされています。
•
Service Portal アプリケーションに事前定義されているコア エンティティに対する HTTP GET 操作
• Lifecycle Center および Portal Designer のユーザ定義エンティティに対する HTTP GET 操作
• 次の特定のエンティティに対する HTTP POST 操作
– 個人：個人の作成、個人の詳細情報の更新
– タスク：タスクのアクション（完了/許可/拒否/確認）の実行
GET 操作とは、指定されたエンティティのデータを取得する操作であり、PUT 操作では、エンティティの詳細情報またはステータスに変更を加えることができます。操作を呼び出したユーザは、操作対象のエンティティ インスタンスに対して必要な読み取り権限または書き込み権限を持っている必要があります。
規約と構文
• REST の URL は次の規則に従います。
http(s)://<serverURL>/RequestCenter/nsapi/<entityGroup>/<entityType>/<filters>?sortBy=<columnName>&sortDir=<sortOrder>?startRow=<x>&recordSize=<y>
山カッコ（<>）で囲まれている要素は、適切なパラメータまたはパラメータ値に置換する必要があることを示しています。
• フィルタ、ソート、およびページングのコントロールとアクションは、オプション パラメータとして REST URL に渡されます。フィルタには、「フィルタ」の項で説明するように、1 つまたは複数の式を含めることができます。フィルタを指定しなかった場合は、エンティティに関して見つかったすべてのインスタンスが返されます。
• 複数のフィルタの組み合わせが可能なこともあります。その場合、2 番め以降のパラメータの指定はオプションです。このようなパラメータについては、構文内でそのパラメータ構文を角カッコ（[]）で囲むことによって示しています。オプションのパラメータは、区切り文字（|）で囲む必要があります。
• 特記のない限り、すべての URL で大文字と小文字が区別されます。
• nsAPI にはバージョン機能が組み込まれています。ベース バージョン 1.0 の REST URL にはバージョン番号を表すパラメータがありません。しかし、これは将来のリリースで変更される可能性があります。
• 要求された操作が成功したのか、それとも失敗したのかを示すために、HTTP のステータス コードおよびエラー メッセージが REST 応答で返されます。
• nsAPI Java バインディング パッケージの名前は com.newscale.nsapi.* です。
フィルタ
nsAPI は、次のように GET 操作においてエンティティのタイプに基づき多様なフィルタをサポートしています。
|
|
|
|
| すべてのエンティティ |
Id /id/<value> |
http://serverURL/RequestCenter/nsapi/definition/servicedefs/id/16 |
名前：完全一致 /name/<value> |
http://serverURL/RequestCenter/nsapi/definition/servicedefs/name/Create%20Custom%20VM |
名前：ワイルドカード検索 ?name=<value> |
http://serverURL/RequestCenter/nsapi/definition/servicedefs?name=Create%20Custom* |
標準、サービス項目、カスタム コンテンツ |
すべてのテーブルのカラム。次の要素で構成されたフィルタ式を最大 3 つ使用可能 • 比較演算子：=、>、<、>=、<= • 関係演算子：AND、OR（大文字小文字の区別あり） • 区切り文字：| /<columnName1><operator1><value1>[|<AND|OR>|]<columnName2><operator2><value2>][|<AND|OR>|<columnName3><operator3><value3>] 日付フィールドの値は mm-dd-yyyy 形式にする必要があります。 |
http://serverURL/RequestCenter/nsapi/standard/StOperatingSystem/Custom1=Linux|AND|Custom2=64 これは、次のように記述することもできます。 http://serverURL/RequestCenter/nsapi/standard/StOperatingSystem/Custom1=Linux|Custom2=64 http://serverURL/RequestCenter/nsapi/standard/StOperatingSystem/Custom1=Linux|OR|Custom2=64 http://serverURL/RequestCenter/nsapi/serviceitems/serviceitemsubscription/SubmitDate>=03-01-2011 http://serverURL/RequestCenter/nsapi/customcontent/UcAnnouncementObj/Category=Corporate |
サービス項目 |
ビュー名 ?View Name=<value> 指定可能なビュー名は次のとおりです。
My ServiceItems（My Services に表示されるもの）
Manage ServiceItems（Service Item Manager に表示されるもの） |
http://serverURL/RequestCenter/nsapi/serviceitem/SiDesktop?View%20Name=My%20ServiceItems http://serverURL/RequestCenter/nsapi/serviceitem/SiDesktop?View%20Name=Manage%20ServiceItems |
組織単位 |
OU のタイプ ?type=<all/businessUnit/serviceTeam> |
http://serverURL/RequestCenter/nsapi/directory/organizationalunits?type=serviceTeam |
| 個人 |
ログイン名 ?loginname/<value> |
http://serverURL/RequestCenter/nsapi/directory/people?loginname/dsmith |
OU 名 ?ouname=<value> |
http://serverURL/RequestCenter/nsapi/directory/people?ouname=Operations |
グループ名 ?groupname=<value> |
http://serverURL/RequestCenter/nsapi/directory/people?groupname=Approvers |
ロール名 ?rolename=<value> 継承されたロールをフィルタに使用することはできません。 |
http://serverURL/RequestCenter/nsapi/directory/people?rolename=Service%20Performer |
カテゴリ |
カテゴリ タイプ ?catalogType=<serviceCatalog/offeringCatalog> |
http://serverURL/RequestCenter/nsapi/definition/categories?catalogType=serviceCatalog |
| サービス |
カテゴリ名 ?categoryName=<value> |
http://serverURL/RequestCenter/nsapi/definition/servicedefs?categoryName=Manage%20Physical%20Servers |
キーワード ?keywordName=<value> |
http://serverURL/RequestCenter/nsapi/definition/servicedefs?keywordName=server |
要求および承認 |
ビュー名、ステータス /ViewName=<value1>[| Status=<value2>] フィルタに使用可能なビュー名は、My Services の [Requisitions] タブおよび [Authorizations] タブにあるビューのリストに対応しています。 ステータス フィルタは、ビュー名フィルタと組み合わせて使用する必要があります。ステータス フィルタ単独で使用することはできません。 |
http://serverURL/RequestCenter/nsapi/transaction/requisitions/ViewName=Ordered%20for%20Self http://serverURL/RequestCenter/nsapi/transaction/authorizations/ViewName=Authorizations%20for%20Self http://serverURL/RequestCenter/nsapi/transaction/authorizations/ViewName=Authorizations%20for%20Self| Status=Approved |
タスク |
ビュー名 ?viewName=<value> フィルタに使用可能なビュー名は、Service Manager のシステム定義ビューのリストに対応しています。ユーザ定義ビューをフィルタに使用することはできません。 |
http://serverURL/RequestCenter/nsapi/transaction/tasks?viewName=AvailableWork |
タスク（特定の要求エントリに関するもの） |
タスク タイプ ?taskType=<value> 指定可能なタスクのタイプ：all、delivery、authorization タスク ステータス（Skipped） ?showSkippedTasks=<false|true> |
http://<ServerURL>/RequestCenter/nsapi/transaction/tasks/RequisitionEntryNumber=1234?taskType=delivery&showSkippedTasks=true |
POST 操作では、次のフィルタがサポートされています。
|
|
|
|
個人 |
ログイン名または Id フィルタは操作の中で暗黙的に行われ、個人の識別情報が要求 XML から取得されます。 |
http://serverURL/RequestCenter/nsapi/directory/people/update 作成アクションおよび更新アクションの両方で、この同じ URL が使用されます。個人の属性を URL に渡す必要はありません。 |
タスク |
Id /<value>/<done |approve |reject | review> 「|」は、指定可能なオプションの 1 つだけを選択する必要があることを示しています。 |
http://serverURL/RequestCenter/nsapi/transaction/tasks/215/approve |
名前検索について
エンティティの名前フィルタでワイルドカード検索を行う場合（例：?name=<value>）、検索文字列の先頭のワイルドカード（「*」や「%」）は無視されます。これらの文字が文字列の中または末尾にある場合は、ワイルドカード照合で適用されます。
名前検索において先頭のワイルドカード文字を有効にするには、newscale.properties ファイル（RequestCenter.ear¥config にあります）内のプロパティ ContainsQueryInFnS を見つけ、次のように値を true に設定してください。
このプロパティは、Service Manager および Service Link モジュールにおけるワイルドカード検索サポートもすべて制御します。 このような検索操作は、システムのパフォーマンスに悪影響を及ぼす可能性があるため、一般的には実稼働環境での使用は推奨されません 。
関連付けられているエンティティとは、プライマリ エンティティと一緒に取得される、ネストされたエンティティのことです。たとえば、個人がメンバとして属している OU などがあります。関連付けられているエンティティの名前フィルタでは、ワイルドカード検索はサポートされません。このようなフィルタによる検索では、完全一致の結果のみが返されます。また、大文字小文字が区別されます。つまり、検索文字列内のワイルドカード文字は、照合の際にリテラルとして扱われます。次に例を示します。
/nsapi/directory/people?ouname=star*OU
文字どおり「star*OU」という名前の組織単位に含まれている人が返されます。
/nsapi/directory/people?groupname=starGroup*
文字どおり「starGroup*」という名前のグループに含まれている人が返されます。
ソート
複数のデータ行を返す操作では、ソート コントロールを使用できます。フィルタと同様、ソート コントロールも次のように REST URL 内にパラメータとして指定します。
?sortBy=<columnName>&sortDir=<sortOrder>
• sortBy：ソート基準として使用するフィールドの名前。
• sortDir：ソートの方向。指定可能な値は asc（昇順）と desc（降順）です。
ソート パラメータが REST URL に渡されなかった場合は、次の表に示すように、デフォルトのソート フィールドとソート順序が使用されます。
|
|
|
カテゴリ |
Name（昇順） |
サービス |
Name（昇順） |
提供 |
Name（昇順） |
エージェント |
Name（昇順） |
人 |
First Name（昇順） |
組織単位 |
Name（昇順） |
グループ |
Name（昇順） |
アカウント |
Name（昇順） |
すべてのサービス項目 |
Row Id*（昇順） |
サービス項目の詳細 |
Row Id*（昇順） |
標準 |
Row Id*（昇順） |
カスタム コンテンツ |
Row Id*（昇順） |
要求 |
Submit Date（昇順）、Requisition Id（昇順） |
要求エントリ |
Requisition Entry ID（昇順） |
タスク |
Task Name（昇順）、Task Id（昇順） |
承認 |
Requisition Id（昇順）、Task Id（昇順） |
契約 |
Agreement Name（昇順） |
Row Id とは、サービス項目、標準、およびカスタム コンテンツ テーブルにレコードが挿入された物理的な順序を表します。これは、それらの各テーブルの PrimaryID というカラムに対応しています。
サービス項目、標準、およびカスタム コンテンツの各エンティティは、すべてのカラムでソートできます。他のエンティティは、特定のフィールドによるソートだけがサポートされています。詳細については、「詳細な API リファレンス」を参照してください。
例
/nsapi/directory/people?sortBy=lastName&sortDir=asc
個人レコードが、姓の昇順にリストされて返されます。
/nsapi/directory/people?sortBy=login&sortDir=desc
個人レコードが、ログイン名の降順にリストされて返されます。
ページング
複数のデータ行を返す操作では、ページ コントロールを使用できます。これらも次のように REST URL 内にパラメータとして指定します。
?startRow=<x>&recordSize=<y>
• startRow：レコードの取得を開始する行。デフォルト値は 1 です。
• recordSize：一度に取得するレコード数。デフォルト値は Portal Designer の共通設定で設定されます。許容最大レコード数は 50 です。
上記の各パラメータおよび返されるレコードの総数が、REST XML 応答のルート タグ内に属性として示されます。次に例を示します。
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<categories totalCount="11" recordSize="10" startRow="1">
<categoryId>1</categoryId>
<categoryName><b>Consumer Services</b></categoryName>
取得されるレコード数よりも多い数を startRow に指定した場合、HTTP 500 エラーが返されます。取得されるレコード数よりも多い数を recordSize に指定した場合、すべての行が返されます。
例
Service Designer に 60 個のサービスが定義されていて、Portal Designer の nsAPI 設定に指定されているレコードの最大数が 30 であるとします。
/nsapi/definition/servicedefs
最初の 30 個のサービスが返されます。
<services totalCount="60" recordSize="30" startRow="1">
/nsapi/definition/servicedefs?startRow=4
4 番めのサービスから 30 個のサービスが返されます。
<services totalCount="60" recordSize="30" startRow="4">
/nsapi/definition/servicedefs?startRow=4&recordSize=5
4 番めのサービスから 5 個のサービスが返されます。
<services totalCount="60" recordSize="5" startRow="4">
/nsapi/definition/servicedefs?startRow=4&recordSize=35
4 番めのサービスから 30 個のサービスが返されます。
<services totalCount="60" recordSize="30" startRow="4">
ネストされたエンティティ
一部のエンティティには、ネスト構造が含まれています。nsAPI は、第 1 レベルの子または関連付けられているエンティティの取得だけをサポートしています。親エンティティとその子エンティティについて、次の表にまとめます。
|
|
|
カテゴリ |
カテゴリに関するサブカテゴリ、組み込みサービス、および提供 |
サービス |
サービスに関連付けられているカテゴリ、キーワード、およびバンドル化サービス |
提供サービス |
提供サービスに関連付けられているカテゴリ、キーワード、目的、コスト ドライバ、およびコンポーネント サービス |
個人 |
個人に関連付けられている OU、グループ、ロール、住所、連絡先、設定、および代理人 |
結果セット内に複数のデータ行を返すカテゴリ検索、サービス検索、または個人検索の場合は、パフォーマンス上の理由で、関連するエンティティは取得されません。個々のエンティティに対する Id または Name 動作による GET でのみ、関連するエンティティを取得可能です。
例
/nsapi/directory/people/loginname/<value>
個人がメンバとして属しているグループが返されます。
/nsapi/directory/people/id/<value>
個人が属しているグループが返されます。
個人が属しているグループは返され ません 。
/nsapi/directory/people?ouname=<value>
個人が属しているグループは返され ません 。
REST API の呼び出し
HTTP クライアントでの nsAPI の使用
ブラウザまたはその他の HTTP クライアントから nsAPI を呼び出すには、アプリケーション認証が必要です。
Service Portal に正常にログインしたら、有効な nsAPI REST URL をブラウザのアドレス バーに入力します。次に例を示します。
http://<serverURL>/RequestCenter/nsapi/definition/categories/id/3
次のような応答 XML がブラウザに表示されます。
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<categoryId>3</categoryId>
<categoryName>Workplace Services</categoryName>
<description>Services for voice and data communications, desktop, mobile devices, and application access.</description>
<topDescriptionEnabled>false</topDescriptionEnabled>
<middleDescriptionEnabled>false</middleDescriptionEnabled>
<bottomDescriptionEnabled>false</bottomDescriptionEnabled>
<catalogTypeId>1</catalogTypeId>
<catalogType>Consumer Services Catalog</catalogType>
<description>Order a new or refurbished laptop.Manager approval required.</description>
<description>Order a new iPhone or Blackberry, configured and maintained under corporate policy.</description>
<name>New Mobile Device</name>
<a href='/RequestCenter/myservices/navigate.do?categoryid=3&query=catalog&layout=popup_p' onclick="return GB_showFullScreen('Category', this.href)">Workplace Services</a>
<categoryURLOnlySc>/RequestCenter/myservices/navigate.do?categoryid =3&query=catalog</categoryURLOnlySc>
アプリケーションにログインする前に REST API 要求が実行された場合、URL は次のエラーを返します。
HTTP Error 401 Unauthorized
他のクライアントを介して行われた HTTP 要求の場合は、次のように nsAPI ログイン URL に HTTP ヘッダー パラメータとして認証用資格情報を渡すことができます。
http://<serverURL>/RequestCenter/nsapi/authentication/login
この HTTP ヘッダー には、次のパラメータを含める必要があります。
username =<username>
password =<password>
認証が成功したら、HTTP 応答で JSessionID クッキーが返されます。後続の nsAPI 呼び出しで認証を再び行うことなくセッションを維持するためには、同じ JSessionID クッキーを要求に含める必要があります。
JavaScript ポートレットでの nsAPI の使用
Portal Designer モジュールで作成した JavaScript ポートレット内で、nsAPI 呼び出しを実行することができます。JavaScript、REST URL、AJAX または Ext JS コンポーネントを使用して、必要なエンティティのデータを取得するポートレットを作成し、そのポートレットをグリッド形式で表現できます。
Ext JS グリッドでのデータの表現
Ext JS を使用してカテゴリのリストを表現する例を、次に示します。
/* create the Data Store */
var store = new Ext.data.Store(<
URL : 'http://<serverURL>/RequestCenter/nsapi/definition/servicecatalog/categories',
/* the return is XML, so let’s set up a reader */
reader : new Ext.data.XmlReader(<
var grid = new Ext.grid.GridPanel(<
header : "Category Name",
dataIndex : "description",
bbar : new Ext.PagingToolbar(<
displayMsg : 'Displaying topics <0> - <1> of <2>',
emptyMsg : "No topics to display"
ログイン ユーザの取得
現在ログインしているユーザの名前空間変数を取得し、JavaScript ポートレット内で使用できます。
/* Demonstrate JavaScript to get Logged-In user details */
alert(‘PersonId: ’ +nsAPP_CurrentUserId);
alert(‘Login name: ’ +nsAPP_CurrentUserLoginName);
alert(‘First name: ’ +nsAPP_CurrentUserFirstName);
alert(‘Last name: ’ +nsAPP_CurrentUserLastName);
alert(‘HomeOUId: ‘ +nsAPP_CurrentUserHomeOuId);
認証
JSR ポートレットからアクセスする場合、nsAPI Java クライアントを使用してログイン操作およびログアウト操作を呼び出すことができます。
import com.newscale.nsapiclient.NSApiClientFactory;
import com.newscale.nsapiclient.NSApiClient;
NSApiClient nsApiClient = NSApiClientFactory.getInstance();
nsApiClient.login("http://<serverURL>/RequestCenter","username", "password" ); // Login by username, password.
nsApiClient.logout(); // Logout
NSApiClient nsApiClient = NSApiClientFactory.getInstance();
nsApiClient.login("http://<serverURL>/RequestCenter",
sessionId); // Login using current session id.
ログイン ユーザの取得
次に、ログインしているユーザの詳細情報を取得する、Spring ベースの JSR Portlet Controller の例を示します。
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
import org.springframework.ui.Model;
import org.springframework.stereotype.Controller;
import com.newscale.nsapi.directory.person.Person;
public class MyJSRController {
private NSApiClient nsApiClient = getNSApiClient();
public NSApiClient getNsApiClient() {
public void setNsApiClient(NSApiClient nsApiClient) {
this.nsApiClient = nsApiClient;
public String viewNormal(RenderRequest request, RenderResponse response, Model model) {
nsApiClient.login("http://<AppServer host>:<port>/RequestCenter", request.getPortletSession().getId());
// Get Currently Logged-in user from nsAPI client
Person persons = nsApiClient.getDirectory().getCurrentUser();
long personId = persons.getPersonId());
long homeOUId = persons.getHomeOrganizationalUnitId());
String firstName =persons.getFirstName());
String lastName =persons.getLastName());
String username =persons.getLogin());
Get 操作
ここでは、エンティティの取得方法を示すサンプル コードの一部をいくつか示します。これらの方法の詳細については、個々のエンティティ クラスに関する Javadoc を参照してください。
• Id による個人の取得
package com.newscale.nsapiclient.directory;
import com.newscale.nsapiclient.directory.person.Person;
import com.newscale.nsapi.NSApiConstants;
import com.newscale.nsapiclient.directory.Directory;
import com.newscale.nsapiclient.NSApiClientFactory;
import com.newscale.nsapiclient.NSApiClient;
NSApiClient nsApiClient = NSApiClientFactory.getInstance();
nsApiClient.login("http://<serverURL>/RequestCenter","username","password");
Person person = nsApiClient.getDirectory().getPersonById(123);
/* This is the equivalent of REST URL
http://<serverURL>/RequestCenter/nsapi/directory/people/id/123
• Name による個人の取得
package com.newscale.nsapiclient.directory;
import com.newscale.nsapiclient.directory.person.Person;
import com.newscale.nsapi.NSApiConstants;
import com.newscale.nsapiclient.directory.Directory;
import com.newscale.nsapiclient.NSApiClientFactory;
import com.newscale.nsapiclient.NSApiClient;
NSApiClient nsApiClient = NSApiClientFactory.getInstance();
nsApiClient.login("http://<serverURL>/RequestCenter","username","password");
Person person = nsApiClient.getDirectory().getPersonByLoginName("jsmith");
This is the equivalent of REST URL
http://<serverURL>/RequestCenter/nsapi/directory/people/loginname/jsmith
• すべての人の取得
package com.newscale.nsapiclient.directory;
import com.newscale.nsapiclient.directory.person.Person;
import com.newscale.nsapi.NSApiConstants;
import com.newscale.nsapiclient.directory.Directory;
import com.newscale.nsapiclient.NSApiClientFactory;
import com.newscale.nsapiclient.NSApiClient;
import org.apache.commons.collections.map.MultiValueMap;
NSApiClient nsApiClient = NSApiClientFactory.getInstance();
nsApiClient.login("http://<serverURL>/RequestCenter","username","password");
PersonList persons = nsApiClient.getDirectory().getPeople(null);
This is the equivalent of REST URL
http://<serverURL>/RequestCenter/nsapi/directory/people
• クエリー フィルタによる個人の取得
package com.newscale.nsapiclient.directory;
import com.newscale.nsapiclient.directory.person.Person;
import com.newscale.nsapi.NSApiConstants;
import com.newscale.nsapiclient.directory.Directory;
import com.newscale.nsapiclient.NSApiClientFactory;
import com.newscale.nsapiclient.NSApiClientConstants;
import com.newscale.nsapiclient.NSApiClient;
import org.apache.commons.collections.map.MultiValueMap;
NSApiClient nsApiClient = NSApiClientFactory.getInstance();
nsApiClient.login("http://<serverURL>/RequestCenter","username","password");
MultiValueMap filterMap = new MultiValueMap();//this can be used to specify multiple filter criteria
filterMap.put(NSApiClientConstants.QUERYPARAM_NAME, "John");
PersonList persons = nsApiClient.getDirectory().getPeople(filterMap);
This is the equivalent of REST URL
http://<serverURL>/RequestCenter/nsapi/directory/people?name=John
• 複数のクエリー フィルタによる個人の取得
package com.newscale.nsapiclient.directory;
import com.newscale.nsapiclient.directory.person.Person;
import com.newscale.nsapi.NSApiConstants;
import com.newscale.nsapiclient.directory.Directory;
import com.newscale.nsapiclient.NSApiClientFactory;
import com.newscale.nsapiclient.NSApiClientConstants;
import com.newscale.nsapiclient.NSApiClient;
import org.apache.commons.collections.map.MultiValueMap;
NSApiClient nsApiClient = NSApiClientFactory.getInstance();
nsApiClient.login("http://<serverURL>/RequestCenter","username","password");
MultiValueMap filterMap = new MultiValueMap();
filterMap.put(NSApiClientConstants.QUERYPARAM_NAME, "John");
filterMap.put(NSApiClientConstants.QUERYPARAM_SORTBY, "lastName");
filterMap.put(NSApiClientConstants.QUERYPARAM_SORTDIR, "asc");
PersonList persons = nsApiClient.getDirectory().getPeople(filterMap);
// This is the equivalent of REST URL
// http://<serverURL>/RequestCenter/nsapi/directory/people?name
// =John&sortBy=lastName&sortDir=asc
// search for people by the name John,
// sort the result set by Last Name in ascending order
Post 操作
ここでは、個人の作成および更新方法、ならびにタスクに対するアクションの実行方法を示すサンプル コードの一部をいくつか示します。これらの方法の詳細については、個々のエンティティ クラスに関する Javadoc を参照してください。
• 個人の更新
package com.newscale.nsapiclient.directory;
import com.newscale.nsapiclient.directory.person.Person;
import com.newscale.nsapi.NSApiConstants;
import com.newscale.nsapiclient.directory.Directory;
import com.newscale.nsapiclient.NSApiClientFactory;
import com.newscale.nsapiclient.NSApiClient;
NSApiClient nsApiClient = NSApiClientFactory.getInstance();
nsApiClient.login("http://<serverURL>/RequestCenter","username","password");
Person person = NSApiClient.getDirectory().getPersonById(123);
person.setLastName("Smith");
Person persons = NSApiClient.getDirectory().updatePerson(person);
This is the equivalent of posting XML of person 123 with last name changed to "Smith" to the REST URL
http://<serverURL>/RequestCenter/nsapi/directory/people/update
• 配信タスクの完了
package com.newscale.nsapiclient.transaction;
import com.newscale.nsapiclient.transaction.task.TaskAction;
import com.newscale.nsapi.NSApiConstants;
import com.newscale.nsapiclient.transaction.Transaction;
import com.newscale.nsapiclient.NSApiClientFactory;
import com.newscale.nsapiclient.NSApiClientConstants;
import com.newscale.nsapiclient.NSApiClient;
import org.apache.commons.collections.map.MultiValueMap;
NSApiClient nsApiClient = NSApiClientFactory.getInstance();
nsApiClient.login("http://<serverURL>/RequestCenter","username","password");
// This is the equivalent of REST URL
// http://<serverURL>/RequestCenter/nsapi/tasks/10/done
NSApiClient.getTransaction().completeTask(10);
エラー メッセージ
nsAPI は、次のように、例外の性質に応じてさまざまな HTTP 応答コードを返します。
• HTTP ステータス コード 401 （Unauthorized）および XML エラー応答メッセージ「 User does not have proper authentication .」：認証パラメータが無効であるか、または指定されていません。
• HTTP ステータス コード 404 （Not Found）および XML エラー応答メッセージ「 Requested resource could not be found .」：指定されたパラメータ/URL 値のデータを取得できませんでした。
例：
nsapi/directory/people/id/-1
nsapi/directory/people/id/foo
nsapi/directory/people/id/1000（id が 1000 の個人が存在しない場合）
nsapi/directory/people/name/<non existent person>
nsapi/directory/people/idxyz/1
• HTTP ステータス コード 403 （Forbidden）および XML エラー応答メッセージ「 The user does not have sufficient permissions to perform the operation this object .」：指定された操作をオブジェクトに対して実行するために必要な権限をユーザが持っていないため、データを取得できませんでした。
• HTTP ステータス 500 （内部エラー）および XML エラー応答メッセージ「 Internal Error: Invalid parameter values specified or unexpected error .」：パラメータの誤り。あるいは、nsAPI の内部で発生したその他の例外。または、その他の一般的なサーバ エラー。
例：
nsapi/directory/people?startRow=5000（5000 行存在していない場合）
nsapi/directory/people?sortBy=wrongColumn&sortDir=Asc（サポートされていないカラム）
nsapi/directory/people?recordSize=-1（recordSize が負またはゼロの値）
• Http ステータス 422 （Unprocessable Entity）、および POST/UPDATE 操作に対する XML 妥当性検査エラー応答メッセージ：要求データの必須フィールドに値がありません。または無効な値が入っています。
nsAPI は、指定されたフィルタに対する結果が存在しない場合には、エラーを返しません。次に例を示します。
nsapi/directory/people?name=<non-existent person>
nsAPI でのメソッドの実行中に発生したすべての例外について、nsAPI は Java から NSAPIException をスローします。
フィードバック