Prime Service Catalog RESTful API のリファレンスおよび例

概要

この章では、サービス カタログ（Service Catalog）の Web サービスの使用法について説明します。これには、SOAP ベース バージョンの要求 API（RAPI 2）を実装する Web サービスが含まれます。これは、外部システムが Service Catalog 内でサービス要求を作成および管理できるようにする API です。Web サービスには、サービス要求内の提供タスクや承認タスクの管理を許可し、Service Catalog の内容の確認を行う要求なども含まれます。

REST URL の構文および表記法

  • 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 操作においてエンティティのタイプに基づき多様なフィルタをサポートしています。

表 3-1 サポートされているフィルタ テーブル

エンティティ タイプ
使用可能なフィルタ/構文
REST URL の例

すべてのエンティティ

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/serviceitems/serviceitemsubscription/AccountName=tenantaccount1

http://serverURL/RequestCenter/nsapi/customcontent/UcAnnouncementObj/Category=Corporate

サービス項目（Service Items）

ビュー名（View Name）

?ViewName=<value>

指定可能なビュー名は次のとおりです。

  • My ServiceItems（My Services に表示される）
  • Manage ServiceItems（Service Item Manager に表示される）

http://serverURL/RequestCenter/nsapi/serviceitem/SiDesktop?ViewName=My%20ServiceItems

http://serverURL/RequestCenter/nsapi/serviceitem/SiDesktop?ViewName=Manage%20ServiceItems

組織

OU Type

?type=<all/businessUnit/serviceTeam>

http://serverURL/RequestCenter/nsapi/directory/organizationalunits?type=serviceTeam

個人(Person)

ログイン名（Login Name）

?loginname/<value>

http://serverURL/RequestCenter/nsapi/directory/people?loginname/dsmith

OU 名前

?ouname=<value>

http://serverURL/RequestCenter/nsapi/directory/people?ouname=Operations

グループ名（Group Name）

?groupname=<value>

http://serverURL/RequestCenter/nsapi/directory/people?groupname=Approvers

役割名

?rolename=<value>

継承されたロールをフィルタに使用することはできません。

http://serverURL/RequestCenter/nsapi/directory/people?rolename=Service%20Performer

カテゴリ（Categories）

カテゴリ タイプ（Category Type）

?catalogType=<serviceCatalog/offeringCatalog>

http://serverURL/RequestCenter/nsapi/definition/categories?catalogType=serviceCatalog

ユーザ コンテキスト

?userContext=<true/false>

http://serverURL/RequestCenter/nsapi/definition/categories?userContext=true

サービス

カテゴリ名（Category Name）

?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

タスク

ビュー名（View Name）

?viewName=<value>

フィルタに使用可能なビュー名は、Service Manager のシステム定義ビューのリストに対応しています。ユーザ定義ビューをフィルタに使用することはできません。

http://serverURL/RequestCenter/nsapi/transaction/tasks?viewName=AvailableWork

タスク（特定の要求エントリに関するもの）

タスク タイプ（Task Type）

?taskType=<value>

可能なタスク タイプは「すべて」、「提供」、および「承認」です。

タスク ステータス（省略）

?showSkippedTasks=<false|true>

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks/RequisitionEntryNumber=1234?taskType=delivery&showSkippedTasks=true

POST 操作では、次のフィルタがサポートされています。

表 3-2 POST 操作でサポートされているフィルタ テーブル
エンティティ タイプ
使用可能なフィルタ
REST URL の例

個人(Person)

ログイン名または 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> など）、検索文字列の先頭のワイルドカード文字（「*」や「%」など）は無視されます。これらの文字が文字列の中または末尾にある場合は、ワイルドカード照合で適用されます。

名前検索で先頭のワイルドカード文字の使用を有効にするには、ContainsQueryInFnS プロパティを newscale.properties ファイル（RequestCenter.war/WEB-INF/classes/config にあります）で見つけ、値を true に設定します。

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 に渡されない場合は、次の表に示すように、デフォルトのソート フィールドとソート順序が使用されます。

表 3-3 ソート パラメータ

エンティティ タイプ
デフォルトのソート フィールドとソート順序

カテゴリ（Categories）

Name（昇順）

サービス

Name（昇順）

カリキュラム

Name（昇順）

エージェント（Agents）

Name（昇順）

人員（People）

First Name（昇順）

組織

Name（昇順）

グループ（Groups）

Name（昇順）

アカウント

Name（昇順）

すべてのサービス項目

Row Id*（昇順）

サービス項目の詳細

Row Id*（昇順）

標準（Standards）

Row Id*（昇順）

カスタム コンテンツ（Custom Content）

Row Id*（昇順）

要求

Submit Date（昇順）、Requisition Id（昇順）

要求エントリ

要求エントリ ID（Requisition Entry ID）（昇順）

タスク

タスク名（Task Name）（昇順）、タスク ID（Task Id）（昇順）

承認

要求 ID（Requisition Id）（昇順）、タスク 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">
<category>
<categoryId>1</categoryId>
<categoryName><b>Consumer Services</b></categoryName>
<description />
...
 

取得されるレコード数より大きい startRow を指定すると、HTTP 500 エラーが返されます。取得されるレコード数より大きい recordSize を指定すると、すべての行が返されます。

例

次の例では、Service Designer で 60 個のサービスが定義されており、Portal Designer の nsAPI 設定で指定できるレコードの最大数が 30 であると想定しています。

例 1：

/nsapi/definition/servicedefs
 

最初の 30 個のサービスが返されます。このような要求に対する応答の例は次のようになります。

<services totalCount="60" recordSize="30" startRow="1">
...
</services>
 

例 2：

/nsapi/definition/servicedefs?startRow=4
 

4 番めのサービスから始まる 30 個のサービスが返されます。このような要求に対する応答の例は次のようになります。

<services totalCount="60" recordSize="30" startRow="4">
...
</services>
 

例 3：

/nsapi/definition/servicedefs?startRow=4&recordSize=5
 

4 番めのサービスから始まる 5 個のサービスが返されます。このような要求に対する応答の例は次のようになります。

<services totalCount="60" recordSize="5" startRow="4">
...
</services>
 

例 4：

/nsapi/definition/servicedefs?startRow=4&recordSize=35
 

4 番めのサービスから始まる 30 個のサービスが返されます。このような要求に対する応答の例は次のようになります。

<services totalCount="60" recordSize="30" startRow="4">
...
</services>
 

ネストされたエンティティ

ある種のエンティティにはネスト構造が含まれます。第 1 レベルの子だけまたは関連付けられたエンティティの取得は nsAPI によってサポートされます。親エンティティおよびその子エンティティを表にまとめます。

表 3-4 ネストされたエンティティ
親エンティティ
子エンティティ

カテゴリ（Categories）

カテゴリのサブカテゴリ、組み込みサービス、および提供

サービス

サービスに関連付けられたカテゴリ、キーワード、およびバンドル サービス

個人(Person)

個人に関連付けられた OU、グループ、ロール、住所、連絡先、設定、および代理人

結果セットで複数行のデータを返すカテゴリ検索、サービス検索、または人の検索では、関連付けられたエンティティはパフォーマンス上の理由により取得されません。関連付けられたエンティティを利用できるのは、個々のエンティティに対する ID または名前による取得操作の場合だけです。

例

/nsapi/directory/people/loginname/<value>
 

個人がメンバーとなっているグループが返されます。

<person>
...
<associatedGroups>
<associatedGroup>
<id>2</id>
<name>group2</name>
</associatedGroup>
<associatedGroup>
<id>5</id>
<name>group5</name>
</associatedGroup>
</associatedGroups>
</person>
 
/nsapi/directory/people/id/<value>
 

個人が属しているグループが返されます。

/nsapi/directory/people
 

個人が属しているグループは返され ません 。

/nsapi/directory/people?ouname=<value>
 

個人が属しているグループは返され ません 。

JavaScript ポートレットでの nsAPI の使用

nsAPI コールは、Portal Designer モジュールで開発された JavaScript ポートレットで呼び出すことができます。JavaScript、REST URL、AJAX、または Ext JS コンポーネントを使用すると、ポートレットを作成して目的のエンティティのデータを取得し、グリッド形式でレンダリングできます。

Ext JS グリッドでデータをレンダリングする

以下に、Ext JS を使用してカテゴリのリストをレンダリングする例を示します。

getUrl = "/RequestCenter/nsapi/definition/categories";
 
var proxy = new Ext.data.HttpProxy({
url: getUrl,
method: 'GET'
});
 
defaultPageSize = 5;
fieldList = [ "categoryId",
"categoryName",
"description",
"topDescriptionEnabled",
"topDescription",
"topDescriptionURL",
"middleDescriptionEnabled",
"middleDescription",
"middleDescriptionURL",
"bottomDescriptionEnabled",
"bottomDescription",
"bottomDescriptionURL",
"catalogTypeId",
"catalogType",
"isRoot",
"descriptionURL",
"categoryURL"]
 
displayList = [
{id: 'id', header: 'Id', width: 50,sortable: false, dataIndex: 'categoryId'},
{header: 'Name',sortable: true, dataIndex: 'categoryName'},
{header: 'Description', dataIndex: 'description',sortable: false},
{header: 'TD Enabled', dataIndex: 'topDescriptionEnabled',hidden:true,sortable: false},
{header: 'Top Description', dataIndex: 'topDescription',hidden:true,sortable: false},
{header: 'Top Description URL', dataIndex: 'topDescriptionURL',hidden:true,sortable: false},
{header: 'Middle DescriptionEnabled', dataIndex: 'middleDescriptionEnabled',hidden:true,sortable: false},
{header: 'Middle Description', dataIndex: 'middleDescription',hidden:true,sortable: false},
{header: 'Middle Description URL', dataIndex: 'middleDescriptionURL',hidden:true,sortable: false},
{header: 'Bottom Description Enabled', dataIndex: 'bottomDescriptionEnabled',hidden:true,sortable: false},
{header: 'Bottom Description', dataIndex: 'bottomDescription',hidden:true,sortable: false},
{header: 'Bottom Description URL', dataIndex: 'bottomDescriptionURL',hidden:true,sortable: false},
{header: 'Catalog Type Id', dataIndex: 'catalogTypeId',hidden:true,sortable: false},
{header: 'Catalog Type', dataIndex: 'catalogType',hidden:true,sortable: false},
{header: 'isRoot', dataIndex: 'isRoot',hidden:true,sortable: false},
{header: 'descriptionURL', dataIndex: 'descriptionURL',hidden:true,sortable: false},
{header: 'URL', dataIndex: 'categoryURL',sortable: false}
];
var store = new Ext.data.XmlStore({
autoDestroy: true,
proxy: proxy,
root : "categories",
record: 'category',
idPath: 'rowId',
totalProperty: '@totalCount',
autoLoad: true,
paramNames: {
start: 'startRow',
limit: 'recordSize',
catName : 'categoryName'
},
fields: fieldList
});
 
var sortchange = function(obj,direction) {
store.setBaseParam("sortBy","categoryName");
store.setBaseParam("sortDir",direction.direction);
store.load();
}
 
 
var grid = new Ext.grid.GridPanel({
renderTo : '#divName#',
store : store,
autoWidth : true,
height : 300,
title : 'Category List',
colModel: new Ext.grid.ColumnModel({
defaults: {
width: 120,
sortable: true
},
columns:displayList,
}),
bbar : [new Ext.PagingToolbar({
store : store,
displayInfo : true,
pageSize : defaultPageSize,
params:{
startRow: 1,
recordSize: defaultPageSize
}
})]
});
 
grid.on("sortchange",sortchange);
store.setBaseParam("recordSize",5);
store.load();

ログイン ユーザの取得

現在ログインしているユーザの名前空間変数は JavaScript ポートレットで使用できるようになります。次に例を示します。

Ext.onReady(function() {
/* 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 の使用

認証

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.
...
...
nsApiClient.logout();
 

ログイン ユーザの取得

次に、ログインしているユーザの詳細情報を取得する、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;
…
@Controller
public class MyJSRController {
private NSApiClient nsApiClient = getNSApiClient();
public NSApiClient getNsApiClient() {
return nsApiClient;
}
public void setNsApiClient(NSApiClient nsApiClient) {
this.nsApiClient = nsApiClient;
}
@RequestMapping("VIEW")
@RenderMapping("NORMAL")
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();
// Get user info
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.nsapi.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
*/
...
nsApiClient.logout();
 
  • Name による個人の取得
package com.newscale.nsapiclient.directory;
import com.newscale.nsapi.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
*/
 
...
nsApiClient.logout();
 
  • すべての人の取得
package com.newscale.nsapiclient.directory;
import com.newscale.nsapi.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 java.util.List;
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
*/
...
nsApiClient.logout();
 
  • クエリー フィルタによる個人の取得
package com.newscale.nsapiclient.directory;
import com.newscale.nsapi.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;
 
import java.util.List;
 
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
*/
...
nsApiClient.logout();
 
  • 複数のクエリー フィルタによる個人の取得
package com.newscale.nsapiclient.directory;
import com.newscale.nsapi.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;
 
import java.util.List;
...
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
...
nsApiClient.logout();

Post 操作

ここでは、個人の作成および更新方法、ならびにタスクに対するアクションの実行方法を示すサンプル コードの一部をいくつか示します。これらの方法の詳細については、個々のエンティティ クラスに関する Javadoc を参照してください。

  • 個人の更新
package com.newscale.nsapiclient.directory;
import com.newscale.nsapi.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
*/
...
nsApiClient.logout();
 
  • 配信タスクの完了
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;
 
import java.util.List;
...
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);
nsApiClient.logout();

API リファレンスおよび例

nsAPI の javadoc は、製品インストーラの Image フォルダにあります。REST URL および java クライアントから nsAPI を呼び出す例を、サポートされているエンティティごとに示します。

定義データ

カテゴリ（Categories）

 

表 3-5 カテゴリ API テーブル

領域
例

Core API

すべてのカテゴリの取得

デフォルトでは、タイプが「Service Catalog」のカテゴリのみが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/categories?catalogType=serviceCatalog

Java の例

CategoryList categories = NSApiClient.getDefinition().getCategories(null);

すべてのコンシューマ サービス カテゴリの取得

「Consumer Services」タイプのすべてのカテゴリが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/categories

Java の例

CategoryList categories = NSApiClient.getDefinition().getCategories("serviceCatalog");

Name によるコンシューマ サービス カテゴリの取得

指定した名前のサービス カタログ カテゴリが返されます。ネストされたエンティティ（サブカテゴリおよび組み込みサービス）が取得されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/categories/name/<categoryName>

Java の例

Category categories = NSApiClient.getDefinition().getCategoryByName("<categoryName>");

 

Id によるコンシューマ サービス カテゴリの取得

指定した Id のサービス カタログ カテゴリが返されます。ネストされたエンティティ（サブカテゴリおよび組み込みサービス）が取得されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/categories/id/<categoryId>

Java の例

Category categories = NSApiClient. getDefinition().getCategoriesById(<categoryId>);

 

Name による提供サービス カテゴリの取得

ネストされたエンティティ（サブカテゴリおよび組み込み提供）が含まれます。指定した名前のサービス提供カテゴリが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/categories/name/<categoryName>?catalogType=offeringCatalog

Java の例

MultiValueMap paramsMap = new MultiValueMap();
paramsMap.put(QUERYPARAM_CATALOG_TYPE, "offeringCatalog");
Category categories = NSApiClient.getDefinition().getCategoryByName("<categoryName>");

フィルタ

カテゴリ名フィルタ

検索では大文字と小文字が区別されます。

StartsWith（newscale.properties の ContainsQueryInFnS=false）：先頭のワイルドカードは無視されます。

Contains（newscale.properties の ContainsQueryInFnS=true）：先頭のワイルドカードは適用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/categories?name=<wildcardValue>&catalogType=serviceCatalog

Java Example:
MultiValueMap paramsMap = new MultiValueMap();
paramsMap.put(QUERYPARAM_CATALOG_TYPE, "serviceCatalog");
paramsMap.put(QUERYPARAM_NAME, "<wildcardValue>");
CategoryList categories = NSApiClient.getDefinition().getCategories(paramsMap);

 

サービス ユーザ アクセス フィルタ

オーダーする権限を持つログオン中のユーザについて、その直下またはその階層にあるサービスのすべてのカテゴリを返します。

REST URL:

http://<ServiceUrl>/RequestCenter/nsapi/definition/categories?userContext=<true or false>

Java Example:
MultiValueMap paramMap = new MultiValueMap();
paramMap.put(QUERYPARAM_USERCONTEXT, "true");

NSApiClient.getDefinition().getCategories(paramMap);

ソート カラム

CategoryName

応答 XML
<categories totalCount="x" recordSize="y" startRow="z">
<category>
...
<associatedServices>
...
<associatedService>
<description> </description>
<id></id>
<imageURL></imageURL>
<name> </name>
<status> </status>
</associatedService>
...
</associatedServices>
...
</category>
</categories>

環境

表 3-6 環境 API テーブル

領域
例

コア API

パブリック GUI ID を使用して AMQP 環境の詳細を取得（パブリック GUI ID：[管理（Administration）] > [設定（Settings）] に移動し、パブリック/プライベート キーを指定します）

すべての AMQP 環境の詳細が返されます。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/messagebroker/service/<serviceName>?publicKeyGUID=...

http://<ServerURL>/RequestCenter/nsapi/messagebroker/overview?publicKeyGUID=...

ステータス コード：200 OK

ステータス コード：400 Bad request

パブリック キー GUID を使用した暗号化クレデンシャルの詳細については、「AMQP との統合」の項を参照してください。

プロバイダー タイプ、短縮名によりクラウド接続の詳細を取得

指定した短縮名について、Base64 符号化形式の SSL 証明書を含む、クラウド タイプ（UCSD/ICFD/PUPPET など）の接続情報が返されます。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/definition/connections/provider/{providerName}/shortName/{shortName}

{Provider name} には UCSD/ICFD/PUPPET を指定でき、{psc} は接続に使用される短縮名 ID です。接続インシデントが https の場合、API は接続に使用するルート証明書を返します。接続の SSL 証明書（Base 64 形式）も返されます。

ステータス コード：200 OK

ステータス コード：400 Bad request

サンプル応答：

{

"connections":

{

"connection":

[

{

"primaryID": 2,

"userName": "admin",

"protocol": "https",

"hostName": "172.21.38.151",

"description": "...",

"url": "https://172.21.38.151:443/app/api/rest",

"port": 443,

 

プロバイダー タイプ、パブリック GUI ID を使用した短縮名により、クラウドの接続詳細を取得

外部システムのパブリック キー GUID がクエリー パラメータとして渡された場合、応答内のクレデンシャル（パスワードとトークン）は GUID に関連付けられているパブリック キーにより暗号化されます（PO のセキュア ストリング形式を使用）。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/definition/connections/provider/{providerName}/shortName/{shortName}?publicKeyGUID=..

パブリック キー GUID が渡されないか、間違っている場合、ステータス コード：400 不正な要求が返されます。

 

AMQP サーバ詳細の作成

AMQP サーバとの SSL 接続および非 SSL 接続を作成し、Web インターフェイスで AMQP サーバの詳細を更新します。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/ucsd/discovery/saveConnection

SSL 証明書を使用する接続の場合：

{
"id": "row-1",
"shortName": "am2",
"description": "amqp_server2",
"protocol": "SSL",
"hostName": "10.78.0.247",
"port": "5671",
"un": "pscuser",
"up": "!@^_cHNjdXNlcg==_^@!",
"pollerEnabled": "0",
"provider": "AMQP",
"exportUser": "0",
"cert": "-----BEGIN CERTIFICATE-----\nMIIC5DCCAcygAwIBAgIBATANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDDAhNeVRlc3RDQTAeFw0x\nNjA2MTExMTUwMTJaFw0xNzA2MTExMTUwMTJaMCcxFDASBgNVBAMMCyQoaG9zdG5hbWUpMQ8wDQYD\nVQQKDAZzZXJ2ZXIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCq8v2yJT7tv+nOwFSo\nEE1c0oVg3skd86JN7jVJaz/mMOyJjDmf1147iUwZPMTTCB34ovYUXFkw+a+0ext2WRHgQLTMPvVO\nA86jwuPd/bhUxXg8jeEfE4V/1Seci9Xz+5VxqCybCNOzJQ12/vLXvIJK43U/+1GdXnpWxFaF0yd0\nht3iUy6mfUAHfNMI2SOfJwbbdUaMyD0/Krsiu+X+vFQBUDmM7Y0priItiDVDq7rxug2UOPACzzMG\n5yJ5aJjNLSlJRwKKst/jjvesqHIgWNo0qKvkTET3tIVsKDi1Fn9IdKQuuoI1n225+58cWSANmZ5M\n4BdSIf4z6QRuKliBRi55AgMBAAGjLzAtMAkGA1UdEwQCMAAwCwYDVR0PBAQDAgUgMBMGA1UdJQQM\nMAoGCCsGAQUFBwMBMA0GCSqGSIb3DQEBCwUAA4IBAQC4L9fk4kuu/dpLeFWNUhb5Uyk6AqbTRAyD\nlq1m11E09EhmTH7cnoFsz0ELBDppASIUADSb9jmUeNKJtjW94gq8luSem1Z8lQzUCOCE6rsaznrw\nm9jJO7gXA5SSmy7PgdokdhbeTzlSYA3kkkR5ZE8M403Qv5cEPREqnshs6f6bQSm8tzSNETy3OyHL\npUo7YVTBCfJMQ/e2nZxCJSDuEL6QaIL4kmEYeu8j/1RplBAofMkDfDe+yMx2MJYl+MopVggGexpa\nMqybCchrDTJ/8sI/R18Ld80TQ2Km70sQqvNVenCpGCtgGIcupRWaAOpsQH0PNaUK+lcwYRIvf0VS\n09QE\n-----END CERTIFICATE-----",
"ovCert": "",
"skipValidateCertificate": "0",
"virtualHost": "psc",
"publicKey": "none",
"secureStringFormat": "Bytes",
"serverDownNotification": "none",
"recoveryInterval": "5",
"inboundQueue": "psc_inbound_queue",
"messageType": "XML",
"basicAuthentication": "0",
"isTriggeredByPoller": false
}

 

SSL 証明書のない接続の場合：

{
"id": "row-1",
"shortName": "am1",
"description": "amqp_server1",
"protocol": "TCP",
"hostName": "10.78.0.247",
"port": "5672",
"un": "admin",
"up": "!@^_Y2lzY28xMjM=_^@!",
"pollerEnabled": "0",
"provider": "AMQP",
"exportUser": "0",
"cert": "",
"ovCert": "",
"skipValidateCertificate": "0",
"virtualHost": "default",
"publicKey": "none",
"secureStringFormat": "Bytes",
"serverDownNotification": "none",
"recoveryInterval": "5",
"inboundQueue": "psc_inbound_queue",
"messageType": "XML",
"basicAuthentication": "0",
"isTriggeredByPoller": false
}

（注） パスワードの値は、Base64 で暗号化された値として、プレフィックス !@^_ およびサフィックス _^@! が付いた形で渡されます。Base64 で暗号化された値は、JavaScript btoa メソッドを使用して生成できます。

（注） ShortName の長さは最大 3 文字です。

 

AMQP 接続の削除

POST REST URL：

http://<Server URL>/RequestCenter/nsapi/ucsd/discovery/deleteConnection

{
"shortName": "am3",
"provider": "AMQP"
"protocol": "TCP"
}

ローカリゼーション

表 3-7 ローカリゼーション API テーブル

領域
例

コア API

すべての言語をロケール詳細とともに取得

すべての言語をロケールの詳細とともに返します。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/localization/locales

サンプル応答：

[

{

"active": 1,

"defaultCurrency": "REAL",

"defaultDateSep": "/",

"defaultLongDate": "dd 'de' MMMM 'de' yyyy",

"defaultShortDate": "dd/MM/yy",

"defaultTime": "HH:mm:ss",

"localeCode": "BRPT",

"localeID": 9,

"name": "Brazilian-Portuguese"

},

{

"active": 1,

"defaultCurrency": "YEN",

"defaultDateSep": "/",

"defaultLongDate": "MMMM dd, yyyy",

"defaultShortDate": "MM/dd/yyyy",

"defaultTime": "h:mm aa",

"localeCode": "CNZH",

"localeID": 6,

"name": "Chinese (Simplified)"

},

-----

-----

]

 
 

 

ロケールに固有な JavaScript 文字列の取得

入力で渡されるロケールに固有な JavaScript 文字列を返します。デフォルトでは、英語ロケールの JavaScript 文字列が返されます。要求で不明なロケールが渡された場合、既知のロケールに関する応答を返し、不明なロケールに関するエラー応答は表示しません。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/localization/javascriptstrings?locales=KRKO, ALSQABC, BRBT, CNZH

サンプル応答：

[

{

"StringID": "js1",

"US English": "src_eng22",

"Chinese (Simplified)": "",

"Brazilian-Portuguese": "",

"Korean": "update5"

},

{

"StringID": "js2",

"US English": "src_eng2",

"Chinese (Simplified)": "",

"Brazilian-Portuguese": "",

"Korean": "5"

},

--------

---------

]

 

すべての使用可能な言語のすべての使用可能な JavaScript 文字列の取得

すべての使用可能な言語について、すべての使用可能な JavaScript 文字列を返します。つまり、言語の数に制限はありません。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/localization/javascriptstrings

サンプル応答：

[

{

"StringID": "js1",

"US English": "src_eng22",

"German": "",

"Spanish": "",

"French": "js string french",

"Korean": "update5"

},

{

"StringID": "js2",

"US English": "src_eng2",

"German": "",

"Spanish": "",

"French": "french js2",

"Korean": "5"

},

----------

-----------

]

 

すべての使用可能な言語のすべての使用可能な JavaScript 文字列をポスト

REST URL:

http://<ServerURL>/RequestCenter/nsapi/localization/javascriptstrings

サンプル要求：

[

{

"StringID": "js1",

"US English": "src_eng22",

"German": "",

"Spanish": "",

"French": "js string french",

"Korean": "update5"

},

{

"StringID": "js2",

"US English": "src_eng2",

"German": "",

"Spanish": "",

"French": “french js2",

"Korean": "5"

},

----------

-----------

]

サンプル成功応答：

JavaScript 文字列の作成/更新が正常に完了しました。

サンプルエラー応答：

JSON コンテンツ内の言語名は、この製品では、スペルが誤っているか、利用できません。「French (Switzerland)」で確認してください。

サービス

 

表 3-8 サービス API テーブル

領域
例

コア API

すべてのサービスの取得

すべてのサービスが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/servicedefs

Java の例

ServiceList services = NSApiClient.getDefinition().getServices(null);

 

サービス カタログのワイルドカード検索によるすべてのサービスの取得

サービスの名前、サービスの説明、カテゴリ、またはキーワードが検索文字列と一致しているサービスがすべて返されます。先頭のワイルドカードはサポートされません。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/servicedefs?search={wildcardValue*}

Java の例

MultiValueMap paramsMap = new MultiValueMap();
paramsMap.put("search", "<wildcardValue*>");
ServiceList services = NSApiClient.getDefinition().getServices(paramsMap);

 

Id によるサービスの取得

ネストされたエンティティ（関連付けられているカテゴリおよびキーワード）は、getById および getByName の場合にのみ取得されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/servicedefs/id/<serviceId>

Java の例

Service services = NSApiClient.getDefinition().getServiceById(<serviceId>);

 

Name によるサービスの取得

ネストされたエンティティ（関連付けられているカテゴリおよびキーワード）は、getbyId および getByName の場合にのみ取得されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/servicedefs/name/<serviceName>

Java の例

Service services = NSApiClient.getDefinition().getServiceByName("<serviceName>");

 

カテゴリに含まれるすべてのサービスの取得

そのカテゴリに関連付けられているすべてのサービスが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/servicedefs?categoryName=<categoryName>

Java の例

ServiceList services =NSApiClient.getDefinition().getServiceByCategoryName("<categoryName>");

 

キーワードによるすべてのサービスの取得

そのキーワードに関連付けられているすべてのサービスが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/servicedefs?keywordName=<keyword>

Java の例

ServiceList services = NSApiClient.getDefinition().getServiceByKeyword("<keyword>");

フィルタ

サービス名フィルタ

検索では大文字と小文字が区別されます。

StartsWith（newscale.properties の ContainsQueryInFnS=false）：先頭のワイルドカードは無視されます。

Contains（newscale.properties の ContainsQueryInFnS=true）：先頭のワイルドカードは、必要に応じて指定してください。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/servicedefs?name=<wildcardValue>

Java の例

MultiValueMap paramsMap = new MultiValueMap();
paramsMap.put("name","<wildcardValue>");
ServiceList servicesList = NSApiClient.getDefinition().getServices(paramsMap)

ソート カラム

ServiceName

応答 XML
<services totalCount="x" recordSize="y" startRow="z">
<service>
...
<includedServices>
...
<includedService>
<id></id>
<name> </name>
</includedService>
...
</includedServices>
...
</service>
</services>

CategoriesExtensions およびファセット

カテゴリ、ファセット、および拡張子によりサービスを作成/更新します。

新しいサービスに POST を使用 - サービスがすでに存在する場合、エラーが発生します。カテゴリ、ファセット、および拡張子を作成/更新し、それをサービスに関連付けます。

既存のサービスを更新するために PUT を使用 - サービスが存在しない場合、エラーが発生します。カテゴリ、ファセット、および拡張子を作成/更新して、それをサービスに関連付けます。

REST URL:

/RequestCenter/nsapi/cloud/marketplace/service

サンプル ペイロード:

{

"serviceName": "TestServiceT225", "serviceId": "...", "templateName": "TestService", "templateCategory" : "TemplateCategory", "description": "test", "imageData": "", "imageURL": "$RC_IMAGEPATH$/ABCServer.jpeg", "overview": "<p><strong>Product Details<\/strong><br />Version: 1.23.0-0 on Ubuntu 12.04.4<br />", "serviceGroupName": "TestGrp",

"categories": [

{

"name": "TestABCImageURL2", "description" : "TestDesc", "imageURL": "$RC_IMAGEPATH$/ABCServer.jpeg"}

],

"facetes": {

"facetlogicname1" : {"displayName" : "Facet 1", "values" : ["f1val1", "f1val2", "f1val3", "f1val4"]},

"facetlogicname2" : {"displayName" : "Facet 2", "values" : ["f2val1", "f2val2"]}

},

"extensions": {

"extensionlogicname1" : {"displayName" : "Extension 1", "values" : "extval1"},

"extensionlogicname2" : {"displayName" : "Extension 2", "values" : "extval2"}

}

}

サンプルの応答 XML：

{ "JSONObject":

{

"serviceName": "TestNewJSON1-TestNew",

"serviceEndpoint":

"/RequestCenter/nsapi/definition/servicedefs/name/TestNewJSON1-TestNew"

}

}

 

サービスのカテゴリのリンクを解除する

POST REST URL：

http://<Server URL>/RequestCenter/nsapi/definition/servicedefs/id/{serviceId}/delinkCategories

サンプル ペイロード:

{"categories" :["catname1","catname2",...]}

ステータス コード：200 OK

ステータス コード：400 Bad request

サンプル応答：

{

status-message:

{

code: "...."

value: "....."

}

}

 

さまざまなシナリオにおける応答：

1. 渡された serviceId が存在しない場合：

HTTP コード：404

HTTP 応答：

{

nsapi-error-response:

{

errorcode: "SERV_0001"

errormessage: "ServiceId does not exist."

}

}

2. 渡されるカテゴリのいずれかがサービスと関連付けられていない場合：
HTTP コード：404
HTTP 応答：
{
nsapi-error-response:
{
errorcode: "SERV_0003"
errormessage: "Categories could not be unlinked from the Service."
}
}

3. すべての汎用例外で、JSON 応答は次のようになります。
HTTP コード：500
HTTP 応答：
{
nsapi-error-response:
{
errorcode: "EXC_0001"
errormessage: "Some NSAPI Exception Occurred."
}
}

4. ログイン ユーザに serviceId で識別されるサービスに対する RBAC 権限がない場合：
HTTP コード：401
HTTP 応答：
{
nsapi-error-response:
{
errorcode: "NSAPI_ERROR_004"
errormessage: "The user does not have sufficient permission to perform the operation on this object."
}
}

 

5. カテゴリのリンク解除が正常に行われた場合：
HTTP コード：200
HTTP 応答：
{
status-message:
{
code: "Success"
value: "Categories Unlinking is done Successfully for the Service."
}
}

 

サービスからのファセットのリンク解除

POST REST URL：

http://<Server URL>/RequestCenter/nsapi/definition/servicedefs/id/{serviceId}/delinkFacets

ペイロードはファセット名（<facetName> は表示名ではなく、ファセットの名前）と、次の JSON 配列形式の値をとります。

{

"<facets>" :["<facet1>","<facet2>",...]

}

さまざまなシナリオにおける応答：

1. 渡された serviceId が存在しない場合：

HTTP コード：404

HTTP 応答：

{

nsapi-error-response:

{

errorcode: "SERV_0001"

errormessage: "ServiceId does not exist."

}

}

2. ファセットがサービスに関連付けられていない場合：
HTTP コード：404
HTTP 応答：
{
nsapi-error-response:
{
errorcode: "SERV_0005"
errormessage: "Facets could not be unlinked from the Service."
}
}

3. ログイン ユーザに serviceId で識別されるサービスに対する RBAC 権限がない場合：
HTTP コード：401
HTTP 応答：
nsapi-error-response:
{
errorcode: "NSAPI_ERROR_004"
errormessage: "The user does not have sufficient permission to perform the operation on this object"
}
}

 

4. すべての汎用例外で、JSON 応答は次のようになります。
HTTP コード：500
HTTP 応答：
{
nsapi-error-response:
{
errorcode: "EXC_0001"
errormessage: "Some NSAPI Exception Occurred."
}
}

5. ファセットのリンク解除が正常に行われた場合：
HTTP コード：200
HTTP 応答：
{
status-message:
{
code: "Success"
value: "Facets Unlinking is done Successfully for the Service."
}
}

 

複数値のファセットから値をリンク解除します。この API は複数値のファセットに対してのみ適用できます。

POST REST URL：

http://<Server URL>/RequestCenter/nsapi/definition/servicedefs/id/{serviceId}/delinkMultiValueFacet

ペイロードはファセット名（<facetName> は表示名ではなく、ファセットの名前）と、次の JSON 配列形式の値をとります。

{

"<facetName>" :["<facetValue1>","<facetValue2>",...]

}

さまざまなシナリオにおける応答：

1. 渡された serviceId が存在しない場合：

HTTP コード：404

HTTP 応答：

{

nsapi-error-response:

{

errorcode: "SERV_0001"

errormessage: "ServiceId does not exist."

}

}

2. ファセット値がサービスに関連付けられていない場合:

HTTP コード：404

HTTP 応答：

{

nsapi-error-response:

{

errorcode: "SERV_0005"

errormessage: "Facet values could not be unlinked from the Service."

}

}

 

3. ログイン ユーザに serviceId で識別されるサービスに対する RBAC 権限がない場合：

HTTP コード：401

HTTP 応答：

nsapi-error-response:

{

errorcode: "NSAPI_ERROR_004"

errormessage: "The user does not have sufficient permission to perform the operation on this object"

}

}

4. すべての汎用例外で、JSON 応答は次のようになります。
HTTP コード：500
HTTP 応答：
{
nsapi-error-response:
{
errorcode: "EXC_0001"
errormessage: "Some NSAPI Exception Occurred."
}
}

5. ファセット値の解除が正常に行われた場合：
HTTP コード：200
HTTP 応答：
{
status-message:
{
code: "Success"
value: "Facet Values Unlinking is done Successfully for the Service."
}
}

 

サービスからサービス拡張子をリンク解除する

POST REST URL：

http://<Server URL>/RequestCenter/nsapi/definition/servicedefs/id/{serviceId}/delinkServiceExtensions

ペイロードは次の JSON 配列形式のサービス拡張子名（<serviceExtensions> は表示名ではなく、論理名）をとります。

{

"serviceExtensions" : ["serExt1","serExt2",...]}

さまざまなシナリオにおける応答：

1. 渡された serviceId が存在しない場合：

HTTP コード：404

HTTP 応答：

{

nsapi-error-response:

{

errorcode: "SERV_0001"

errormessage: "ServiceId does not exist."

}

}

2. サービス拡張子がサービスに関連付けられていない場合:
HTTP コード：404
HTTP 応答：
{
nsapi-error-response:
{
errorcode: "SERV_0004"
errormessage: "Servce Extensions could not be unlinked from the Service."
}
}

3. ログイン ユーザに serviceId で識別されるサービスに対する RBAC 権限がない場合：
HTTP コード：401
HTTP 応答：
nsapi-error-response:
{
errorcode: "NSAPI_ERROR_004"
errormessage: "The user does not have sufficient permission to perform the operation on this object"
}
}

 

4. すべての汎用例外で、JSON 応答は次のようになります。

HTTP コード：500

HTTP 応答：

{

nsapi-error-response:

{

errorcode: "EXC_0001"

errormessage: "Some NSAPI Exception Occurred."

}

}

5. サービス拡張子のリンク解除が正常に行われた場合：

HTTP コード：200

HTTP 応答：

{

status-message:

{

code: "Success"

value: "Service Extensions Unlinking is done Successfully for the Service."

}

}

 

サービスの削除

この API は次の URL で削除するサービスの ID をとります。

http://<Server URL>/RequestCenter/nsapi/definition/servicedefs/id/{id}

HTTP メソッド：DELETE

1. サービスの削除が正常に終了した場合：

HTTP コード：200

HTTP 応答：

{

status message:

{

code: “Success”

"value": "Service with ServiceID {id} deleted successfully.”

}

}

2. 渡された serviceId が存在しない場合：

HTTP コード：404

HTTP 応答：

{

nsapi-error-response:

{

errorcode: "SERV_0001"

errormessage: "ServiceId does not exist."

}

}

3. サービスに要求があり、削除できない場合

HTTP コード：403

HTTP 応答：

{

nsapi-error-response:

{

errorcode: "SERV_0002"

errormessage: "Service Cannot be deleted since it already exists amongst requisitions"

}

}

 

4. 一般的な例外

HTTP コード：500

HTTP 応答：

{

nsapi-error-response:

{

errorcode: "EXC_0001"

errormessage: "Delete Service Failed"

}

}

5. ログイン ユーザに serviceId で識別されるサービスに対する RBAC 権限がない場合：

HTTP コード：401

HTTP 応答：

nsapi-error-response:

{

errorcode: "NSAPI_ERROR_004"

errormessage: "The user does not have sufficient permission to perform the operation on this object"

}

}

REST API

サービスのコピー

既存のアクティブ フォーム コンポーネント（AFC）とディクショナリを再利用して、またはサービスを AFC のディクショナリ、電子メール テンプレート、およびスクリプトとともに複製することによって、サービス定義をコピーします。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/definition/v1/service

サービスのコピー：

既存のアクティブ フォーム コンポーネント（AFC）およびディクショナリを再利用することで、サービス定義をコピー。

入力例：

{
"Service ID": " 88 ",
"New Service Name": " service ",
"Deep Copy": “ false ",
}

サービスの複製：

サービス内のプレフィックスを持つフォームおよびディクショナリをすべてコピー。

入力例：

{
"Service ID": " 88 ",
"New Service Name": " service ",
"Deep Copy": " true ",
"Form Name Prefix": " NewForm ",
"Dictionary Name Prefix": " NewDictionary "
}

サービス内の必要なフォームおよび AFC のみをコピー。

入力例：

{
"Service ID": " 88 ",
"New Service Name": " service ",
"Deep Copy": " true ",
"Forms":{
"Old form name":{
"New Form Name": " Deep Copy Form ",
"New Form Group Name": " Deep copy form group ",
"Dictionaries":{
"Old dictionary name":{
"New Dictionary Name": " Deep_Copy_Dictionary ",
"New Dictionary Group Name": " new group "
}
}
}
},
}
 
 

エージェント（Agents）

 

表 3-9 エージェント API テーブル
領域
例

コア API

エージェントの停止

アクティブなサービス リンク エージェントを停止します。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/definition/agent/<agent name>/stop

エージェントの起動

非アクティブなサービス リンク・エージェントを起動します。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/definition/agent/<agent name>/start

応答 XML
Agent<agent name> <started/stopped> successfully

 

表 3-10 エージェント API テーブル

領域
例

コア API

すべてのエージェントの取得

すべてのエージェントが返されます。

GET REST URL：

http://<ServerURL>/RequestCenter/nsapi/definition/agents

Java の例

AgentList agents = NSApiClient.getDefinition().getAgents(null);

 

Id によるエージェントの取得

発信および着信のプロパティは、getById および getByName の場合にのみ取得されます。

GET REST URL：

http://<ServerURL>/RequestCenter/nsapi/definition/agents/id/<agentId>

Java の例

Agent agents = NSApiClient.getDefinition().getAgentById(<agentId>);

 

Name によるエージェントの取得

発信および着信のプロパティは、getById および getByName の場合にのみ取得されます。

GET REST URL：

http://<ServerURL>/RequestCenter/nsapi/definition/agents/name/<agentName>

Java の例

Agent Agents = NSApiClient.getDefinition().getAgentByName("<agentName>");

 

エージェントのステータスの取得

エージェントのステータスを取得します。

GET REST URL：

http://<ServerURL>/RequestCenter/nsapi/definition/agent/<agentName>/status

フィルタ

エージェント名フィルタ

検索では大文字と小文字が区別されます。

StartsWith（newscale.properties の ContainsQueryInFnS=false）：先頭のワイルドカードは無視されます。

Contains（newscale.properties の ContainsQueryInFnS=true）：先頭のワイルドカードは、必要に応じて指定してください。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/agents?name=<wild cardValue>

Java の例

AgentList agents = NSApiClient.getDefinition().getAgentsByFilter("<wildcardValue>");

ソート カラム

AgentName

応答 XML
<agents totalCount="x" recordSize="y" startRow="z">
<agent>
...
</agent>
</agents>

契約

表 3-11 契約 API テーブル

領域
例

APIs の取得

Id による契約の取得

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/agreements/id/<agreementId>

 

Name による契約の取得

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/agreements/name/<agreementName>

 

すべてのマスター契約の取得

すべてのマスター契約が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/agreements/master

 

すべてのプロジェクト契約の取得

すべてのプロジェクト契約が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/agreements/project

 

アカウント名のすべての契約を取得

そのアカウント名のすべての契約が返されます（完全一致、大文字小文字は区別されません）。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/agreements/accountname/{accountName}

 

アカウント名の契約の取得

そのアカウント名の契約が返されます（アカウント名はこの領域で必須です）。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/agreements/name/{agreementname}?&accountName={accountName}

ソート カラム（s）

AgreementName

応答 XML
<agreements totalCount="x" recordSize="y" startRow="z">
<agreement>
...
</agreement>
</agreements>

表 3-12 使用シナリオ テーブル

領域
例

他の使用シナリオ

アカウント下のすべての OU の取得

このアカウントで関連付けられているすべての OU が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/agreements/agreementorgunitlist?&accountName={accountName}

 

契約の作成

REST URL (HTTP POST): http://<ServerURL>/RequestCenter/nsapi/definition/agreements/create

<agreement agreementId="123" name="Sample Agreement Name">
parentAgreementName="Sample Parent Agreement Name" >
<description>Sample Agreement Description</description>
<agreementTemplateName>Sample Agreement Template Name</agreementTemplateName>
</agreement>

 

契約の削除

REST URL (HTTP DELETE): http://<ServerURL>/RequestCenter/nsapi/definition/agreements/delete

<agreement agreementId="123" name="Sample Agreement Name">
</agreement>

 

契約の更新

REST URL (HTTP PUT):

http://<ServerURL>/RequestCenter/nsapi/definition/agreements/update

<agreement agreementId="123" name="Sample Agreement Name"
accountName="Sample Account Name" parentAgreementName="Sample Parent Agreement Name">
<description>Sample Agreement Description</description>
<agreementAttributes>
<agreementAttribute serviceItemTypeName="Sample Service Item Type Name 1"
aggregateFunction="Count" serviceItemAttribute="" quota="123" />
<agreementAttribute serviceItemTypeName="Sample Service Item Type Name 2"
aggregateFunction="Count" serviceItemAttribute="" quota="456" />
<agreementAttribute serviceItemTypeName="Sample Service Item Type Name 2"
aggregateFunction="Sum" serviceItemAttribute="Sample Attribute Name" quota="789" />
</agreementAttributes>
<organizationalUnits>
<organizationalUnit>
<organizationalUnitName>Sample OU Name</organizationalUnitName>
<organizationalUnitType>Business Unit</organizationalUnitType>
</organizationalUnit>
</organizationalUnits>
</agreement>

課金レート

課金レート グループ

 

表 3-13 課金レート グループ API テーブル

領域
例

Core API

すべての課金レート グループの取得

すべての課金レート グループが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/rategroups

ID によるレート グループの取得

ID により課金レート グループが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/rategroups/id/{id}

名前によるレート グループの取得

名前により課金レート グループが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/rategroups/name/{name}

 

ワイルド カード名前検索によるレート グループの取得

ワイルド カード名前検索により課金レート グループが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/rategroups?name={wild card name}

 

レート グループの作成（1 レート グループ オブジェクトのみ）

REST URL (HTTP POST):

http:// <ServerURL>/RequestCenter/nsapi/definition/billing/rategroups/create

POST DATA:

<rateGroup name=”Sample Rate Group” description=”Sample rate group description”>

<rateTables>

<rateTable id=”1” name=”First”/>

<rateTable id=”2” name=”Second”/>

<rateTable id=”3” name=”Third”/>

</rateTables>

</rateGroup>

 

レート グループの更新（1 レート グループ オブジェクトのみ）

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/rategroups/update

本文

<rateGroup id=”123” name=”Sample Rate Group” description=”Sample rate group description”>

<rateTables>

<rateTable id=”1” name=”First”/>

<rateTable id=”2” name=”Second”/>

<rateTable id=”3” name=”Third”/>

</rateTables>

</rateGroup>

 

レート グループの削除（1 レート グループ オブジェクトのみ）

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/rategroups/delete

BODY:

<rateGroup id=”123” name=”Sample Rate Group Name” />

課金レート定義

表 3-14 課金レート定義 API テーブル

領域
例

 

グループ名によるすべての課金レート テーブルの取得

ID、名前、説明、サービス項目タイプの ID と名前を持つレート テーブルの軽量オブジェクトが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/ratetables/rategroupname/{groupName}

 

グループ ID によるすべての課金レート テーブルの取得

ID、名前、説明、サービス項目タイプの ID と名前を持つレート テーブルの軽量オブジェクトが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/ratetables/rategroupid/{groupID}

 

名前によるレート テーブル定義またはスキーマ詳細の取得

名前によるレート テーブル定義またはスキーマ詳細が返されます。属性と操作情報が付いた完全なレート テーブル定義が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/ratetables/schema/name/{name}

 

ID によるレート テーブル定義またはスキーマ詳細の取得

属性と操作情報が付いた完全なレート テーブル定義が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/ratetables/schema/id/{id}

 

ワイルドカード名前検索によるレート テーブルの取得

ID、名前、説明、グループ ID と名前、サービス項目タイプ ID と名前を持つレート テーブルの軽量オブジェクトが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/ratetables/schema?name={wild card name}

 

レート テーブル スキーマの作成（1 レート テーブル オブジェクトのみ）

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/ratetables/schema/create

<rateTable id=”" name=”Sample Rate Table” logicName=”SampleRateTable” description=”Sample Rate Table Description”>

<rateGroup id=”123” name=”Sample Rate Group Name”/>

<serviceItemType id=”123” name=”Sample Service Item Type Name”/>

<billingAttributes>

<attribute name="Attribute Name 1" billingField=”true” memoField=”false”/>

<attribute name="Attribute Name 2" billingField =”false” memoField =”false”/>

<attribute name="Attribute Name 3" billingField =”true” memoField =”false”/>

</billingAttributes>

<billingOperations>

<operation name="Operation1" applicable=”false”/>

<operation name="Operation2" applicable =”true”/>

<operation name="Operation3" applicable =”true”/>

</billingOperations>

</rateTable>

 

レート テーブル スキーマの更新（1 レート テーブル オブジェクトのみ）

課金レート テーブル スキーマを更新します（1 レート テーブル オブジェクトのみ）。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/ratetables/schema/update

<rateTable id=”123" name=”Sample Rate Table” logicName=”BiSampleRateTable” description=”Sample Rate Table Description”>

<rateGroup id=”123” name=”Sample Rate Group Name”/>

<serviceItemType id=”123” name=”Sample Service Item Type Name”/>

<billingAttributes>

<attribute name="Attribute Name 1" billingField=”true” memoField=”false”/>

<attribute name="Attribute Name 2" billingField =”false” memoField =”false”/>

<attribute name="Attribute Name 3" billingField =”true” memoField =”false”/>

</billingAttributes>

<billingOperations>

<operation name="Operation1" applicable=”false”/>

<operation name="Operation2" applicable =”true”/>

<operation name="Operation3" applicable =”true”/>

</billingOperations>

</rateTable

 

レート テーブル スキーマの削除（1 レート テーブル オブジェクトのみ）

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/ratetables/schema/delete

<rateTable id=”123" name=”Sample Rate Table” logicName="BiSampleRateTable" />

課金レート データ

表 3-15 課金レート データ API テーブル

領域
例

 

レート テーブル名によるレート テーブル データの取得

レート テーブル 名により課金レート テーブルのデータが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/ratetables/data/tablename/{tableName}

 

レート テーブル ID によるレート テーブルの取得

レート テーブル ID により課金レート テーブルのデータが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/ratetables/data/tableid/{tableID}

 

レート テーブル データの更新（1 レート テーブル オブジェクトのみ）

レート テーブル データの既存のエントリが消去され、特定の入力データを挿入します（「置換」などの作業）。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/billing/ratetables/data/update

<rateTableData id=”123” name=”Sample Rate Table” logicName=”BiSampleRateTable”>

<rateTableRecord rate=”123.45” rateCode=”RateCode1” unitOfMeasure=”Per Month”>

<attributes>

<attribute name="Attribute Name

1">Value1</attribute>

<attribute name="Attribute Name

2">Value2</attribute>

<attribute name="Attribute Name

3">Value3</attribute>

</attributes>

</rateTableRecord>

<rateTableRecord rate=”456.78” rateCode=”RateCode2” unitOfMeasure=”Per Week”>

<attributes>

<attribute name="Attribute Name

11">Value11</attribute>

<attribute name="Attribute Name

12">Value12</attribute>

<attribute name="Attribute Name

13">Value13</attribute>

</attributes>

</rateTableRecord>

</rateTableData

フィルタ
  • URL で許可されるパラメータ：URL で許可されるパラメータは startRow、recordSize、sortBy、sortDir、および responseType（xml または json）です。
  • 「RateGroup」および「RateTable」での検索 URL：ソートを実行するカラムとソート順を指定するには、「sortBy」および「sortDir」クエリー パラメータを使用できます。「sortBy」が空または無効なカラム名である場合、デフォルトのソートは「ID」に対する「昇順」です。
  • 「RateTableData」での検索 URL：デフォルトのソートは「ID」に対する「降順」です。「sortBy」および「sortDir」クエリー パラメータはサポートされません。
  • ワイルド カード検索では「starts-with」が使用でき、パフォーマンス上の理由から contains クエリーおよび先頭のワイルド カード検索はできません。
  • レート テーブル スキーマの作成/更新では、レート グループおよびサービス項目タイプは名前に基づきます。ID がある場合、ID と名前の組み合わせのクロスチェックを試みた後に、更新または削除を実行します。
  • レート グループまたはレート テーブルの更新/削除では、ID があれば ID に基づきます。ID がない場合は名前に基づきます。
  • レート テーブル スキーマ検索では、属性は「課金」または「メモ」フィールドとして選択されている場合にのみ取得されます。また、操作は適用可能と選択された場合にのみ取得されます。
  • レート テーブル スキーマの作成では、レート グループ名およびサービス項目タイプ名は必須であり、ID は任意選択です。ID がある場合は、レート テーブルの作成前に ID と名前の組み合わせがクロスチェックされます。
  • レート テーブル スキーマの更新では、属性または操作は、それらが入力オブジェクトに指定された場合にのみ更新されます（選択または選択解除）。そうでない場合は、既存の属性や操作を変更しないでそのままにしておきます。
  • レート テーブル データの更新では、レート テーブル データの既存のレコードがすべて削除され、入力 XML/JSON のレコードがレート テーブル データとして保存されます。
  • 課金履歴ポートレット UI のすべての検証が、すべての作成、更新、削除に対して実行されます。

ソート カラム

ソートは URL で許可される 2 つのカラム（「ID」または「名前」）で可能です。

応答 XML

軽量レート グループ リストの XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

<rateGroups recordSize="2" startRow="1" totalCount="2">

<rateGroup id="11" name="Sample Rate Group 1" description="First group" />
<rateGroup id="22" name="Sample Rate Group 2" description="Second group" />
</rateGroups>
 

単一 レート グループ取得の XML

レート グループの更新要求のペイロードと同じ

グループの ID または名前により取得される軽量レート テーブル リストの XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rateTables recordSize="2" startRow="1" totalCount="2">
<rateTable id="12" name="Small scale Rate Table" logicName="BiSmallscaleRateTable" description="Rate table for small scale businesses">
<serviceItemType id="6" name="Laptop"/>
</rateTable>
<rateTable id="22" name="Large scale Rate Table" logicName="BiLargescaleRateTable" description="Rate table for large scale businesses">
<serviceItemType id="4" name="Desktop"/>
</rateTable>
</rateTables>
 

単一レート スキーマ取得の XML

レート グループの更新要求のペイロードと同じ

 

レート テーブル データ取得の XML:

レート グループの更新要求のペイロードと同じ

オーダー管理

表 3-16 オーダー管理 API テーブル

領域
例

GET API

要求の情報の取得

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/v1/ordermgmt/reqinfo/reqid/{reqId}

サンプル出力：

[
{
"Status":"Cancelled",
"OrgUnit":"<s ID=\"847\"/>",
"CustomerPhone":null,
"Customer":"Customer1",
"Initiator":"Initiator1",
"CustomerEmail":null,
"CreatedDate":"5/26/16 7:46 AM",
"ClosedDate":"05/26/2016",
"ReqNo":"1",
"SubmittedDate":"05/26/2016"
}
]

 

要求のためのサービスの情報を取得

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/v1/ordermgmt/servicenfo/reqid/{reqId}

サンプル出力：

[
{
"Status":"<s ID=\"68\" />",
"StdDuration":null,
"UnitCost":"0.0",
"Qty":"1",
"Subtotal":"0.0",
"Name":"TestsService",
"ServiceLevelDesc":null
},
{
"TotalCost":"0.0"
}
]

 

要求に関するすべてのシステム コメントおよびユーザ コメントを取得

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/v1/ordermgmt/comments/reqid/{reqId}

[
[
{
"CommentText":"Comment",
"Name":"admin admin",
"On":"Mon Jun 27 03:29:00 PDT 2016"
}
],
[
{
"CommentText":"admin admin cancelled the requisition 20.",
"Name":"admin admin",
"On":"Tue Jun 14 09:04:49 PDT 2016"
}
]
]

 

要求のすべての添付ファイルの詳細を取得

REST URL:

URL: http://<ServerURL>/RequestCenter/nsapi/definition/v1/ordermgmt/attachmentslist/reqid/{reqId}

サンプル出力：

[
{
"UploadDate":"05/26/2016",
"DocSize":"881304",
"DocumentId":"1",
"DocumentName":"file.txt"
}
]

 

要求のドキュメント ID を使用して添付ファイルをダウンロード

REST URL:

URL: http://<ServerURL>/RequestCenter/nsapi/definition/v1/ordermgmt/attachment/viewdocid/{document Id}

サンプル出力：

downloads the file

 

ログイン中のユーザがオーダーできるすべてのサービス ID を取得

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/v1/orderableserviceids

サンプル出力：

{
"Clone Container": 1015,
"Cassandra Cluster App (v2.1.1)": 1086,
"Add Cloud Center User": 1081,
"API_Service": 1091
}

 

ログイン中のユーザがログイン ID がわかっている顧客に代わってオーダーできるすべてのサービスを取得

REST URL:

http://<ServerURL>/RequestCenter/nsapi/definition/v1/orderableserviceids/customerlogin/{customerlogin}

出力例：：

{
“1Service:: 2
}

ポリシー

領域
例

コア API

サービス項目タイプによるポリシーの取得

サービス項目タイプの名前によりポリシーが返されます。

REST URL:

/RequestCenter/nsapi/serviceitem/definition/{ serviceItemTypeName }/policies

XML 応答：

<policies totalCount="2" startRow="1" recordSize="2">

<policy policyType="quota" accountName="bangalore" policyEnabled="true" executionOrder="2" dataTypeLogicName="SiLaptop" policyTemplateLogicName="quotacheck" policyId="34" name="Laptop Quota policy">

<description>

</description>

<policyParamValues>

<paramValue policyParamLogicName="quotacheck-serviceitemattribute" paramValue="Quota"/>

<paramValue policyParamLogicName="quotacheck-quotathreshold" paramValue="90"/>

</policyParamValues>

<policyActions>

<policyAction policyActionTemplateName="orderservice" executionOrder="1">

<actionParamValues>

<actionParamValue policyActionTemplateParamLogicName="orderservice-servicename" actionParamValue="Apple iPhone"/>

<actionParamValue policyActionTemplateParamLogicName="orderservice-initiatorname" actionParamValue="admin"/>

<actionParamValue

policyActionTemplateParamLogicName="orderservice-customername" actionParamValue="admin"/>

<actionParamValue policyActionTemplateParamLogicName="orderservice-billtoOU" actionParamValue="Site Administration"/>

<actionParamValue

 

policyActionTemplateParamLogicName="orderservice-sections">

<dictionary name="TabletComputerDict">

<fields/>

</dictionary>

</actionParamValue>

</actionParamValues>

</policyAction>

</policyActions>

</policy>

<policy policyType="update" accountName="bangalore" policyEnabled="true" executionOrder="1" dataTypeLogicName="SiLaptop" policyTemplateLogicName="updatecheckchange" policyId="33" name="Laptop Policy">

<description>

</description>

<policyParamValues>

<paramValue policyParamLogicName="updatecheckchange-serviceitemattribute" paramValue="Price"/>

</policyParamValues>

<policyActions>

<policyAction policyActionTemplateName="policyalert" executionOrder="1">

<actionParamValues>

<actionParamValue policyActionTemplateParamLogicName="errormessage" actionParamValue="Policy alert when Price is updated for a Laptop"/>

</actionParamValues>

</policyAction>

</policyActions>

</policy>

</policies>

 
ServiceitemtypeName および PolicyID によるポリシーの取得
 
ServiceitemtypeName およびポリシー ID によりポリシーが返されます。
 

REST URL:

/RequestCenter/nsapi/serviceitem/definition/{serviceItemTypeName }/policies/id/{policyId}

 
ServiceItemTypeName、PolicyName、PolciyType によるポリシーの取得
 

serviceItemTypeName、ポリシー名、ポリシー タイプによりポリシーが返されます。

 

REST URL:

 

/RequestCenter/nsapi/serviceitem/definition/{ serviceItemTypeName}/policies/name/{name}?policyType={ capacity, quota, time}
 
Example: http://localhost:8088/RequestCenter/nsapi/serviceitem/definition/Laptop/policies/name/Laptop Policy?policyType=update
 
注：「policyType」クエリ パラメータに許可される入力値は次のとおりです。
capacity/quota/time/update

XML 応答：

<policy policyType="update" accountName="bangalore" policyEnabled="true" executionOrder="1" dataTypeLogicName="SiLaptop" policyTemplateLogicName="updatecheckchange" policyId="33" name="Laptop Policy">

<description>

</description>

<policyParamValues>

<paramValue policyParamLogicName="updatecheckchange-serviceitemattribute" paramValue="Price"/>

</policyParamValues>

<policyActions>

<policyAction policyActionTemplateName="policyalert" executionOrder="1">

<actionParamValues>

<actionParamValue policyActionTemplateParamLogicName="errormessage"

actionParamValue="Policy alert when Price is updated for a Laptop"/>

</actionParamValues>

</policyAction>

</policyActions>

</policy>

エラー応答

<nsapi-error-response>

No policy found for this name (Laptop ABCD Policy) and for policyType (update).

</nsapi-error-response>
領域
例

POST

特定の ServiceItemTypename のポリシーの作成

POST URL:

/RequestCenter/nsapi/serviceitem/definition/{serviceItemTypeName}/policies/create

入力 XML：

<policy policyType="update" accountName="bangalore" policyEnabled="true" executionOrder="1" dataTypeLogicName="SiLaptop" policyTemplateLogicName="updatecheckchange" policyId="33" name="Laptop Policy">

<description>

</description>

<policyParamValues>

<paramValue policyParamLogicName="updatecheckchange-serviceitemattribute" paramValue="Price"/>

</policyParamValues>

<policyActions>

<policyAction policyActionTemplateName="policyalert" executionOrder="1">

<actionParamValues>

<actionParamValue policyActionTemplateParamLogicName="errormessage"

actionParamValue="Policy alert when Price is updated for a Laptop"/>

</actionParamValues>

</policyAction>

</policyActions>

</policy>
 

応答 XML：

<nsapi-response>

<status-message code="POLICY_SUCCESS_003">

<value>Policy created successfully.</value>

</status-message>

</nsapi-response>

PUT
特定の ServiceItemTypename のポリシーの更新
 
PUT URL:
 
/RequestCenter/nsapi/serviceitem/definition/{serviceItemTypeName}/policies/update
 

入力 XML：

<policy policyType="update" accountName="bangalore" policyEnabled="true" executionOrder="1" dataTypeLogicName="SiLaptop" policyTemplateLogicName="updatecheckchange" policyId="33" name="Laptop Policy">

<description>

</description>

<policyParamValues>

<paramValue policyParamLogicName="updatecheckchange-serviceitemattribute" paramValue="Price"/>

</policyParamValues>

<policyActions>

<policyAction policyActionTemplateName="policyalert" executionOrder="1">

<actionParamValues>

<actionParamValue policyActionTemplateParamLogicName="errormessage"

actionParamValue="Policy alert when Price is updated for a Laptop"/>

</actionParamValues>

</policyAction>

</policyActions>

</policy>
 

応答 XML：

<nsapi-response>

<status-message code="POLICY_SUCCESS_003">

<value>Policy updated successfully.</value>

</status-message>

</nsapi-response>

DELETE
PolicyID または PolicyName による特定の ServiceItemTypename のポリシーの削除
 
DELETE URL:
 
/RequestCenter/nsapi/serviceitem/definition/{serviceItemTypeName}/policies/delete

入力 XML：

ポリシー名により削除するには、次のように入力します。

<policy policyType="quota" name="Laptop Quota policy Fourth">

</policy>

ポリシー ID により削除するには、次のように入力します。

<policy policyId="38">

</policy>
 

応答：

<nsapi-response>

<status-message code="POLICY_SUCCESS_002">

<value>Policy deleted successfully.</value>

</status-message>

</nsapi-response>
 

ディレクトリ データ

個人（Person）

 

表 3-17 個人 API テーブル

領域
例

コア API

すべての人の取得

すべての人が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/people

Java の例

PersonList person = NSApiClient.getDirectory().getPeople(null);

 

Id による個人の取得

指定した Person Id を持つ個人が返されます。

ネストされたエンティティ（OU、グループ、ロール、住所、連絡先、および設定）が取得されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/people/id/<personId>

Java の例

Person persons = NSApiClient.getDirectory().getPersonById(<personId>);

 

LoginName による個人の取得

指定した LoginName を持つ個人が返されます。

ネストされたエンティティ（OU、グループ、ロール、住所、連絡先、および設定）が取得されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/people/loginname/<loginName>

Java の例

Person persons = NSApiClient.getDirectory().getPersonByLoginName("<loginName>");

 

ログイン ユーザの取得

現在ログインしている個人が返されます。

REST URL:

http://<serverURL>/RequestCenter/nsapi/directory/people/currentuser

Java の例

Person person = NSApiClient.getDirectory().getCurrentUser();

 

ログイン名がわかっている場合に、個人にロールを割り当てる、または割り当てを解除する

REST URL: /nsapi/directory/people/{loginname}/roles

Method: POST

サンプル ペイロード/本文：

{

"rolemapping":

{

"operation":"assign",

"roles":["My Role",”Tenant User”],

}

}

operation に指定可能な値：「assign」または「unassign」

成功応答：200

エラー応答：400 bad request

特殊な条件

個人の作成/更新

個人を取得（GET）する前述の REST URL のいずれかの応答から、個人 XML を取得します。

個人を更新する REST URL に対して個人 XML を POST することによって、個人の作成または変更を行います。

（XML のログインまたは personId で識別される）個人が存在する場合は更新操作が実行され、そうでない場合は新規個人が作成されます。

作成操作には、次の 5 つの要素が必要です。

  • firstName
  • lastName
  • homeOrganizationalUnitName
  • 電子メール（e-mail）
  • ログイン

作成操作では、個人のパスワードにログイン名が設定されます。

更新操作でホーム OU に対する変更を行うと、個人のホーム OU が置換されます。関連付けられている他の OU、グループ、およびロールは、作成操作でも更新操作でも無視されます。

ホーム OU、タイムゾーン、ロケール、スーパーバイザ、代理承認者、ログイン モジュール、連絡先、および住所の各属性には、次のルールが適用されます。

  • id 要素が XML で送信されたがデータベースには見つからなかった場合、例外がスローされ、該当するメッセージが示されます。
  • id 要素が見つからなかった場合は、XML で送信された Name 要素が代わりに使用されます。その名前がデータベースに見つからなかった場合は、例外がスローされます。
  • id または name 要素のいずれも XML 内に存在せず、属性がオプションである場合、その属性は作成/更新操作で無視されます（HomeOU は必須です）。
  • XML で送信されたデータに誤りや欠落があったために作成または更新操作が失敗した場合、HTTP ステータス コード「422 Unprocessable Entity」が返されます。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/directory/people/update

Java の例

Person person = NSApiClient.getDirectory().getPersonById(<personId>);
person.setLastName("<lastName>");
Person persons = NSApiClient.getDirectory().updatePerson(person);

フィルタ

OU 名フィルタ

検索では大文字と小文字が区別され、完全一致が使用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/people?ouname=<ouName>

Java の例

MultiValueMap paramsMap = new MultiValueMap();
paramsMap.put("ouname", "<ouName>");
PersonList person = NSApiClient.getDirectory().getPeople(paramsMap);

 

グループ名フィルタ

検索では大文字と小文字が区別され、完全一致が使用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/people?groupname=<groupName>

Java の例

MultiValueMap paramsMap = new MultiValueMap();s
paramsMap.put("groupname", "<groupName>");
PersonList person = NSApiClient.getDirectory().getPeople(paramsMap);

 

ロール名フィルタ

検索では大文字と小文字が区別され、完全一致が使用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/people?rolename=<roleName>

Java の例

MultiValueMap paramsMap = new MultiValueMap();
paramsMap.put("rolename", "<roleName>");
PersonList person = NSApiClient.getDirectory().getPeople(paramsMap);

ソート カラム

[姓（First Name）]、[名（Last Name）]、[ログイン名（Login Name）]

XML 応答
<people totalCount="x" recordSize="y" startRow="z">
<person>
...
<contacts>
...
<contact>
<contactId></contactId>
<contactType></contactType>
<contactTypeId></contactTypeId>
<value></value>
</contact>
...
</contacts>
...
</person>

</people>

組織

 

表 3-18 組織単位 API テーブル

領域
例

コア API

すべての組織単位の取得

すべての組織単位が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/organizationalunits

Java の例

OrganizationalUnitList Ou = NSApiClient.getDirectory().getOrganizationalUnits(null);

 

Id による組織単位の取得

ネストされたエンティティ（下位の組織単位）は、getById および getByName の場合にのみ取得されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/organizationalunits/id/<ouId>

Java の例

OrganizationalUnit Ou = NSApiClient.getDirectory().getOrganizationalUnitById(ouId);

 

Name による組織単位の取得

ネストされたエンティティ（下位の組織単位）は、getById および getByName の場合にのみ取得されます。

同じ名前でタイプが異なる OU が 2 つ見つかった場合は、サービス チーム OU が返されます。

オプションのパラメータ ?type=<BusinessUnit/serviceTeam> も指定できます（「all」はタイプ パラメータ値では許可されません）。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/organizationalunits/name/<ouName>

Java の例

OrganizationalUnit Ou = NSApiClient.getDirectory().getOrganizationalUnitByName("<ouName>");

 

Type による OU の取得

指定した OU タイプの組織単位がすべて返されます。

指定可能な値：「all」、「BusinessUnit」、「ServiceTeam」。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/organizationalunits?type=<ouType>

Java の例

OrganizationalUnitList Ou = NSApiClient.getDirectory().getOrganizationalUnitByType("<ouType>");

 

親組織には割り当てずに、タイプが事業単位（BusinessUnit）の組織単位を作成する

REST URL: nsapi/directory/organizationalunits

Method: PUT

サンプル ペイロード/本文：

{

"organizationalunit": {

"description": "Details about Tail-f",

"isBillable": "true",

"organizationalUnitName": "Tail-f",

"organizationalUnitType": "BusinessUnit",

"status": "Active"

}

}

成功応答：201 created

エラー応答：400 bad request

 

親組織に割り当てずに、タイプがサービス チーム（ServiceTeam）の組織単位を作成する

REST URL: nsapi/directory/organizationalunits

Method: PUT

サンプル ペイロード:

{

"organizationalunit": {

"description": "Automobile company,

"isBillable": "true",

"organizationalUnitName": "Tail-f",

"organizationalUnitType": "ServiceTeam",

"status": "Active"

}

}

成功応答：201 created

エラー応答：400 bad request

 

ステータスが非アクティブでタイプが事業単位（BusinessUnit）の組織単位を作成する

REST URL: nsapi/directory/organizationalunits

Method: PUT

サンプル ペイロード:

{

"organizationalunit": {

"description": "Automobile company",

"isBillable": "true",

"organizationalUnitName": "Ferrari",

"organizationalUnitType": "BusinessUnit",

"status": "Inactive"

}

}

成功応答：201 created

エラー応答：400 bad request

 

ステータスがアクティブで、タイプが事業単位（BusinessUnit）の組織単位を作成し、親組織単位に関連付ける

REST URL: nsapi/directory/organizationalunits

Method: PUT

サンプル ペイロード:

{

"organizationalunit": {

"description": "Automobile company",

"isBillable": "true",

"organizationalUnitName": "Hero Honda",

"organizationalUnitType": "BusinessUnit",

"status": "Active",

"parentId": "8",

"parentName": "Honda"

}

}

成功応答：201 created

エラー応答：400 bad request

 

組織単位を更新するが、親組織単位には関連付けない

更新操作により、説明、OUName、OUType、およびステータスを更新できます。

REST URL: nsapi/directory/organizationalunits

Method: POST

サンプル ペイロード:

{

"organizationalunit": {

"description": "Automobile company",

"organizationalUnitId": "19",

"isBillable": "true",

"organizationalUnitName": "f-tail",

"organizationalUnitType": "ServiceTeam",

"organizationalUnitTypeId": "1",

"status": "Active"

}

}

成功応答：200 created

エラー応答：400 bad request

 

親組織単位に関連付けられている組織単位を更新する

更新操作により、説明、OUName、OUType、ステータス、および親組織を更新できます。

REST URL: nsapi/directory/organizationalunits

Method: POST

サンプル ペイロード:

{

"organizationalunit": {

"description": "Automobile company",

"organizationalUnitId": "5",

"isBillable": "false",

"organizationalUnitName": "Aveeno",

"organizationalUnitType": "BusinessUnit",

"organizationalUnitTypeId": "2",

"status": "Active",

"parentId": "16",

"parentName": "Mazda23"

}

}

成功応答：200 created

エラー応答：400 bad request

 

OU 名がわかっている場合に、組織単位にロールを割り当てる、または割り当てを解除する

REST URL: nsapi/directory/organizationalunits/name/{OUname}/roles

Method: POST

サンプル ペイロード:

{

"rolemapping":

{

"operation":"assign",

"roles":["My Role",”Tenant User”],

"type":"ServiceTeam"

}

}

タイプに指定可能な値：「BusinessUnit」または「ServiceTeam」

operation に指定可能な値：「assign」または「unassign」

成功応答：200 created

エラー応答：400 bad request

 

OU ID がわかっている場合に、組織単位にロールを割り当てる、または割り当てを解除する

REST URL: nsapi/directory/organizationalunits/name/{OUID}/roles

Method: POST

サンプル ペイロード:

{

"rolemapping":

{

"operation":"assign",

"roles":["My Role",”Tenant User”],

"type":"ServiceTeam"

}

}

type に指定可能な値：「BusinessUnit」または「ServiceTeam」

operation に指定可能な値：「assign」または「unassign」

成功応答：200 created

エラー応答：400 bad request

フィルタ

組織単位名フィルタ

検索では大文字と小文字が区別されます。

StartsWith（newscale.properties の ContainsQueryInFnS=false）：先頭のワイルドカードは無視されます。

Contains（newscale.properties の ContainsQueryInFnS=true）：先頭のワイルドカードは、必要に応じて指定してください。

ワイルドカードの名前検索では、オプションのパラメータ ?type=<businessUnit/serviceTeam> を指定することもできます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/organizationalunits?name=<wildcardValue>

Java の例

OrganizationalUnitList Ou = NSApiClient.getDirectory().getOrganizationalUnitsByFilter("<wildcardValue>");

ソート カラム

Organizational Unit Name

応答 XML
<organizationalunits totalCount="x" recordSize="y" startRow="z">
<organizationalunit>
...
</organizationalunit>
</organizationalunits>

グループ（Groups）

 

表 3-19 グループ API テーブル

領域
例

コア API

すべてのグループの取得

すべてのグループが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/groups

Java の例

GroupList groups = NSApiClient.getDirectory().getGroups(null);

 

Id によるグループの取得

ネストされたエンティティ（サブグループ）は、getById および getByName の場合にのみ取得されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/groups/id/<groupId>

Java の例

Group groups = NSApiClient.getDirectory().getGroupsById(<groupId>);

 

Name によるグループの取得

ネストされたエンティティ（サブグループ）は、getById および getByName の場合にのみ取得されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/groups/name/<groupName>

Java の例

Group groups = NSApiClient.getDirectory().getGroupsByName("<groupName>");

 

グループの作成

REST URL: nsapi/directory/groups

Method: PUT

サンプル ペイロード/本文：

{

“group”:

{

“groupName”: “Test”, “description”, “Test Group”, “status”: “Active”

}

}

成功応答：201 created

エラー応答：400 bad request

 

グループを作成し、親 ID に関連付ける

REST URL: nsapi/directory/groups

Method: PUT

サンプル ペイロード:

{

“group”:

{

“groupId”: “1”, “groupName”: “TestP”, “parentId”: “1”, “parentName”: “ABCGroup”

}

}

成功応答：201 created

エラー応答：400 bad request

 

グループ ID を使用してグループを更新する - 名前、説明、ステータスを更新する

REST URL: nsapi/directory/groups

Method: POST

サンプル ペイロード:

{

“group”:

{

“groupId”: “14”, “groupName”: “DRMGroup”, “status”: “Active”

}

}

成功応答：200 OK

エラー応答：400 bad request

 

グループ ID を使用してグループを更新し、新しい親グループに関連付ける - 名前、説明、ステータスを更新し、親グループと関連付ける

REST URL: nsapi/directory/groups

Method: POST

サンプル ペイロード:

{

“group”:

{

“groupId”: “14”, “groupName”: “NimbusGroup”, “status”: “Active”, “parentId”: “22, “parentName”: “XYZGroup”

}

}

成功応答：200 OK

エラー応答：400 bad request

 

グループにロールを割り当てる、または割り当てを解除する

REST URL: nsapi/directory/groups/name/{groupname}/roles

Method: POST

サンプル ペイロード:

{

"rolemapping":

{

"operation":"assign",

"roles":["My Role"],

}

}

operation に指定可能な値：「assign」または「unassign」

成功応答：200 created

エラー応答：400 bad request

フィルタ

グループ名フィルタ

検索では大文字と小文字が区別されます。

StartsWith（newscale.properties の ContainsQueryInFnS=false）：先頭のワイルドカードは無視されます。

Contains（newscale.properties の ContainsQueryInFnS=true）：先頭のワイルドカードは、必要に応じて指定してください。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/groups?name=<wild cardValue>

Java の例

GroupList groups = NSApiClient.getDirectory().getGroupsByFilter("<wildcardValue>");

ソート カラム

グループ名

応答 XML
<groups totalCount="x" startRow="y" recordSize="z">
<group>
...
</group>
<groups>

アカウント

表 3-20 アカウント API テーブル

領域
例

Core API

すべてのアカウントの取得

すべてのアカウントが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/accounts

ID によるアカウントの取得

ID によりアカウントが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/accounts/id/{id}

名前によるアカウントの取得

名前によりアカウントが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/accounts/name/{name}

 

ワイルド カードを使用した名前によるアカウントの取得

検索対象のアカウントが返されます。

REST URL (HTTP POST):

http://<ServerURL>/RequestCenter/nsapi/directory/accounts?name={wild card name}

他の使用シナリオ

アカウントを作成または更新します（1 アカウント オブジェクトのみ）。

REST URL(HTTP POST): http://<ServerURL>/RequestCenter/nsapi/directory/accounts/update

<account>

<name>Sample Account Name</name>

<accountId>123</accountId>

<accountType>Project Account</accountType>

<description>Sample Account Description</description>

<billingRateGroup>Sample Rate Group Name</billingRateGroup>

<organizationalUnits>

<organizationalUnit>

<organizationalUnitName>OU Name 1</organizationalUnitName>

<organizationalUnitType>Service Team</organizationalUnitType>

</organizationalUnit>

<organizationalUnit>

<organizationalUnitName>OU Name 2</organizationalUnitName>

<organizationalUnitType>Service Team</organizationalUnitType>

</organizationalUnit>

</organizationalUnits>

<functionalPositions>

<functionalPosition>

<functionalPositionName>Func Pos 1</functionalPositionName>

<ownerLoginName>assigneeLoginName</ownerLoginName>

</functionalPosition>

<functionalPosition>

<functionalPositionName>Func Pos 2</functionalPositionName>

<ownerLoginName />

</functionalPosition>

</functionalPositions>

<customAttribute name="IntegerValue" />

<customAttribute name="LongString">This is Long String</customAttribute>

<customAttribute name="MediumString" />

<customAttribute name="ShortString">This is short value</customAttribute>

<customAttribute name="MoneyValue">1234567.89</customAttribute>

<customAttribute name="DoubleValue">12345678</customAttribute>

<customAttribute name="DateValue">31-Jan-2013</customAttribute>

</account>

 

アカウントを削除します（1 アカウント オブジェクトのみ）

REST URL (HTTP DELETE):

http://<ServerURL>/RequestCenter/nsapi/directory/accounts/delete

<account>

<name>Sample Account Name</name>

<accountId>123</accountId>

</account>

 

OU 名と OU のタイプの取得

テナント アカウントに関連付けられていない OU 名、OU のタイプが返されます（ログイン ユーザが OU へのアクセス権限を持つテナント アカウント。RBAC チェックが実施されます）。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/accounts/tenantorgunitlist

 

アカウントの役職の取得

アカウントの役職が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/accounts/functionalpositionlist

フィルタ

フィルタはサポートされません。

ソート カラム

ソートは許可されません。

応答 XML
<accounts totalCount="x" startRow="y" recordSize="z">
<account>
...(same as the request payload for update)
</account>
</accounts>

トランザクション データ

要求

表 3-21 要求 API テーブル

領域
例

コア API

現行ユーザに対する要求の取得

次に示すデフォルトのフィルタを使用して要求を取得します。

ViewName = Ordered for Self

Status = Ongoing

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions

Java の例

RequisitionList requisitions = NSApiClient.getTransaction().getRequisitions(null);

 

Id による要求の取得

ログインしているユーザに対して RBAC チェックが適用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions/id/<requisitionId>

Java の例

Requisition requisitions = NSApiClient.getTransaction().getRequisitionsById(<requisitionId>);

 

サービス フォーム データの取得

指定された要求 ID のすべての要求エントリのサービス フォーム データを取得します。応答は、各要求のサービス名、フォーム フィールドのデータ、および requisitionEntryId を含むリストです。応答は、XML 形式および JSON 形式で取得できます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions/id/<requisitioin_id>/requisitiondata

Java の例

RequisitionEntriesList requisitionEntries =
NSApiClient.getTransaction().getRequisitionData(id)

 

サービスを追加せずに、未送信の既存の要求/カートを送信する

Method: POST

REST URL:

/RequestCenter/nsapi/transaction/requisitions

要求ペイロード/本文は不要です。

成功コード：201

応答エラー コード：表 REST/Web サービスのエラー メッセージを参照

 

サービスを追加して、新しい要求/カートを送信します。

Method: POST

REST URL:

/RequestCenter/nsapi/transaction/requisitions

ペイロード：

{

"requisition": {

"customerLoginName": "admin",

"billToOU": "H_OU",

"services":[{

"name": "TestServiceRest"

"quantity": "1",

"version": "0",

"dictionaries": [{

"name": "TestNonGrid",

"data": {

"FullName": "AAB",

"HireDate": "78/02/20",

"MultiSelect":["MS3","MS4"],

}

},{

"name": "TestG",

"data":

[

{"city":"Bangalore", "country": "India"},

{"city":"Mysore", "country":"India"}

]

}]

}]

}

}

成功コード：201

応答エラー コード：表 REST/Web サービスのエラー メッセージを参照

 

既存の未送信の要求/カートにオーダーを追加する

Method: PUT

REST URL:

/RequestCenter/nsapi/transaction/requisitions

ペイロード：

{

"requisition": {

"customerLoginName": "admin",

"billToOU": "H_OU",

"services":[{

"name": "TestServiceRest"

"quantity": "1",

"version": "0",

"dictionaries": [{

"name": "TestNonGrid",

"data": {

"FullName": "AAB",

"HireDate": "78/02/20",

"MultiSelect":["MS3","MS4"],

}

},{

"name": "TestG",

"data":

[

{"city":"Bangalore", "country": "India"},

{"city":"Mysore", "country":"India"}

]

}]

}]

}

}

成功コード：200

応答エラー コード：表 REST/Web サービスのエラー メッセージを参照

 

未送信の要求/カートをキャンセルする

Method: DELETE

REST URL:

/RequestCenter/nsapi/transaction/requisitions

ペイロードは不要です。

成功コード：200

応答エラー コード：表 REST/Web サービスのエラー メッセージを参照

 

要求/カートから特定のサービスを削除/キャンセルする

Method: DELETE

REST URL:

/RequestCenter/nsapi/transaction/requisitionentries/{reqentry_id}

ペイロードは不要です。

成功コード：200

応答エラー コード：表 REST/Web サービスのエラー メッセージを参照

 

オープン オーダーのモニタ プランのキャンセル

要求キャンセル nsAPI の cancelMonitorPlan オプションは、オープン オーダーのモニタ プランをキャンセルします。要求のステータスは Delivery Canceled に設定されます。

Method: Delete

REST URL:

/RequestCenter/nsapi/transaction/requisition/{requisitionID}?cancelMonitorPlan=true

ペイロードは不要です。

成功コード：200

応答エラー コード：表 REST/Web サービスのエラー メッセージを参照

（注） cancelMonitorPlan オプションを実行する権限があるのは、サイト管理者ロールを持つユーザのみです。

 

サービス要求フォームを更新する

nsXML で指定された入力に基づいてフォーム データを更新する

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/transaction/updateServiceRequest

サンプル ペイロード:

<?xml version="1.0" encoding="UTF-8"?>

<message channel-id="" is-autocomplete="false" is-published="true">

<task-started task-type="task">

<requisition>

<requisition-entry>

<data-values>

<data-value multi-valued="false">

<name>GridUpdate-1.Name</name>

<value>ordernamechanged4</value>

</data-value>

<data-value multi-valued="false">

<name>GridUpdate-1.Roll</name>

<value>orderrollchanged4</value>

</data-value>

</data-values>

<requisition-entry-id>55</requisition-entry-id>

</requisition-entry>

</requisition>

</task-started>

</message>

サンプル応答：

更新サービス要求が正常に開始されます。

フィルタ

ビューおよびステータス フィルタ

フィルタに使用可能なビューおよびステータスは、My Services の [Requisitions] タブにあるものに対応しています。

Status が指定されなかった場合は、「Ongoing」が使用されます。

ViewName が指定されなかった場合は、「Ordered for Self」が使用されます。

ViewName に指定可能な値：

  • Ordered for Self：現行ユーザに対する要求。
  • Ordered for Others：現行ユーザが（「Order on Behalf」を使用して）他人の代わりに送信した要求。
  • Ordered for my unit：現行ユーザが属している OU 内の人に関する要求（ユーザが「See Requisitions for My Business Units」機能を持っている場合に限り、このビューは他の人に関するデータを返します）。

Status に指定可能な値：Ongoing、Preparation、Ordered、Closed、Canceled、Rejected、All。

誤った値が指定された場合、デフォルトの値（「Ongoing」および「Ordered for Self」）が使用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions/ViewName=<viewName>[|AND|Status=<status>]

Java の例

String filterString = "ViewName=<viewName>|AND|Status=<status>";
RequisitionList requisitons = NSApiClient.getTransaction().getRequisitionsByFilter(filterString);
 

（注） PUT および POST メソッドではフィルタはサポートされません。

ソート カラム

Customer Name、Owner（Initiator）Name、Requisition ID、Service Name、Started Date、Status、Submit Date

（注） PUT および POST メソッドではソートはサポートされません。

GET の応答 XML
<requisitions totalCount="x" recordSize="y" startRow="z">
<requisition>
...
</requisition>
</requisitions>

PUT および POST の応答 XML
{ "RequisitionSubmit": {
"requisitionId": 536,
"customer": "admin admin",
"initiator": "admin admin",
"startedDate": "…",
"startedDateRaw": …,
"dueDate": "…"
"dueDateRaw": …,
"status": "Ordered",
"links" : [
{ "name" : "RequisitionStatus",
"href" : "http://…"
},
{ "name" : "ServiceItems",
"href" : "http://…"
}
]
}
}

（注） dueDate および dueDateRaw 属性は、非同期伝送設定が [管理（Administration）] > [設定（Settings）] モジュールで無効の場合だけ使用できます。

REST API

サービス フォーム詳細の取得

Method: GET

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/v1/orderform?serviceids=<list of service ids, comma seperated>

出力例：：

{
"API_Service": {
"serviceID": "12",
"quantity": 1,
"API_AFC-API_Dictionary": {
"Name": {
"value": ""
},
"City": {
"value": [],
"isMultiValued": "true",
"selectableValues": [
"Bangalore",
"Mysore"
]
},
"Range": {
"value": " ",
"selectableValues": [
"100-1000",
"1000-2000"
]
},
"Sal": {
"value": [],
"isMultiValued": "true",
"selectableValues": [
"10k",
"20k",
"30k",
"40k"
]
}
},
"Form-Dictionary": {
"Select_Person": {
"value": ""
},
"Login_ID": {
"value": ""
}
}
},

 
"0Service": {
"serviceID": "1",
"quantity": 1,
"maxQuantity": 2,
"Form-Dictionary": {
"Select_Person": {
"value": ""
},
"Login_ID": {
"value": ""
}
}
}
}

フォームにグリッド ディクショナリが含まれている場合の出力例：

{
"Grid_Service": {
"serviceID": "114",
"quantity": 1,
"grid_form-Grid_dict": {
"isGrid": true,
"row-1": {
"Name": {
"value": ""
},
"Description": {
"value": ""
}
}
}
}
}

（注） フィールドに複数の値がある場合、そのフィールドの値はリストとみなされ、そのフィールドには複数値フラグが表示されます。

（注） フィールドが必須の場合は、そのフィールドに必須フラグが表示されます。

 

フォームにグリッド ディクショナリが含まれている場合の入力例：

{
"Grid_Service": {
"serviceID": "114",
"quantity": 1,
"grid_form-Grid_dict": {
"row-1": {
"Name": {
"value": "Name1"
},
"Description": {
"value": "desc1"
}
},
"row-2": {
"Name": {
"value": "Name2"
},
"Description": {
"value": "desc2”
}
}
}
}
}

出力例：：

{
"Requisition ID":6,
"InitiatorLogin":"admin admin",
"customerLogin":"user1 user1",
"startedDate":"Wed Oct 26 12:31:13 IST 2016",
"status":"Ordered"
}

（注） 要求送信 API のペイロードは、サービス フォーム詳細 API から取得できます。

（注） グリッド ディクショナリが個人ベースの場合、名前の代わりにログイン ID を送信する必要があります。

（注） サーバ側イベント（PostSubmit）があるフォーム ルールのみが実行されます。

要求エントリ

 

表 3-22 要求エントリ API テーブル

領域
例

コア API

ID による要求エントリの取得

現行ユーザに対して RBAC チェックが適用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/requisitionentries/id/<reqEntryId>

Java の例

RequisitionEntry requisitonEntry = NSApiClient.getTransaction().getRequisitionEntryById(<reqEntryId>);

 

要求 ID による要求エントリの取得

現行ユーザに対して RBAC チェックが適用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/requisitionentries/RequisitionNumber=<reqId>

Java の例

MultiValueMap paramsMap = new MultiValueMap();
paramsMap.put("startRow", "1"); //optional
paramsMap.put("recordSize","10"); //optional
String filterString = "RequisitionNumber=" + <reqId>;
RequisitionEntryList requisitonEntries = NSApiClient.getTransaction().getRequisitionEntries(paramsMap, filterString);

フィルタ
ServiceName
Displays all ordered services that contains the filter values. Service Name filter value is test. Lists all ordered services where the service name contains "test".

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/requisitionentries/ViewName=<viewName>|AND|ServiceName=<wildcard>|AND|Status=<status>

Java の例

isNgcRequest
Displays service request process complete percentage if the isNgcRequest filter value is false or not mentioned. If the isNgcRequest filter value is true, the service process request percentage is not displayed on the Order form page.
REST URL
http://localhost:8088/RequestCenter/nsapi/transaction/requisitionentries/ViewName=Ordered%20for%20Myself|AND|ServiceName=test|AND|Status=AllOpenExceptPreparation?responseType=json&isNgcRequest=true&recCount=20&sortBy=submitDate&sortDir=desc

ソート カラム

Due On、Requisition Entry ID

応答 XML
<requisitionEntries totalCount="x" recordSize="y" startRow="z">
<requisitionEntry>
...
</requisitionEntry>
</requisitionEntries>

 

表 3-23 DELETE 要求エントリ API テーブル

領域
例

コア API

要求またはカートのサービスを取り消す

  • 要求またはカートのステータスが未送信の場合に、サービスを削除します。
  • 要求またはカートのステータスが送信済みの場合は、サービスを取り消します。

DELETE REST URL：

http://<ServerURL>/RequestCenter/nsapi/transaction/requisitionentries/<reqEntryId>

（注） <reqEntryId> は要求 ID に置き換えます。http://<ServerURL>/RequestCenter/nsapi/transaction/requisitionentries/175 を考慮し、応答は次のようになります。

フィルタ

N/A

ソート カラム

N/A

応答 XML

{

"requisition id": 175

}

承認

 

表 3-24 承認 API テーブル

領域
例

コア API

現行ユーザに対する承認の取得

次に示すデフォルトのフィルタを使用して承認を取得します。

ViewName = Authorizations for Self

Status = Ongoing

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/authorizations

Java の例

AuthorizationList authorizations = NSApiClient.getTransaction().getAuthorizations(null);

 

Id による承認の取得

現行ユーザに対して RBAC チェックが適用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/authorizations/id/<taskId>

Java の例

Authorization authorizations = NSApiClient.getTransaction().getAuthorizationsById(<taskId>);

 

ID による関連承認タスク（承認チェーン）の取得

現行ユーザに対して RBAC チェックが適用されます。

渡された ID が、要求レベルの承認タスク（部門承認、部門確認、財務承認）の ID であった場合、その特定の要求に属するすべての要求レベルの承認タスクが返されます。

渡された ID が、要求エントリ レベルの承認タスク（サービス グループ承認、サービス グループ確認）の ID であった場合、その特定の要求エントリに属するすべての要求エントリ レベルの承認タスクが返されます。

デフォルトのソートは、Due On の降順で行われます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/authorizations?taskId=<taskId>

Java の例

MultiValueMap paramsMap = new MultiValueMap();
paramsMap.put("startRow", "" + 1); //optional
paramsMap.put("recordSize", "" +10); //optional
paramsMap.put("sortBy", "dueOn"); //optional
paramsMap.put("sortDir", "asc"); //optional
paramsMap.put("taskId", "<taskId>");
Authorization authorizations =
NSApiClient.getTransaction().getAuthorizations (paramsMap);

フィルタ

ビューおよびステータス フィルタ

フィルタに使用可能なビューおよびステータスは、My Services の [Authorizations] タブにあるものに対応しています。

Status が指定されなかった場合は、「Ongoing」に設定されます。

ViewName が指定されなかった場合は、「Authorizations for Self」に設定されます。

ViewName に指定可能な値：

  • Authorizations for Self：現行ユーザに割り当てられている承認　
  • Assigned and Unassigned Authorizations for Self：現行ユーザ、または現行ユーザがアクセスできるキューに割り当てられている承認　
  • Authorizations for Others：現行ユーザが属している OU 内の人に割り当てられている承認（ユーザが「See Authorizations for My Business Units」機能を持っている場合に限り、このビューはデータを返します）　

Status に指定可能な値：Ongoing、Approved、Rejected、Canceled、Reviewed、All。

誤った値が指定された場合、デフォルトの値（「Ongoing」および「Authorizations for Self」）が使用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/authorizations/ViewName=<viewName>[|AND|Status=<status>]

Java の例

String filterString = "ViewName=<viewName>|AND|Status=<status>";
AuthorizationList authorizations =
NSApiClient.getTransaction().getAuthorizationsWithFilters(filterString);

ソート カラム

Customer Name、Due On、Performer Name、Priority、Requisition ID

応答 XML
<authorizations totalCount="x" recordSize="y" startRow="z" />
<authorization>
...
</authorization>
</authorizations>

タスク

 

表 3-25 タスク API テーブル

領域
例

コア API

現行ユーザに対するタスクの取得

次に示すデフォルトのフィルタを使用してタスクを取得します。

ViewName = AvailableWork

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks

Java の例

TaskList tasks = NSApiClient.getTransaction().getDeliveryTasks(null);

 

ID によるタスクの取得

現行ユーザに対して RBAC チェックが適用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks/id/<taskId>

Java の例

TaskFull tasks = NSApiClient.getTransaction().getDeliveryTaskById(<taskId>);

 

要求エントリ ID によるタスクの取得

現行ユーザに対して RBAC チェックが適用されます。

デフォルトのソートは、Activity ID の昇順で行われます。

パラメータおよび指定可能な値：

  • showSkippedTasks：false（デフォルト）、true
  • taskType：all（デフォルト）、delivery、authorization
  • showNestedTasks：false、true（デフォルト）

このパラメータが true に設定されている場合、親と子のネスト階層が XML 構造内に保持された状態で配信タスクが返されます。

  • showChildDeliveryPlan：false（デフォルト）、true

これは、バンドル サービスにのみ適用されます。このパラメータが true に設定されている場合は、すべての組み込みサービスの配信タスクも返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks/RequisitionEntryNumber=<reqEntryId>?taskType=<taskType>&showSkippedTasks=<false|true>&showNestedTasks=<false|true>&showChildDeliveryPlan=<false|true>

Java の例

MultiValueMap paramsMap = new MultiValueMap();
paramsMap.put("taskType", "delivery"); //optional
paramsMap.put("showSkippedTasks", "true"); //optional
paramsMap.put("showNestedTasks", "true"); //optional
paramsMap.put("sortBy", "dueOn"); //optional
paramsMap.put("sortDir", "desc"); //optional
String filterString = "RequisitionEntryNumber=" + <reqEntryId>;
TaskList tasks = NSApiClient.getTransaction().getAuthAndDeliveryTasks (paramsMap, filterString);

 

要求 ID によるマイルストーンの取得

現行ユーザに対して RBAC チェックが適用されます。

配信プロセスのマイルストーン（確認、承認、配信プロジェクト）が、時系列順に返されます。ソートおよびページングはサポートされていません。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks/RequisitionNumber=<reqId>

Java の例

String filterString = "RequisitionNumber=" + <reqId>;
MilestoneList milestones = NSApiClient.getTransaction().getDeliveryProcessForMilestone (filterString);

特殊な条件

タスクの許可

REST URL にアクションおよびタスク ID を指定して HTTP POST を実行します。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks /<taskId>/approve

Java の例

TaskAction approve = NSApiClient.getTransaction().approveTask(<taskId>);

 

タスクの拒否

REST URL にアクションおよびタスク ID を指定して HTTP POST を実行します。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks/<taskId>/reject

Java の例

TaskAction Reject = NSApiClient.getTransaction().rejectTask(<taskId>);

 

タスクの完了

REST URL にアクションおよびタスク ID を指定して HTTP POST を実行します。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks/<taskId>/done

Java の例

TaskAction Complete = NSApiClient.getTransaction().completeTask(<taskId>);

 

タスクの確認

REST URL にアクションおよびタスク ID を指定して HTTP POST を実行します。

POST REST URL：

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks/<taskId>/review

Java の例

TaskAction Review = NSApiClient.getTransaction().reviewTask(<taskId>);

フィルタ

ビュー フィルタ

フィルタに使用可能なビューは、Service Manager モジュールのビューに対応しています。ユーザ定義ビューは使用できません。

ViewName フィルタが指定されなかった場合、「AvailableWork」に設定されます。

ViewName に指定可能な値：AvailableWork、MyWork、MyLateWork、WorkForeCast

誤った値が指定された場合は、デフォルト値が使用されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks?viewName=<viewName>

Java の例

MultiValueMap paramsMap = new MultiValueMap();
paramsMap.put("ViewName", "<viewName>");
TaskList tasks = NSApiClient.getTransaction().getDeliveryTasks(paramsMap);
  • 要求エントリ レベルのすべての承認タスク（将来の承認タスクを含む履歴）を表示できます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks/RequisitionEntryNumber=111?taskType=authorization&Status=All

  • 要求レベルのすべての承認タスク（将来の承認タスクを含む履歴）を表示できます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/tasks/RequisitionNumber=111?taskType=authorization&Status=All

ソート カラム

Activity ID、Completed On、Customer Name、Customer OU Name、Due On、Effort、Initiator Name、Performer Name、Priority、Requisition ID、Scheduled Start Date、Service Name、Task Name、Task Type

応答 XML
<tasks totalCount="x" recordSize="y" startRow="z">
<task>
...
</task>
</tasks>

ポリシーアラート

 

表 3-26 ポリシー アラート API テーブル

領域
例

Core API

CreatedDate によるポリシー アラートの取得

作成日によりポリシー アラートが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/policyalert/{columnName}{Operator}{Value}

重大度のタイプと CreatedDate によるポリシー アラートの取得

重大度のタイプおよび作成日により、ポリシー アラートが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/policyalert/{columnName1}{Operator}{Value1}|{Join}|{columnName2}{Operator}{Value2}

サービス項目タイプの名前と CreatedDate によるポリシー アラートの取得

サービス項目タイプの名前と作成日により、ポリシー アラートが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/policyalert/{columnName1}{Operator}{Value1}|{Join}|{columnName2}{Operator}{Value2}

 

アカウント名と CreatedDate によるポリシー アラートの取得

アカウント名と作成日により、ポリシー アラートが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/policyalert/{columnName1}{Operator}{Value1}|{Join}|{columnName2}{Operator}{Value2}

 

ポリシー アラートの削除

ポリシー アラートの削除はポリシー アラート エントリの UniqueID で実行されます。この固有 ID はポリシー アラート エントリごとにシステムにより生成される一意の ID です。

REST URL (HTTP DELETE):

http://<ServerURL>/RequestCenter/nsapi/transaction/policyalert/delete/uniqueid/{uniqueIDs}

フィルタ

最大 4 つのフィルタをサポートします。

比較演算子：

文字列カラム：equals、starts-with 演算子（contains および like 演算子は許可されません）。

関係演算子：AND（OR は許可されません）

区切り文字 = |

使用可能なカラム：ServiceItemTypeName、AccountName、SeverityType、および CreatedDate

URL で許可されるパラメータ：startRow、recordSize、sortBy、sortDir、および responseType（xml または json）

ソート カラム

ソートは許可されません。

応答 XML
<policyAlert recordSize="2" startRow="1" totalCount="1">
<policyAlertRecord id="123" severityLevel="Info" alertContext="Policy Alert Action" requisitionID="12" requisitionEntryID="32">
<uniqueID>e96c062f-fe50-4b77-981a-dda1ab078808</uniqueID>
<policy id="8" name="Quota policy 8" />
<serviceItemType id="82" name= "Laptop with Quota"/>
<serviceItem id="12" name="Service Item one" />
<account id="1" name="Custom Account 1" />
<agreement id="6" name="Agreement Name"/>
<message>Message Message Message Message</message>
<createdDate local="04/09/2013 12:44 PM" raw="2013-04-09T19:44:28.720-07:00" />
</policyAlertRecord>
</policyAlert>

課金履歴

表 3-27 課金履歴 API テーブル

領域
例

Core API

取引日による課金履歴の取得

取引日により、課金履歴が返されます。

REST URL:

http://<ServerURL>:8088/RequestCenter/nsapi/transaction/billinghistory/{columnName}{Operator}{Value}

サービス項目名、サービス項目タイプの名前、および取引日による課金履歴の取得

サービス項目名、サービス項目タイプの名前、および取引日により、課金履歴が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/billinghistory/{columnName1}{Operator}{Value1}|{Join}|{columnName2}{Operator}{Value2}

サービス項目タイプの名前と取引日による課金履歴の取得

サービス項目タイプと取引日により、課金履歴が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/billinghistory/{columnName1}{Operator}{Value1}|{Join}|{columnName2}{Operator}{Value2}

 

アカウント ID と取引日による課金履歴の取得

アカウント ID と取引日により、課金履歴が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/billinghistory/{columnName1}{Operator}{Value1}|{Join}|{columnName2}{Operator}{Value2}

 

アカウント名と取引日による課金履歴の取得

アカウント名と取引日により、課金履歴が返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/transaction/billinghistory/{columnName1}{Operator}{Value1}|{Join}|{columnName2}{Operator}{Value2}

フィルタ

最大 4 つのフィルタをサポートします。

REST URL:

比較演算子：

数値/日付カラム：=、>、<、>=、<=

文字列カラム： equals、starts-with 演算子（contains および like 演算子は許可されません）

関係演算子：AND（OR は許可されません）

区切り文字 = |

使用可能なカラム：ServiceItemName、ServiceItemTypeName、AccountID、AccountName、および TransactionDate

フィルタの組み合わせ：

許可されるフィルタの組み合わせは次のとおりです。

  • ServiceItemTypeName フィルタ、ServiceItemName フィルタ、および TransactionDate フィルタ
  • TransactionDate フィルタ（1 回以上）
  • TransactionDate フィルタおよび ServiceItemTypeName フィルタ
  • TransactionDate フィルタおよび AccountID フィルタ
  • TransactionDate フィルタおよび AccountName フィルタ

http://<ServerURL>/RequestCenter/nsapi/serviceitem/<serviceItemName> /<columnName1><operator1><value1>[|<AND>|<columnName2><operator2><value2>][|<AND>|<columnName3><operator3><value3>]

Java の例

String filter = "<columnName1><operator1><value1>|<and>|<columnName2><operator2><value2>|<and>|<columnName3><operator3><value3>";
ServiceItemDTO serviceItems =

ソート カラム

ソートは許可されません。

応答 XML
<billingHistory recordSize="2" startRow="1" totalCount="1">
<billingRecord id="123">
<requisitionID>45</requisitionID>
<requisitionEntryID>56</requisitionEntryID>
<transactionDate local="01/03/2013 6:31 PM"
raw="2013-01-04T02:31:43.400-08:00"/>
<serviceItemType id="5" name="Laptop"/>
<serviceItem id="4" name="DELL"/>
<organizationalUnit id="5" name="My OU"/>
<operation>Assemble Laptop</operation>
<account id="5" name="Account Name"/>
<agreement id="6" name="Agreement Name"/>
<customer id="2" name="John John"/>
<rateRecord rate="123.45" rateCode="RateCode1" unitOfMeasure="Seconds"/>
<billingAttributes>
<attribute name="Attr1">Value1</attribute>
<attribute name="Attr2">Value2</attribute>
<attribute name="Attr3">Value3</attribute>
</billingAttributes>
</billingRecord>
</billingHistory>

サービス項目データ

サービス項目の詳細

 

表 3-28 サービス項目の詳細 API テーブル

領域
例

コア API

Name による取得

指定したサービス項目名に関して現行ユーザに割り当てられている、サービス項目インスタンスの詳細情報およびサブスクリプション データが返されます。

また、ユーザが「View Service Items for My Business Units」機能を持っている場合は、そのユーザが属している全 OU に含まれている人に関するサービス項目が返されます。

サービス項目名パラメータは、[Design Service Item] ページの [Name] フィールドに示されるサービス項目の内部テーブル名（SiVirtualMachine など）を受け入れます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitem/<serviceItemName>

Java の例

ServiceItemDTO serviceItems = NSApiClient.getServiceItem().getServiceItemData("<serviceItemName>", null);

特殊な条件

フィルタ時の特殊文字のサポート

特殊文字（「=」、「|」、または「/」など）を使用する必要がある場合は、要求のペイロード（本文）で、フィルタとともに POST メソッドを使用します。

Method: POST

REST URL:

/RequestCenter/nsapi/serviceitem/{serviceItemName}

サンプル ペイロード:

{

"filterString":"<columnName1><operator1><value1>|<and|or>|<columnName2><operator2><value2>|<and|or>|<columnName3><operator3><value3>"

}

 

ビュー フィルタ

フィルタに使用可能なビューは、My Services および Service Item Manager モジュールの表示内容に対応しています。

ViewName に指定可能な値：

  • My ServiceItems：現行ユーザが所有しているサービス項目のすべてのインスタンス「View Service Items for My Business Units」機能を持っているユーザは、そのユーザが属している OU 内の他人が所有している項目も表示できます。
  • Manage ServiceItems：サービス項目のすべてのインスタンス（ユーザが「Manage Service Item Instances」機能を持っている場合に限り、このビューはデータを返します）。

ソート順やページ サイズなど他の引数も指定する場合は、ViewName 引数を最後に配置する必要があります。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitem/<serviceItemName>?ViewName=<viewName>

Java の例

ServiceItemDTO serviceItems = NSApiClient.getServiceItem().getServiceItemDataWithFilters("<serviceItemName>", "<viewName>");

フィルタ

サービス項目属性フィルタ

最大 3 つのフィルタがサポートされます。

サービス項目およびサブスクリプションのすべてのカラムがサポートされます。

サービス項目分類名（グループ）またはサービス項目タイプ（シスコが予約しているもの、またはユーザ定義のもの）によるフィルタはサポートされていません。

REST URL:

比較演算子：

数値/日付カラム：=、>、<、>=、<=

文字列カラム：=（大文字小文字の区別あり。like、contains、および starts-with 演算子については後述）

関係演算子：AND、OR（大文字と小文字を区別しない、オーダーの優先順位はサポートされていません）

区切り文字 = |

使用可能なカラム：サービス項目およびサブスクリプションの全カラム

http://<ServerURL>/RequestCenter/nsapi/serviceitem/<serviceItemName> /<columnName1><operator1><value1>[|<AND|OR>|<columnName2><operator2><value2>][|<AND|OR>|<columnName3><operator3><value3>]

Java の例

String filter = "<columnName1><operator1><value1>|<and|or>|<columnName2><operator2><value2>|<and|or>|<columnName3><operator3><value3>";
ServiceItemDTO serviceItems = NSApiClient.getServiceItem().getServiceItemDataWithFilters("<serviceItemName>", filter);

 

文字列カラムのフィルタ

%（starts with）演算子用のフィルタ。

*（contains）演算子用のフィルタ。

（ends with）演算子はサポートされていません。

例：

Name=service*

Name=*g*

Name=*g：許可されません。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitem/<serviceItemName> /<columnName>=<wildcardValue>

Java の例

ServiceItemDTO serviceItems = NSApiClient.getServiceItem().getServiceItemDataWithFilters("<serviceItemName>",

 

日付カラムの属性

日付フィールドの値は mm-dd-yyyy 形式にする必要があります。

比較演算子：=、>、<、<=、>=

例：

SubmittedDate=12-10-2010

REST URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitem/<serviceItemName> /<columnName><operator><mm-dd-yyyy>

Java の例

ServiceItemDTO serviceItems = NSApiClient.getServiceItem().getServiceItemDataWithFilters("<serviceItemName>", "<columnName><operator><mm-dd-yyyy>");

ソート カラム

サービス項目の属性：すべてのテーブル カラム。

サブスクリプション：Assigned Date、Display Name、ID（内部 ID）、Requisition ID、Submit Date。

応答 XML
<serviceitem totalCount="x" recordSize="3" startRow="1" id="62">
<logicName></logicName>
<name></name>
<subscription>
...
<assignedDate> </assignedDate>
<assignedDateRaw></assignedDateRaw>
<customerID></customerID>
<customerName> </customerName>
<displayName> </displayName>
<id></id>
<organizationalUnitID></organizationalUnitID>
<organizationalUnitName> </organizationalUnitName>
<requisitionEntryID></requisitionEntryID>
<requisitionID></requisitionID>
<serviceItemClassificationID></serviceItemClassificationID>
<serviceItemTypeID></serviceItemTypeID>
<serviceItemTypeName> </serviceItemTypeName>
<submittedDate> </submittedDate>
<submittedDateRaw></submittedDateRaw>
...
</subscription>
</serviceitem>

v2 CRUD サービス項目の NSAPI

version2（v2）nsAPI のサービス項目は、階層的なサービス項目をサポートするために実行されます。すべてのv2 API は JSON 形式のみをサポートします（入力および応答）。

読み取り、作成、更新、削除について v2 サービス項目 NSAPI でサポートされる URL は次のとおりです。

GET API-1:

http://<Server URL>/RequestCenter/nsapi/v2/serviceitem/{serviceItemLogicName}

特定のサービス項目タイプの論理名のすべてのサービス項目レコードを、フィルタなしで取得します。

URL 例：http://<Server URL>/RequestCenter/nsapi/v2/serviceitem/SiDesktop

出力例：：

HTTP ステータス コード：200 OK

{

"serviceitem": {

"id": 109,

"name": "Desktop",

"logicName": "SiDesktop",

"startRow": 1,

"recordSize": 2,

"totalCount": 2,

"serviceItemData": [

{

"items": [

{

"Name": "1 desktop",

"SingleStr": "Single 1",

"MultiStr": [

"1-First",

"1-2nd",

"1-3rd"

]

}

],

 

"subscription": {

"accountID": 0,

"agreementID": 0,

"customerID": 1,

"id": 1,

"organizationalUnitID": 1,

"requisitionEntryID": 0,

"requisitionID": 0,

"submittedDateRaw": 1412223018210

}

]

}

}

}

 

GET API-2:

http://<ServerURL>/RequestCenter/nsapi/v2/serviceitem/{serviceItemLogicName}/{filters}

特定のサービス項目タイプの論理名の、フィルタ基準に一致するすべてのサービス項目のレコードを取得します。

URL 例：

http:<Server URL>/RequestCenter/nsapi/v2/serviceitem/SiDesktop/Name=1desktop

出力例：：

HTTP ステータス コード：200 OK

{

"serviceitem": {

"id": 109,

"name": "Desktop",

"logicName": "SiDesktop",

"startRow": 1,

"recordSize": 2,

"totalCount": 2,

"serviceItemData": [

{

"items": [

{

"Name": "1 desktop",

"SingleStr": "Single 1",

"MultiStr": [

"1-First",

"1-2nd",

"1-3rd"

]

}

],

 

"subscription": {

"accountID": 0,

"agreementID": 0,

"customerID": 1,

"id": 1,

"organizationalUnitID": 1,

"requisitionEntryID": 0,

"requisitionID": 0,

"submittedDateRaw": 1412223018210

}

]

}

}

}

 

POST API

http://<ServerURL>/RequestCenter/nsapi/v2/serviceitem/{serviceItemLogicName}

URL 例：http://<Server URL>/RequestCenter/nsapi/v2/serviceitem/SiDesktop

入力例：（「serviceItemData」のオブジェクトの構造は、GET 呼び出し応答および POST/PUT 呼び出しの入力と同じです）。

{

“serviceitem": {

"serviceItemData": {

"Name": "2 desktop",

"SingleStr": "Single 2",

"MultiStr": ["2-1st",

"2-2nd",

"2-3rd"],

"Harddisk": {

"Name": "2 Disk",

"Size": "200"

},

 

"Harddisk": {

"Name": "2 Disk",

"Size": "200"

},

"MultiHardDisk": [{

"Name": "2-1 MDisk",

"MSize": "21"

},

{

"Name": "2-2 MDisk",

"MSize": "22"

}],

"CPU": {

"Name": "HP2",

"Speed": "20"

},

"MultiCPU": [{

"Name": "MHP1",

"MSpeed": "100"

},

{

"Name": "MHP2",

"MSpeed": "200"

}]

},

"subscription": {

"loginID": "admin",

"ouname": "Site Administration" }

}

}

 

出力例：

応答 HTTP ステータス コード：200 OK

出力： {

"nsapi-response": {

"status-messages": [

{

"code": "SI_SUCCESS_001",

"value": "Service item successfully updated."

}

]

}

}

 

DELETE API

http://<ServerURL>/RequestCenter/nsapi/v2/serviceitem/{serviceItemLogicName}

特定の入力のサービス項目を削除します。

URL 例：http://<Server URL>/RequestCenter/nsapi/v2/serviceitem/SiDesktop

入力例：

{

"serviceitem":{

"serviceItemData": {

"Name": "14 desktop"

}

}

}

出力例：：

応答 HTTP ステータス コード：204

注意事項と検証

1. これらの API をすべて使用するには、サービス項目の定義が存在している必要があります。

2. URL の「serviceItemLogicName」は有効な名前である必要があります。

3. 作成/更新/削除の入力には、次の検証が必要です。

a. サービス項目名は必須です。

b. 「作成」では、「更新」および「削除」とは異なり、同じサービス項目が以前にあってはなりません。

c. 入力 JSON の属性が SI 定義に存在する必要があります。

d. 親レコードでレコードを参照するためには、「作成」および「更新」API のいずれにも、その参照レコードが存在している必要があります。

e. 包含レコードは親レコードの更新シナリオに存在する必要はありません。

f. 親レコードの更新時に、「名前」を除く、それに含まれる子レコード データを更新できます。このためには所有者情報が一致する必要があります。

g. 子レコードにこれまで一度も所有者 SI がなかった場合は、ユーザが親レコードの更新を使用して、既存の SI レコードを包含レコードとして別の既存の SI（親）に追加する必要があります。
例：デスクトップ（親 SI）と CPU（子 SI）、およびこれら両方に別々に作成されるインスタンス（Desktop1 および CPU1）。ここで、Desktop1 を更新し、CPU1 がこれまで所有者 SI を持ったことがない場合は、CPU1 をこれに接続できます。この呼び出しによって、CPU1 は Desktop1 の包含レコードになります。

h. 更新時に、入力のすべての SI レコード（親レコードまたはそれに含まれる子レコード）はマージされ、保存される必要があります。既存の属性データは、それらの属性が更新 API の入力で指定されていない場合は、変更しないでください。

i. 参照レコードが親レコード更新で更新されることはありません。これらは、参照されるだけです。

j. 親レコードに 1 つの包含オブジェクトがあり、その包含レコードを親に含めない場合、含まれるのが単一値であれば入力として空のオブジェクト {} を渡し、含まれるのが複数値であれば空の配列 [] を渡す必要があります。
例：Harddisk - 単一値が含まれるタイプの属性 MultiHardDisk - 複数値が含まれるタイプの属性。

{

"serviceitem": {

"serviceItemData": {

"Name": "1 desktop",

"Harddisk": {

},

"MultiHardDisk": [

]

}

}

k. 既存の参照レコードを削除するために親を更新するには、入力構造が前述と同じである必要があります。

l. 「Name」は包含/参照の子レコードに必須です。

m. 更新 API の入力で属性が指定されない場合、その属性データは更新の実行によって変更されません。

4. 削除 API の場合、親レコードとそれに関連していたすべての子レコードが削除されますが、親レコードと関連していない参照レコードは削除されません。

5. 必要に応じ、 newscale.properties ファイルで serviceitem.nsapi.rbac.check プロパティを false に設定することで、nsAPI に基づいてサービス項目に対する RBAC チェックをバイパスすることができます。

すべてのサービス項目

 

表 3-29 すべてのサービス項目 API テーブル

領域
例

コア API

すべての項目の取得

すべてのサブスクリプションおよびサービス項目データを表示します。

デフォルトでは、現行ユーザに割り当てられているサービス項目のみがフィルタされます。また、ユーザが「View Service Items for My Business Units」機能を持っている場合は、そのユーザが属している全 OU に含まれている他人のサービス項目も返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitems/serviceitemsubscription

Java の例

ServiceItemSubscriptionList AllserviceItems = NSApiClient.getServiceItemSubscription().getServiceItemSubscriptionData(null);

特殊な条件

フィルタ時の特殊文字のサポート

特殊文字（「=」、「|」、または「/」など）を使用する必要がある場合は、要求のペイロード（本文）で、フィルタとともに POST メソッドを使用します。

Method: POST

REST URL:

/RequestCenter/nsapi/serviceitems/serviceitemsubscription

サンプル ペイロード:

{

"filterString":"<columnName1><operator1><value1>|<and|or>|<columnName2><operator2><value2>|<and|or>|<columnName3><operator3><value3>"

}

フィルタ

ビュー フィルタ

フィルタに使用可能なビューは、My Services および Service Item Manager モジュールのそれぞれに表示される内容に対応しています。

ViewName に指定可能な値：

  • My ServiceItems：現行ユーザが所有しているすべてのサービス項目「View Service Items for My Business Units」を持っているユーザの場合は、そのユーザが属している OU 内の他人が所有している項目も取得します。
  • Manage ServiceItems：すべてのサービス項目（ユーザが「サービス項目インスタンスの管理（Manage Service Item Instances）」権限を持っている場合に限り、このビューはデータを返します）。

ソート順やページ サイズなど他の引数も指定する場合は、ViewName 引数を最後に配置する必要があります。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitems/serviceitemsubscription?ViewName=<viewName>

Java の例

ServiceItemSubscriptionList AllserviceItems = NSApiClient.getServiceItemSubscription().getServiceItemSubscriptionFilterData("<viewName>");

 

サブスクリプション フィルタ

Service Item Subscription テーブルの全カラム用のフィルタ。

最大 3 つのフィルタがサポートされます。

REST URL:

比較演算子：

  • 数値/日付カラム：=、>、<、>=、<=
  • 文字列カラム：=（大文字小文字の区別あり。like、contains、および starts-with 演算子については後述）

関係演算子：AND、OR（大文字と小文字を区別しない、オーダーの優先順位はサポートされていません）

フィルタ区切り文字：|

サポートされるカラム：すべてのカラム

http://<ServerURL>/RequestCenter/nsapi/serviceitems/serviceitemsubscription/<columnName1><operator1><value1>[|<AND|OR>|<columnName2><operator2><value2>][|<AND|OR>|<columnName3><operator3><value3>]

Java の例

String filter = " <columnName1><operator1><value1>|<and|or>|<columnName2><operator2><value2>|<and|or>|<columnName3><operator3><value3>";
ServiceItemSubscriptionList AllserviceItems = NSApiClient.getServiceItemSubscription().getServiceItemSubscriptionFilterData(filter);

 

文字列カラムのフィルタ

%（starts with）演算子がサポートされています。

*（contains）演算子がサポートされています。

（ends with）演算子はサポートされていません。

例：

Name=service*
Name=*g*
Name=*g -- not allowed
 

REST URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitems/serviceitemsubscription /<columnName>=<wildcardValue>

Java の例

String filter = "<columnName>=<wildcardValue>";
ServiceItemSubscriptionList AllserviceItems = NSApiClient.getServiceItemSubscription().getServiceItemSubscriptionFilterData(filter);

 

日付カラムのフィルタ

日付フィールドの値は mm-dd-yyyy 形式にする必要があります。

比較演算子：=、>、<、<=、>=

例：

SubmittedDate=12-10-2010
 

REST URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitems/serviceitemsubscription /<columnName><operator><mm-dd-yyyy>

Java の例

String filter = "<columnName><operator><mm-dd-yyyy>";
ServiceItemSubscriptionList AllserviceItems = NSApiClient.getServiceItemSubscription().getServiceItemSubscriptionFilterData(filter);

ソート カラム

Assigned Date、Customer ID、Display Name、Organizational Unit ID、Requisition ID、Requisition Entry ID、Service Item Classification ID、Service Item ID、Service Item Type ID、Service Item Type Name、Submitted Date

応答 XML
<AllServiceItems totalCount="x" recordSize="y" startRow="z">
<serviceitemsubscription displayName=" " id="">
...
<serviceItemTypeName> </serviceItemTypeName>
<organizationalUnitID></organizationalUnitID>
<assignedDate> </assignedDate>
<requisitionID></requisitionID>
<submittedDate> </submittedDate>
<submittedDateRaw></submittedDateRaw>
<assignedDateRaw></assignedDateRaw>
<customerID></customerID>
<requisitionEntryID></requisitionEntryID>
<serviceItemID></serviceItemID>
<serviceItemTypeID></serviceItemTypeID>
<organizationalUnitName> </organizationalUnitName>
<customerName> </customerName>
<serviceitem id="">
<logicName> </logicName>
<name> </name>
<serviceItemData rowId="">
<serviceItemAttribute name=" "> </serviceItemAttribute>
...
</serviceitemsubscription>
</AllServiceItems>

 

すべてのサービス項目を取得する API

この API は、すべてのサービス項目を取得するのに使用します。

次のオプションを使用できます。

  • SearchFilter：name:equals:laptop
  • startRow および recordsPerPage：改ページ調整
  • SortBy：カラム名
  • sortDir：並べ替えの方向

（注） sortBy と sortDir は、同時に使用する必要があります。

REST URL:

http://<Server URL>/ RequestCenter/nsapi/serviceitem/v1/mdrdatatable/serviceitemlist?

サンプル出力：

{
"Result":{
"recordsReturned":10,
"totalRecords":1,
"startIndex":1,
"records":[
{
"serviceItemId":"1",
"assignedDate":"25/05/2016 7:49 AM",
"owner":"admin admin",
"serviceItemTypeId":"107",
"accountName":"",
"classification":"UCS Director",
"submittedDate":"25/05/2016 7:49 AM",
"organizationUnitName":"Site Administration",
"requisitionId":"",
"serviceItemTypeName":"APIC Container",
"encServiceItemId":"6M+JgN1m4ZpqG79GquDakQ==",
"agreementName":"",
"encServiceItemTypeId":"LAZcCouqBeYcZYsLd0hpRQ==",
"name":"Customer",
"id":"1"
}
]
}
}

 

すべてのサービス項目の CSV をダウンロード

すべてのサービス項目の CSV をダウンロード

次のオプションを使用できます。

  • SearchFilter：name:equals:laptop
  • startRow および recordsPerPage：改ページ調整
  • SortBy：カラム名
  • sortDir：並べ替えの方向

（注） sortBy と sortDir は、同時に使用する必要があります。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitem/v1/mdrdatatable/serviceitemlist/

CSV

サンプル出力：

Service Service Service Requisi Submitted Assigned Organi Acco Agree Custo
Item Item Item tion ID Date Date zational unt ment mer
Group Name Type Unit
 
"UCS SuFen5 Container 8 04/19/ 04/19/ UCSD::fen::Default Director" 2016 2016 Group vu1 7:02 AM 7:02 AM vu1

 

履歴情報の取得

サービス項目の履歴を取得

ペイロード コンテンツ タイプ：application/x-www-form-urlencoded（フォーム データ）。

フォーム データは次のように送信されます。serviceItemTypeId=149&serviceItemId=1

  • serviceItemTypeId：149
  • serviceItemId：1

REST URL:

http://<Server URL> /RequestCenter/nsapi/serviceitem/v1/myservices/assetlist/history?

出力例

[
{
"name": "",
"operation": "Update",
"requisitionId": "",
"serviceId": "",
"submitDate": "06/06/2016"
},
{
"name": "",
"operation": "Create",
"requisitionId": "",
"serviceId": "",
"submitDate": "06/06/2016"
}
]

 

分類ツリーの取得

サービス項目の分類ツリーを取得

REST URL:

http://<ServerURL> /RequestCenter/nsapi/serviceitem/v1/sim/serviceitemtypestree/classificationdatatypetree?

出力例

{
"data":[
{
"data":[
{
"hasChildren":false,
"iconCls":"sitinstance",
"id":"107",
"leaf":true,
"module":"itemType",
"moduleId":"107S",
"text":"APIC Container",
"vsocTenantNodeType":""
}
],
"hasChildren":true,
"iconCls":"sitfolder",
"id":"12",
"leaf":false,
"module":"classification",
"moduleId":"12C",
"text":"Cloud Infrastructure",
"vsocTenantNodeType":""
}
]
}

サービス項目に対する作成/更新/削除 API

次の表では、サービス項目に対して作成/更新/削除操作を行うための nsAPI URL について説明します。要求のコンテンツ タイプは、application/xml または application/json です。デフォルトの応答のコンテンツ タイプは要求のコンテンツ タイプと同じになります。つまり入力データが xml 形式であれば応答データも xml 形式になります。これらは、追加のクエリー パラメータ「responseType」を指定することにより、変更できます。パラメータで指定できる値は「xml」または「json」です。たとえば、xml で入力した場合、URL で responseType-json を指定すると、応答は json 形式で返されます。

.

表 3-30 サービス項目に対する作成/更新/削除 API

領域
例

Core API

サービス項目の作成

POST URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitem/process

xml:

<serviceitem>
<name>custom_sitype</name>
<serviceItemData>
<serviceItemAttribute name="Name">sit1</serviceItemAttribute>
<serviceItemAttribute name="Field1">a</serviceItemAttribute>
<serviceItemAttribute name="Field2">b</serviceItemAttribute>
</serviceItemData>
</serviceitem>

json:

{
"serviceitem" : {
"name" : "custom_sitype",
"serviceItemData" : {
"serviceItemAttribute" : [ {
"name" : "Name",
"value" : "sit1"
}, {
"name" : "Field1",
"value" : "a"
}, {
"name" : "Field2",
"value" : "b"
} ]
}
}
}

サービス項目の更新

PUT URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitem/process

xml:

<serviceitem>
<name>custom_sitype</name>
<serviceItemData>
<serviceItemAttribute name="Name">sit1</serviceItemAttribute>
<serviceItemAttribute name="Field1">a</serviceItemAttribute>
<serviceItemAttribute name="Field2">b</serviceItemAttribute>
</serviceItemData>
</serviceitem>

サービス項目の削除

DELETE URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitem/process

xml:

<serviceitem>
<name>custom_sitype</name>
<serviceItemData>
<serviceItemAttribute name="Name">sit1</serviceItemAttribute>
</serviceItemData>
</serviceitem>

 

サービス項目のカスタム操作

サービス項目に対してカスタム操作を実行します。

PUT URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitem/process?operation=test

xml:

<serviceitem>
<name>custom_sitype</name>
<serviceItemData>
<serviceItemAttribute name="Name">sit1</serviceItemAttribute>
<serviceItemAttribute name="Field1">a</serviceItemAttribute>
<serviceItemAttribute name="Field2">b</serviceItemAttribute>
</serviceItemData>
</serviceitem>

 

サービス項目を作成し、特定の OU に関連付ける

サービス項目を作成し、要求データでサービス項目のサブスクリプション詳細を指定することにより、サービス項目を特定の OU や個人などと関連付けます。

POST URL:

http://<ServerURL>/RequestCenter/nsapi/serviceitem/process

xml:

<serviceitem>
<name>custom_sitype</name>
<serviceItemData>
<serviceItemAttribute name="Name">sit1</serviceItemAttribute>
<serviceItemAttribute name="Field1">a</serviceItemAttribute>
<serviceItemAttribute name="Field2">b</serviceItemAttribute>
<subscription>
<loginID>admin</loginID>
<ouname>testOU1</ouname>
<accountName>account1</accountName>
<requisitionEntryID>6</requisitionEntryID>
</subscription>
</serviceItemData>
</serviceitem>
 

json:

{
"serviceitem" : {
"name" : "custom_sitype",
"serviceItemData" : {
"serviceItemAttribute" : [ {
"name" : "Name",
"value" : "sit1"
}, {
"name" : "Field1",
"value" : "a"
}, {
"name" : "Field2",
"value" : "b"
} ],
"subscription" : {
"loginID" : "admin",
"ouname" : "testOU1",
"accountName" : "account1",
"requisitionEntryID" : ""
}
}
}
}

フィルタ

フィルタはサポートされません。

ソート カラム

ソートは許可されません。

応答 XML

xml:

<nsapi-response>
<status-message>
<value>Service item [sit1] successfully created.</value>
</status-message>
</nsapi-response>
 
<nsapi-response>
<status-message>
<value>Operation 'Test' of service item [sit1] successfully performed.</value>
</status-message>
</nsapi-response>
 

json:

{
"nsapi-response" : {
"status-messages" : [ {
"value" : "Service item [sit140211] successfully created."
} ]
}
}

権限の付与または取り消し

nsAPI は、サービス項目および標準の権限の割り当てと取り消しに対してのみサポートされます。SI インスタンス データに対するレコード レベルの権限の定義は、SIM モジュールから、または nsAPI を使ってのみ可能です（Org Designer からはできません）。

 

表 3-31 権限の付与および取り消し API テーブル

領域
例

コア API

権限の付与

サービス項目および標準に対する権限を付与します。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/rbac/extensibleschema/grantpermission

SIM RBAC に関連するすべての権限は、この nsAPI によって実行できます。

  • 特定の SI グループ/すべての SI グループ/標準グループの定義の権限をロールに付与します。
  • 特定のサービス項目/すべてのサービス項目/標準の定義の権限をロールに付与します。
  • 特定のサービス項目/すべてのサービス項目/標準のインスタンス データの権限をロールに付与します。
  • 特定の SI インスタンス/レコードに対する SI インスタンス レベル/レコード レベルの権限を、個人/OU/グループ/ロール/アカウントに付与します。
  • すべてのオブジェクトに対する「Maintain Billing Rates（課金レートの維持）」権限を付与します。

権限の取り消し

サービス項目および標準に対する権限を取り消します。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/rbac/extensibleschema/revokepermission

SIM RBAC に関連するすべての権限は、この nsAPI によって実行できます。

  • ロールに付与されている、特定の SI グループ/すべての SI グループ/標準グループの定義の権限を取り消します。
  • ロールに付与されている、特定のサービス項目/すべてのサービス項目/標準の定義の権限を取り消します。
  • ロールに付与されている、特定のサービス項目/すべてのサービス項目/標準のインスタンス データの権限を取り消します。
  • 個人/OU/グループ/ロール/アカウントに付与されている、特定の SI インスタンス/レコードに対する SI インスタンス レベル/レコード レベルの権限を取り消します。
  • すべてのオブジェクトに対する「Maintain Billing Rates（課金レートの維持）」権限を取り消します。

フィルタ

フィルタはサポートされません。

ソート カラム

ソートは許可されません。

要求 XML

権限の付与：

ヘッダー：<Username> <password> および <Content-Type=application/xml> Method=POST

<?xml version="1.0" encoding="UTF-8"?>
<grantpermission scope="SpecificObject/AllObjects" object="Instance/Definition/Group" recipient="Role/OrgUnit/Person/Group/ProjectAccount/TenantAccount" recipientName=<Name of the Recipient> recipientType="ServiceTeam/BuisnessUnit - Applicable only if the recipient is set to OrgUnit" domain="ServiceItem/Standard" permission=<Logical Names> instanceName=<Name of the Instance if object="Instance"> objectName=<Name of the attribute object> />
 

例：

<?xml version="1.0" encoding="UTF-8"?>
<grantpermission scope="SpecificObject" object="Instance" recipient="OrgUnit" recipientName="test5466" recipientType="ServiceTeam" domain="ServiceItem" permission="mdr_record_read" instanceName="Cap" objectName="SravItem"/>
 

権限の取り消し：

ヘッダー：<Username> <password> および <Content-Type=application/xml> Method=POST

<?xml version="1.0" encoding="UTF-8"?>
<revokepermission scope="SpecificObject/AllObjects" object="Instance/Definition/Group" recipient="Role/OrgUnit/Person/Group/ProjectAccount/TenantAccount" recipientName=<Name of the Recipient> recipientType="ServiceTeam/BuisnessUnit - Applicable only of the recipient is set to OrgUnit" domain="ServiceItem/Standard" permission=<Logical Names> instanceName=<Name of the Instance if object="Instance"> objectName=<Name of the attribute object> />
 

例：

<?xml version="1.0" encoding="UTF-8"?>
<revokepermission scope="SpecificObject" object="Instance" recipient="OrgUnit" recipientName="test5466" recipientType="ServiceTeam" domain="ServiceItem" permission="mdr_record_read" instanceName="Cap" objectName="SravItem"/>
 

特定のオブジェクトにユーザが付与/取り消しできる権限の詳細については、 特定のオブジェクトにユーザが付与/取り消しできる権限 の表を参照してください。

表 3-32 特定のオブジェクトにユーザが付与/取り消しできる権限

範囲
UI ラベル
権限
object=
“Definition“,
domain= “ServiceItem“
object=
“Group“,
domain= “ServiceItem“
object=
“Instance“,
domain= “ServiceItem“
object=
“Definition“,
domain= “Standard“
object=
“Group“,
domain= “Standard“
object=
“Instance“,
domain= “Standard“

AllObjects/SpecificObject
[読み取り（Read）]
mdr_record_read
N/A
N/A
AllObjects には適用されない。インスタンス名が NULL ではない場合は、特定のオブジェクトに適用可能
N/A
N/A
N/A

書き込み（Write）

mdr_record_write

N/A

N/A

AllObjects には適用されない。インスタンス名が NULL ではない場合は、特定のオブジェクトに適用可能

N/A

N/A

N/A

読み取り定義

mdr_datatype_read

適用可能

N/A

N/A

適用可能

N/A

N/A

ReadWrite 定義

mdr_datatype_write

適用可能

N/A

N/A

適用可能

N/A

N/A

すべてのインスタンス データの読み取り

content_def_read_allcontentdata

N/A

N/A

適用可能

N/A

N/A

適用可能

すべてのインスタンス データの読み取り/書き込み

content_def_write_allcontentdata

N/A

N/A

適用可能

N/A

N/A

適用可能

個人の BU のすべてのインスタンス データの読み取り

allinstancedata_my_bu_read

N/A

N/A

適用可能

N/A

N/A

N/A

個人の BU のすべてのインスタンス データの読み取り/書き込み

allinstancedata_my_bu_write

N/A

N/A

適用可能

N/A

N/A

N/A

個人の BU およびその下位単位のすべてのインスタンス データの読み取り

allinstancedata_my_bu_hierarachy_read

N/A

N/A

適用可能

N/A

N/A

N/A

個人の BU およびその下位単位のすべてのインスタンス データの読み取り/書き込み

allinstancedata_my_bu_hierarachy_write

N/A

N/A

適用可能

N/A

N/A

N/A

個人のテナント アカウントのすべてのインスタンス データの読み取り

allinstancedata_my_tenantaccount_read

N/A

N/A

適用可能

N/A

N/A

N/A

個人のテナント アカウントのすべてのインスタンス データの読み取り/書き込み

allinstancedata_my_tenantaccount_write

N/A

N/A

適用可能

N/A

N/A

N/A

個人のプロジェクト アカウントのすべてのインスタンス データの読み取り

allinstancedata_my_projectaccount_read

N/A

N/A

適用可能

N/A

N/A

N/A

個人のプロジェクト アカウントのすべてのインスタンス データの読み取り/書き込み

allinstancedata_my_projectaccount_write

N/A

N/A

適用可能

N/A

N/A

N/A

自己がサブスクライブするすべてのインスタンス データの読み取り

allinstancedata_subscribed_self_read

N/A

N/A

N/A

N/A

N/A

N/A

自己がサブスクライブするすべてのインスタンス データの読み取り/書き込み

allinstancedata_subscribed_self_write

N/A

N/A

N/A

N/A

N/A

N/A

新しいインスタンス データの作成

create_new_service_item

N/A

N/A

適用可能

N/A

N/A

N/A

新しい標準のインスタンス データの作成

create_new_standard_instance_data

N/A

N/A

N/A

N/A

N/A

適用可能

このグループのすべての定義の読み取り

mdr_class_read

N/A

適用可能

N/A

N/A

適用可能

N/A

このグループのすべての定義の読み取り/書き込み

mdr_class_write

N/A

適用可能

N/A

N/A

適用可能

N/A

AllObjects

MaintainBilling Rates

billingrates_maintain

object=“Definition“

N/A

domain=“Billing“

object=“Definition“

N/A

N/A

標準（Standards）

 

表 3-33 標準 API テーブル

領域
例

コア API

Name による取得

デフォルトでは、指定した標準の最初の 50 個のエントリが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/standard/<standardName>

Java の例

StandardDTO standards = NSApiClient.getStandard().getStandardData("<standardName>", null);

フィルタ

最大 3 つのフィルタがサポートされます。

REST URL:

比較演算子：

  • 数値/日付カラム：=、>、<、>=、<=（大文字小文字の区別あり）
  • 文字列カラム：=（like、contains、および starts-with 演算子については後述）

関係演算子：AND、OR（大文字と小文字を区別しない、オーダーの優先順位はサポートされていません）

フィルタ区切り文字：|

サポートされるカラム：すべてのカラム

http://<ServerURL>/RequestCenter/nsapi/standard/<standardName>/<columnName1><operator1><value1>[|<AND|OR>|<columnName2><operator2><value2>][|<AND|OR>|<columnName3><operator3><value3>]

Java の例

String filter: "<columnName1><operator1><value1>|<and|or>|<columnName2><operator2><value2>|<and|or>|<columnName3><operator3><value3>";
StandardDTO standards = NSApiClient.getStandard().getStandardDataWithFilters("<standardName>", filter);

 

文字列カラムのフィルタ

%（starts with）演算子がサポートされています。

*（contains）演算子がサポートされています。

（ends with）演算子はサポートされていません。

例：

Name=service*
Name=*g*
Name=*g -- not allowed
 

REST URL:

http://<ServerURL>/RequestCenter/nsapi/standard/<standardName>/<columnName>=<wildcardName>

Java の例

StandardDTO standards = NSApiClient.getStandard().getStandardDataWithFilters("<standardName>", "<wildcardName>");

 

日付カラムのフィルタ

日付フィールドの値は mm-dd-yyyy 形式にする必要があります。

比較演算子：=、>、<、<=、>=

例：

SubmittedDate=12-10-2010
 

REST URL:

http://<ServerURL>/RequestCenter/nsapi/standard/<standardName>/<columnName><operator><mm-dd-yyyy>

Java の例

StandardDTO standards = NSApiClient.getStandard().getStandardDataWithFilters("<standardName>", "<columnName><operator><mm-dd-yyyy>");

ソート カラム

すべてのテーブル カラム。

応答 XML
<standard totalCount="x" startRow="y" recordSize="z" id="a">
<logi n Name></loginName>
<name></name>
<standardData rowId="">
...
<standardAttribute name="id" />
...
<standardURL><a ></a></standardURL>
<standardURLOnly> </standardURLOnly>
...
</standardData>
</standard>

サービス カタログ（Service Catalog）のデータ

カスタム コンテンツ（Custom Content）

カスタム コンテンツは、サービス ポータルのコンテンツのソースとして機能する、ユーザ定義のテーブルにより構成されます。これらのテーブルは、標準と同様にポートレットのデータ ソースとして参照されます。

 

表 3-34 カスタム コンテンツ API テーブル

領域
例

コア API

Name による取得

デフォルトでは、指定したテーブルの最初の 50 個のエントリが返されます。

REST URL:

http://<ServerURL>/RequestCenter/nsapi/customcontent/<customContentName>

Java の例

CustomContentDTO customs = NSApiClient.getCustomContent().getcontentData("<customContentName>", null);

フィルタ

すべてのカスタム コンテンツ カラムがサポートされています。

%（starts with）演算子がサポートされています。

（ends with）演算子はサポートされていません。

例：

Name=custom*
Name=*g -- not allowed
 

REST URL:

比較演算子：=、>、<、>=、<=（大文字小文字の区別あり）

関係演算子：AND、OR（大文字小文字の区別あり）

フィルタ区切り文字：|

サポートされるカラム：すべてのカラム

http://<ServerURL>/RequestCenter/nsapi/customcontent/<customContentName>/<columnName1><operator1><value1>[|<AND|OR>|<columnName2><operator2><value2>][|<AND|OR>|<columnName3><operator3><value3>]

http://<ServerURL>/RequestCenter/nsapi/customcontent/<customContentName>/<columnName>=<wildcardName>

http://<ServerURL>/RequestCenter/nsapi/customcontent/<customContentName>/<columnName><operator><mm-dd-yyyy>

Java の例

String filter = "<columnName><operator><value>";
CustomContentDTO customs = NSApiClient.getCustomContent().getcustomContentDataWithFilters("CoPortalContent", filter);

ソート カラム

すべてのテーブル カラム

応答 XML
<customContent totalCount="x" startRow="y" recordSize="z" id="a">
<logicName></logicName>
<name></name>
...
<customContentData rowId="">
<customContentAttribute name=" "></customContentAttribute>
...
</customContentData>
</customContent>

全カラム名のリスト、および各エンティティの説明については、『 Cisco Prime Service Catalog Designer Guide 』の「Designing Portals」の章にある「Reference Data」の項を参照してください。

テナント管理

表 3-35 テナント管理 API テーブル

領域
例

Get API

ユーザ ロールを取得する API

Method: GET

REST URL: http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/userroles

サンプル応答：

{
"roles": {
"startRow": 0,
"totalCount": 0,
"recordSize": 0,
"role": [
{
"roleId": 73,
"roleName": "Service Administrator",
"statusId": 1,
"roleTypeId": 2,
"logicName": "service-administrator",
"inherited": false,
"parentId": 0
},
{
"roleId": 1336,
"roleName": "Team Administrator",
"statusId": 1,
"roleTypeId": 2,
"logicName": "team-administrator",
"inherited": false,
"parentId": 0
}
]
}
}

Get API

テナント管理設定を取得する API

Method: GET

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/tenantconfiguration

 

サンプル応答：

{
"ArrayList": [
{
"name": "TenantType",
"value": "Multi"
},
{
"name": "TenantID",
"value": "System generated UUID"
},
{
"name": "TenantName",
"value": "User ID"
},
{
"name": "Organization",
"value": "CSV list imported"
},
{
"name": "Billing",
"value": "Active"
},
{
"name": "BillingType",
"value": "Credit Card"
},
{
"name": "BillingDept",
"value": "Dynamic join to people data in LDAP"
},
{
"name": "FinApp",
"value": "Yes"
},
{
"name": "FinAppType",
"value": "Add approvers using CSV"
},
{
"name": "EntApp",
"value": "Yes"
},
{
"name": "TenantApp",
"value": "Yes"
},
{
"name": "TenantAppType",
"value": "Parent Tenant Admin (Multi Only)"
}
]
}

（注） 設定を行っていない場合、応答は ArrayList: [ ] となります。

Get API

管理者メンバー情報を含むカードおよびリストを表示するため、階層的チームとチーム詳細を取得する API

Method: GET

REST URL: http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/id/{teamId}

サンプル要求：
http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/id/1040

サンプル応答：

{
"TeamList": {
"startRow": 0,
"totalCount": 2,
"recordSize": 0,
"teams": [
{
"teamName": "Root Team",
"teamId": 39,
"statusId": 0,
"status": "Active",
"parentId": 0,
"parentName": "",
"accountId": 22,
"hasChild": false,
"memberCount": 2,
"createdOn": 1477035094013,
"createdOnString": "10/21/2016 12:31 AM",
"adminMembers": [
{
"memberName": "root cisco",
"memberId": 25,
"status": "Active",
"email": "root@cisco.com",
"type": "Team Admin"
}
],
"rootTenant": "T122",
"parentTenant": "",
"rootTenantDisplayName": "Root Team",
"currentTenantAdmin": false,
"currentParentTenantAdmin": true
},
{
"teamName": "Tenant A",
"teamId": 1040,
"statusId": 0,
"status": "Active",

 
"parentId": 0,
"parentName": "",
"accountId": 23,
"hasChild": true,
"memberCount": 2,
"createdOn": 1478049861410,
"createdOnString": "11/01/2016 6:24 PM",
"childTeams": [
{
"teamName": "Tenant B",
"teamId": 1041,
"statusId": 0,
"status": "Active",
"parentId": 1040,
"parentName": "Tenant A",
"accountId": 23,
"hasChild": true,
"memberCount": 2,
"createdOn": 1478050009523,
"createdOnString": "11/01/2016 6:26 PM",
"adminMembers": [
{
"memberName": "adminB cisco",
"memberId": 35,
"status": "Active",
"email": "adminB_tl@cisco.com",
"type": "Team Admin"
}
],
"rootTenant": "T123",
"parentTenant": "T123",
"rootTenantDisplayName": "Tenant A",
"currentTenantAdmin": false,
"currentParentTenantAdmin": false
}
],
"adminMembers": [
{
"memberName": "UserA UserA",
"memberId": 14,
"status": "Active",
"email": "usera_tl@cisco.com",
"type": "Team Admin"
}
],
"rootTenant": "T123",
"parentTenant": "",
"rootTenantDisplayName": "Tenant A",
"currentTenantAdmin": false,
"currentParentTenantAdmin": false
}
]
}
}
For the first time loading data, you have to pass teamid=0.
For example: http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/id/0
 

（注） 関連付けられたテナント アカウントを持っていない場合、{} という空の応答が受信されます。

Get API

管理者メンバー情報を含むリストを表示するため、チーム リストを取得する API

searchPattern は *name* という形式になります。

SortBy：Name、Status、CreatedOn

SortDir：Asc、Desc

Method: GET

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/teamlist?startRow={startRow}&recordSize={recordSize}&sortBy={sortBy}&sortDir={sortDir}&name={searchName}

サンプル要求：

http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/teamlist?startRow=1&recordSize=20&sortBy=Nams&sortDir=Asc&name=*

サンプル応答：

{
"TeamList": {
"startRow": 1,
"totalCount": 4,
"recordSize": 20,
"teams": [
{
"teamName": "Root Team",
"teamId": 39,
"statusId": 0,
"status": "Active",
"parentId": 0,
"parentName": "",
"accountId": 22,
"hasChild": false,
"memberCount": 2,
"createdOn": 1477035094013,
"createdOnString": "10/21/2016 12:31 AM",
"adminMembers": [
{
"memberName": "root cisco",
"memberId": 25,
"status": "Active",
"email": "root@cisco.com",
"type": "Team Admin"
}
],
"rootTenant": "T122",
"parentTenant": "",
"rootTenantDisplayName": "Root Team",
"currentTenantAdmin": false,
"currentParentTenantAdmin": false
},

 
{
"teamName": "Tenant A",
"teamId": 1040,
"statusId": 0,
"status": "Active",
"parentId": 0,
"parentName": "",
"accountId": 23,
"hasChild": true,
"memberCount": 2,
"createdOn": 1478049861410,
"createdOnString": "11/01/2016 6:24 PM",
"adminMembers": [
{
"memberName": "UserA UserA",
"memberId": 14,
"status": "Active",
"email": "usera_tl@cisco.com",
"type": "Team Admin"
}
],
"rootTenant": "T123",
"parentTenant": "",
"rootTenantDisplayName": "Tenant A",
"currentTenantAdmin": false,
"currentParentTenantAdmin": false
},
{
"teamName": "Tenant B",
"teamId": 1041,
"statusId": 0,
"status": "Active",
"parentId": 1040,
"parentName": "Tenant A",
"accountId": 23,
"hasChild": true,
"memberCount": 2,
"createdOn": 1478050009523,
"createdOnString": "11/01/2016 6:26 PM",
"adminMembers": [
{
"memberName": "adminB cisco",
"memberId": 35,
"status": "Active",
"email": "adminB_tl@cisco.com",
"type": "Team Admin"
}
],
"rootTenant": "T123",
"parentTenant": "T123",
"rootTenantDisplayName": "Tenant A",
"currentTenantAdmin": false,
"currentParentTenantAdmin": false
},

 
{
"teamName": "Tenant C",
"teamId": 1042,
"statusId": 0,
"status": "Active",
"parentId": 1041,
"parentName": "Tenant B",
"accountId": 23,
"hasChild": false,
"memberCount": 1,
"createdOn": 1478050137437,
"createdOnString": "11/01/2016 6:28 PM",
"adminMembers": [
{
"memberName": "adminC cisco",
"memberId": 36,
"status": "Active",
"email": "adminC_tl@cisco.com",
"type": "Team Admin"
}
],
"rootTenant": "T123",
"parentTenant": "T124",
"rootTenantDisplayName": "Tenant A",
"currentTenantAdmin": false,
"currentParentTenantAdmin": false
}
]
}
}

Get API

親チーム ID でサブチームを取得する API

searchPattern は *name* という形式になります。

SortBy：Name、Status、CreatedOn、または MemberCount

SortDir：Asc、Desc

Method: GET

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/id/{teamid}/teamlist?startRow={startRow}&recordSize={recordSize}&sortBy={sortBy}& sortDir={
sortDir}&name={searchName}

サンプル要求：

http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/id/3/teamlist?startRow=1&recordSize=10&sortBy=Name& sortDir=Asc&name=*

サンプル応答：

{
"TeamList": {
"startRow": 1,
"totalCount": 2,
"recordSize": 10,
"teams": [
{
"teamName": "Program Management",
"teamId": 4,
"statusId": 1,
"status": "Active",
"parentId": 3,
"parentName": "Cisco Team",
"accountId": 0,
"hasChild": false,
"memberCount": 3,
"createdOn": 1475721937253,
"createdOnString": "10/05/2016 7:45 PM"
},
{
"teamName": "UX Team",
"teamId": 5,
"statusId": 2,
"status": "Inactive",
"parentId": 3,
"parentName": "Cisco Team",
"accountId": 0,
"hasChild": false,
"memberCount": 0,
"createdOn": 1475721947930,
"createdOnString": "10/05/2016 7:45 PM"
}
]
}
}

Get API

チーム メンバー リストを取得する API

SortBy：Name、Email、または Status

SortDir：Asc、Desc

SearchName：*name*

Method: GET

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/id/{teamId}/memberlist?startRow={startRow}&recordSize={recordSize}&sortBy={sortBy}& sortDir={
sortDir}&name={searchName}

サンプル要求：

http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/id/3/memberlist?startRow=1&recordSize=10&sortBy=Name&sortDir=ASc&name=*

サンプル応答：

{
"TeamMemberList": {
"startRow": 1,
"totalCount": 3,
"recordSize": 10,
"teamMembers": [
{
"memberName": "admin admin",
"memberId": 1,
"status": "Active",
"email": "thanes_demo@cisco.com",
"type": "Member"
},
{
"memberName": "Ryan Marfone",
"memberId": 5,
"status": "Active",
"email": "Ryan@cisco.com",
"type": "Team Admin"
},
{
"memberName": "test test",
"memberId": 3,
"status": "Active",
"email": "test@test.com",
"type": "Team Admin"
}
]
}
}

Post API

メンバーを AS チーム管理者に昇格させる API

この API は、次のことを行います。

  • ユーザへの team-admin ロールの割り当て
  • 既存チームの管理者ユーザから team-admin ロールの割り当てを解除
  • 既存チームの管理者ユーザへの it-user ロールの割り当て

Method: POST

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/id/{teamId}/people/id/{personId}/promoteTeamAdmin

サンプル要求：

http://<ServerURL>/RequestCenter/nsapi/directory/tenant/v2/id/3/people/id/10/promoteTeamAdmin

サンプル応答：

{
"status-message": {
"code": "TA_054",
"value": "User is promoted to Team Admin successfully"
}
}
 

エラー応答：

{
"status-message": {
"code": " TA_030",
"value": "Cannot promote user to a team admin, user is already a team admin"
}
}

Post API

Cloud Center ユーザの API キーの更新

Method: POST

REST URL:

http://<ServerURL>/RequestCenter/nsapi/directory/people/id/{personId}/updateapikey

サンプル要求：

http://<ServerURL>/RequestCenter/nsapi/directory/people/id/10/updateapikey

サンプル応答：

{
"status-message": {
"code": "TA_054",
"value": "API Key updated successfully"
}
}
 

エラー応答：

{
"status-message": {
"code": "TA_054",
"value": "Cloud Center User ID does not exist"
}
}
 

エラー応答：

{
"status-message": {
"code": "TA_054",
"value": "Cloud Center Profile for the User does not exist"
}
}

Catalog Deployer API

表 3-36 Catalog Deployer API

領域
例

Rex API

サービス データの取得

Method: GET

REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/service/{name}

要求ヘッダーのパラメータ：ユーザ名およびパスワード

応答：rex xml

カテゴリ データの取得

Method: GET

REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/category/{name}

要求ヘッダーのパラメータ：ユーザ名およびパスワード

応答：rex xml

Rex API

組織データの取得

Method: GET

REST URL:
http://<ServerURL>/RequestCenter/rexapi/entity/organizationalunit/{name}

要求ヘッダーのパラメータ：ユーザ名およびパスワード

応答：rex xml

rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。

グループ データの取得

Method: GET

REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/group/{name}

要求ヘッダーのパラメータ：ユーザ名およびパスワード

応答：rex xml

rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。

個人データの取得

Method: GET

REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/person/{name}

要求ヘッダーのパラメータ：ユーザ名およびパスワード

応答：rex xml

rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。

キュー データの取得

Method: GET

REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/queue/{name}

要求ヘッダーのパラメータ：ユーザ名およびパスワード

応答：rex xml

rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。

役職データの取得

Method: GET

REST URL:

http://<ServerURL>/RequestCenter/rexapi/entity/functionalposition/{name}

要求ヘッダーのパラメータ：ユーザ名およびパスワード

応答：rex xml

rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。

Rex API

ロール データの取得

Method: GET

REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/role/{name}

要求ヘッダーのパラメータ：ユーザ名およびパスワード

応答：rex xml

rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。

電子メール テンプレートのデータの取得

Method: GET

REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/emailtemplate/{name}

要求ヘッダーのパラメータ：ユーザ名およびパスワード

応答：rex xml

rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。

エージェント データの取得

Method: GET

REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/agent/{name}

要求ヘッダーのパラメータ：ユーザ名およびパスワード

応答：rex xml

rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。

rex データの取得

Method: POST

REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/getdata

要求ヘッダーのパラメータ：ユーザ名およびパスワード

応答：rex xml

rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。

（注） 戻される xml にはヘッダー パラメータは含まれません。

データのインポート

Method: POST

REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/putdata

要求ヘッダーのパラメータ：ユーザ名およびパスワード

要求の本文：rex xml

rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。

Rex XML 構造の例

Service:
<rex>
<Header requestAction="put"/>
<ServiceDefinitions>
<ServiceDefinition name="Service A" serviceGroupName="0 Service Icons" catalogName="" type="notspecified" isActive="true" isReportable="false" isEntitlement="false" isOrderable="true" computePrice="false" authorizations="site" canStartLater="false" dateQuality="tbd" guid="EBC80F54-01E3-45C1-8DF2-1C35C1165838" orderingMode="Add review enabled" paginationViewMode="Classic View" hideInServiceCatalog="false" isTemplate="false" showOrderSummary="false" maxQuantity="0" isBaseService="false">
<Transaction actionRequested="getXml" actionResult="Succeeded" actionResultCode="0" actionTaken="fetched" detail=""/>
<Duration value="0.0" units="hours" isDefinedDuration="false"/>
<Billing rate="0.0" type="none"/>
<Expensing expenseCode=""/>
<Authorization>
<ServiceGroupReview>
<AuthRoles/>
<Escalations/>
</ServiceGroupReview>
<ServiceGroupAuthorization>
<AuthRoles/>
<Escalations/>
</ServiceGroupAuthorization>
</Authorization>
<Presentation>
<Description>
<Icon documentId="0"/>
</Description>
<SectionOne isEnabled="false"/>
<SectionTwo isEnabled="false"/>
<SectionThree isEnabled="false"/>
</Presentation>
<PositionNames>
<PositionName name="Author" type="Service" serviceDefinitionName="Service A" serviceDefinitionGuid="EBC80F54-01E3-45C1-8DF2-1C35C1165838" objectType="Person" instanceName="admin"/>
</PositionNames>
<Categories>
<ConsumerServicesCategories/>
<ServicePortfoliosCategories/>
</Categories>
<AssociatedKeywords/>
<AssociatedObjectives/>
<Pricing price="0.0" pricingSchema="fixedprice" pricingSchemaString="Fixed Price" priceDisplaySchema="" priceDisplaySchemaString="">
<Description>
<Text>
<![CDATA[]]>
</Text>
</Description>
</Pricing>
<Costing>
<Costs/>
</Costing>
<ServiceLevel/>
<Bundling canBeBundled="true" isABundle="false">
<ServiceContainsServices/>
<ServiceIsContainedByServices/>
</Bundling>
<ServicePreRequisites/>
<ServiceAccessories/>
<Manufacturer name="" partNumber=""/>
<Supplier name="" type="" partNumber=""/>
<Plans>
<Plan>
<PlanAttributes type="delivery" name="PrimaryDeliveryPlan" subtaskFlow="sequential" maxDepth="1" hoursPerDay="8.0" isAutomaticStart="true">
<PlanSubject>
<![CDATA[<s ID="11"><p>#Name#</p></s>]]>
</PlanSubject>
<PlanMonitorTask>
<PlanMonitorWorkflowRoles>
<PlanMonitorWorkflowRole assignmentMethod="none" expression=""/>
</PlanMonitorWorkflowRoles>
<Notifications>
<Notification eventType="plantaskcanceled" emailTemplate=""/>
</Notifications>
</PlanMonitorTask>
</PlanAttributes>
<Tasks/>
<Escalations/>
</Plan>
</Plans>
<DictionaryFormAccessPolicies/>
<ServiceForms/>
<RelatedEntities>
<Forms/>
<ServiceGroups>
<ServiceGroupName name="0 Service Icons" guid="956A6E7B-1FB6-4B49-B258-C58F5AC727D3"/>
</ServiceGroups>
<Categories/>
<EmailTemplates/>
<Objectives/>
<ServiceDefinitions/>
<Keywords/>
<Persons/>
<OrganizationalUnits/>
<Queues/>
<Agents/>
</RelatedEntities>
<PermissionsAssignment>
<OperationsWeArePermitted/>
<OperationsTheyArePermitted>
<Operation name="service_change_rights" displayName="service_change_rights">
<Objects/>
</Operation>
<Operation name="service_change_delivery" displayName="service_change_delivery">
<Objects/>
</Operation>
<Operation name="service_change_forms" displayName="service_change_forms">
<Objects/>
</Operation>
<Operation name="service_change_presentation" displayName="service_change_presentation">
<Objects/>
</Operation>
<Operation name="service_order_service" displayName="service_order_service">
<Objects/>
</Operation>
</OperationsTheyArePermitted>
</PermissionsAssignment>
<Images/>
<ServiceExtensions/>
<BaseTemplateID>
<![CDATA[0]]>
</BaseTemplateID>
</ServiceDefinition>
</ServiceDefinitions>
</rex>

REST API 要求のレート制限の設定

Prime Service Catalog の管理者はレート リミッタにより、許可される要求数および許可される要求の時間帯（秒数）をグローバルに設定します。

要求（外部アプリケーションからの要求、または Prime Service Catalog UI 内の要求）は、設定に従って受け入れられ、設定の制限を超えると拒否されます。

要求が拒否された場合、レート制限に対する HTTP 応答コード- 429 Too Many Requests (RFC 6585) が要求ユーザに返されます。

次のグローバルなデフォルト値がレート制限機能のために管理者によって設定されます。

  • enabled：このフラグは true（REST 呼び出しのレート制限を有効にする）または false（REST 呼び出しのレート制限を無効にする）に設定されます（API または UI ベースの nsAPI REST 呼び出しに適用されるグローバル設定）。このフラグはデフォルトで無効ですが、nsApiRateLimit.json ファイルを設定してレート制限を有効にできます。フラグの設定は、グローバルおよびすべての上書きに均等に適用されます。さらに、UI または外部アプリケーションからの nsAPI REST 呼び出しに対して、別のレート制限を定義できます。
  • nsApiRateLimit：許可される呼び出しの最大数を指定します。
  • nsApiRateIntervalSecs：nsApiRateLimit により設定される要求が許可される時間帯（秒数）を指定します。

さらに、管理者は次の修飾子を使用して、グローバル（デフォルト）値を上書きできます（特定の URL、1 つ以上のメソッドが上書きされます）。

（注） 時間帯は上書きできません。上書きでは毎回、グローバル設定を使用します。

  • url：nsAPI の Rest URI は完全 URL か、またはワイルドカード（*）を使った URL です。ワイルド カードが使用されない場合は、入力 URI と設定される URL が完全一致すると想定されます。設定のクエリー パラメータはすべて、レート リミッタにより省略されます。
  • method：HTTP メソッドは 1 つまたは複数の ["GET", "PUT", "POST", "DELETE"] を含む文字列リテラル配列です。
  • nsApiRateLimit：許可される呼び出しの最大数を指定します。これは、この URI だけに対する同様のグローバル設定を上書きします。

次の JSON 構造に従ってレート制限を設定します。

（注） JSON の検証は手動で行います。設定ファイル nsAPIRateLimit.json を保存する際に、アプリケーションは JSON の検証を行いません。このため、無効な JSON の場合にアプリケーションが動作しないことがあります。

{
"api": {
"config": {
"enabled": "false",
"nsApiRateLimit": 2,
"nsApiRateIntervalSecs": 10,
"overrides": [
{
"url": "/nsapi/serviceitem/SiServItem*",
"method": [
"GET"
],
"nsApiRateLimit": 5
},
{
"url": "/nsapi/serviceitem/*",
"method": [
"GET"
],
"nsApiRateLimit": 3
},
{
"url": "/nsapi/serviceitem/*",
"method": [
"POST",
"PUT"
],
"nsApiRateLimit": 3
},
{
"url": "/nsapi/transaction/authorizations/*",
"method": [
"GET",
"PUT",
"POST",
"DELETE"
],
"nsApiRateLimit": 8
},
{
"url": "/nsapi/transaction/authorizations/ViewName=Authorizations%20for%20Self| Status=Approved",
"method": [
"GET",
"PUT",
"POST",
"DELETE"
],
"nsApiRateLimit": 3
},
{
"url": "/nsapi/definition/categories",
"method": [
"GET",
"PUT",
"POST",
"DELETE"
],
"nsApiRateLimit": 5
}
]
}
},
"ui": {
"config": {
"enabled": "false",
"nsApiRateLimit": 4,
"nsApiRateIntervalSecs": 10,
"overrides": [
{
"url": "/nsapi/transaction/requisitions/*",
"method": [
"GET",
"PUT",
"POST",
"DELETE"
],
"nsApiRateLimit": 3
},
{
"url": "/nsapi/transaction/authorizations/*",
"method": [
"GET",
"PUT",
"POST",
"DELETE"
],
"nsApiRateLimit": 3
},
{
"url": "/nsapi/definition/categories",
"method": [
"GET",
"PUT",
"POST",
"DELETE"
],
"nsApiRateLimit": 5
}
]
}
}

}

エラー メッセージ

例外の性質に応じて、異なる HTTP 応答コードが nsAPI により返されます。

  • HTTP ステータス コード 400 Mandatory Field Missing Error / Redirect URL or EntityID from metadata already exists / Duplicate IDP configuration name：フィールド未入力エラー、メタデータ情報がすでに存在する、または IDP 設定名の重複。
  • 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 (there is no person with 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 （Internal Error）および XML エラー応答メッセージ「 Internal Error: Invalid parameter values specified or unexpected error 」：不適切なパラメータ、nsAPI 内で発生するその他の例外、またはその他の一般的なサーバ エラー。

次に、例を示します。

nsapi/directory/people?startRow=5000 (non-existent 5000 row)
nsapi/directory/people?sortBy=wrongColumn&sortDir=Asc (unsupported column)
nsapi/directory/people?recordSize=-1 (negative or zero value for recordSize)
 
  • Http ステータス 422 （Unprocessable Entity）、および POST/UPDATE 操作に対する XML 妥当性検査エラー応答メッセージ：要求データの必須フィールドに値がありません。または無効な値が入っています。

nsAPI は、指定されたフィルタについて結果が見つからない場合、または無効なフィルタ条件が指定された場合にエラー メッセージを返します。次に例を示します。

<nsapi-response>
<status-code>failed</status-code>
<status-message>Service item custom_sit201 does not exist, none of the service items were updated. </status-message>
</nsapi-response>
 

nsAPI でのメソッドの実行中に発生したすべての例外について、nsAPI は Java から NSAPIException をスローします。

サポートされる操作の要約

次のチャートに、さまざまなエンティティ タイプでサポートされる操作についての要約を示します。

参照テーブル

エンティティ名
Id による取得
Name による取得
すべて取得
ワイルドカード名前検索
ソート
ページング
REST フィルタから Java クライアント メソッドへの変換
更新
フィルタ
ネストされたエンティティ
認証

認証：ログイン/ログアウト

 

 

 

 

X

 

X

 

 

 
定義データ

カテゴリ（Categories）

X

X

X

X

X

X

X

 

[カタログ タイプ（Catalog Type）]

サブカテゴリ、含まれるサービス、含まれる提供

サービス

X

X

X

X

X

X

X

 

カテゴリ ID、カテゴリ名、キーワード

カテゴリ、キーワード、組み込みサービス

契約

X

X

X

X

X

X

X

 

名前

 

エージェント（Agents）

X

X

X

X

X

X

X

 

名前

 
トランザクション データ

要求

X

 

X

 

X

X

X

 

ビュー名、ステータス

 

要求エントリ

X

 

X

 

X

X

 

 

 

 

許可

X

 

X

 

X

X

X

 

ビュー名、ステータス

 

タスク

X

 

X

 

X

X

X

 

ビュー名（View Name）

 

タスク：特定の要求エントリに関するタスク

 

 

X

 

X

X

X

 

タスクのタイプ、ステータス（Skipped）

組み込みサービスのタスク

タスク：特定の要求に関するマイルストーン

 

 

X

 

 

 

 

 

 

 

タスク：アクション

 

 

 

 

 

 

 

X

 

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
ディレクトリ データ

組織

X

X

X

X

X

X

X

 

OU Type

 

Person

X

X

X

X

X

X

X

X

OU 名、グループ名、ロール名

OU、グループ、ロール、住所、連絡先、設定、代理人

グループ（Groups）

X

X

X

X

X

X

X

 

名前

 

アカウント

X

X

X

X

X

X

X

 

名前

 
サービス項目データ

すべてのサービス項目

 

 

X

 

X

X

 

 

任意のカラム

 

サービス項目（Service Items）

 

 

X

 

X

X

X

 

任意のカラム

 

標準（Standards）

 

 

X

 

X

X

X

 

任意のカラム

 
サービス カタログ（Service Catalog）のデータ

カスタム コンテンツ（Custom Content）

 

X

X

X

X

X

X

 

任意のカラム