グループ Web サービス

npc API は、共通のグループ管理タスクを実行できる Web サービスを提供します。
capm370
NetOps Portal
API は、共通のグループ管理タスクを実行できる Web サービスを提供します。
グループ RESTful Web サービスを使用し、監視対象アイテムのグループを作成し、管理します。 新しいグループを作成し、そのグループにアイテムを手動で追加できます。 また、アイテム属性に基づくグループを作成し、入力するルールを記述することもできます。
グループの ID の検索
NetOps Portal
API コールのほとんどについて、グループの数値 groupItemId が必要です。 これらの ID を検索するために、以下の 3 つの方法を使用できます。
  1. groupItemId ルックアップ サービス
    このサービスでは、簡易 HTTP GET を使用して、1 つのグループ パスの ID を検索できます。
    「All Groups/Inventory」の ID を検索するには、
    groupItemId
    パラメータを使用します。 構文は以下のとおりです。
    http://
    PC_host
    :8181/pc/center/webservice/groups/groupPath/All
    %20
    Groups
    %2F
    Inventory/groupItemId
    全体のパスを指定する必要はありません。 たとえば、「
    groupPath/Acme%2FGroups%2FSites%2FBoston/groupItemId
    」を検索することによって、「
    All Groups/Tenants/Acme/Groups/Sites/Boston
    」グループを検索できます。
    グループ パスを指定する場合は、URL 文字列エンコーディングを使用します。 スペースは %20 で置き換える必要があり、グループは %2F によって区切る必要があります。
    返される xml は以下のとおりです。
    <groupItemId>
    <groupItemId>5</groupItemId>
    </groupItemId>
    検索は、複数のグループに一致する可能性がありますが、1 つのグループだけを返します。
  2. 一括グループ検索サービス
    このサービスでは、単一の HTTP POST を使用して、複数のグループの ID を検索できます。 構文は以下のとおりです。
    http://PC_host:8181/pc/center/webservice/groups/find
    POST する XML は以下のとおりです。
    <groups> <group Path='/All Groups/Tenants/Acme/Groups/Sites/San Francisco'/> <group Path='/All Groups/Tenants/Acme/Groups/Sites/Austin'/> <group Path='/All Groups/Tenants/Acme/Groups/Sites/Boston'/> </groups>
    任意の数のグループを検索できます。 検索される各グループのパスに対して、対応するグループ ID とグループ名が返されます。 パスがグループに一致しない場合、ID は返されません。
    上の POST に対して返される XML は、以下のとおりです。
    <?xml version="1.0" encoding="UTF-8"?> <groups> <group ID="10503"Name="San Francisco" Path="/All Groups/Tenants/Acme/Groups/Sites/San Francisco"/> <group Path="/All Groups/Tenants/Acme/Groups/Sites/Austin"/> <group ID="10505"Name="Boston" Path="/All Groups/Tenants/Acme/Groups/Sites/Boston"/> </groups>
    「Austin」グループが存在しないため、このグループのグループ ID は返されません。
  3. グループ Web サービス
    このサービスは、指定したグループのすべての子グループを一覧表示します。 このコールでは、大規模なグループ階層を返すために数分かかります。 この方法は、より多くのデータを返すため最も低速です。
    「All Groups/Inventory」という ID を検索するための構文は、以下のとおりです。
    http://PC_host:8181/pc/center/webservice/groups/groupPath/All%20Groups%2FInventory
    グループ パスを指定する場合は、URL 文字列エンコーディングを使用します。 スペースは %20 で置き換える必要があり、グループは %2F によって区切る必要があります。
サイト グループ管理用構文
[すべてのグループ]の下のすべてのグループのリストを取得するには、groupPath パラメータまたは groupItemId パラメータを使用します。
groupPath パラメータを使ってデフォルト グループを識別し、次のコールを発行します。
http://
PC_host
:8181/pc/center/webservice/groups/groupPath/All%20Groups
いくつかの REST クライアントを使用する場合、「All%20Groups」ではなく、「All Groups」構文が必要です。 しかし、一般的に、ブランクのスペースは URL 内で有効ではありません。
サイト グループの識別子(siteId)を取得するには、次のコールを発行します。
http://
PC_host
:8181/pc/center/webservice/groups/groupItemId/siteId
以下の XML は、サイト ID に対する戻り値の例を示します。
<GroupTree siteId="118" inheritDefault="true" path="Austin, TX">
指定したグループの下のすべてのサブグループのリストを取得するには、次の 2 つのオプションがあります。
  • groupPath
    パラメータを使用する。
  • groupItemId
    パラメータを使用する。
groupPath
パラメータを使ってグループを特定し、次のコールを発行すると、返された XML にそのサブグループが一覧表示されます。
http://
PC_host
:8181/pc/center/webservice/groups/groupPath/All%20Groups%2FInventory
groupItemId
パラメータを使ってグループを特定し、次のコールを発行すると、返された XML にそのサブグループが一覧表示されます。
デフォルトの「Inventory」グループの
groupItemId
は 5 です。
http://
PC_host
:8181/pc/center/webservice/groups/groupItemId/5
返される XML には、そのグループに適用されるあらゆるグループ ルールの構文が含まれます。 ユーザ インターフェースで作成するさまざまなルールでテストし、生成された構文を調べてください。
サイト グループおよびルール
グループ ルールは正規表現に加えて、多重比較をサポートします。 たとえば、次の XML の構文を使用すると、名前が単語「Cisco」から始まるデバイスを追加するグループ ルールをポストします。
<Match> <Compare readOnly="true" using="MEMBER_OF"> <Property name="ItemID" type="device"/> <Value reference="/All Groups">1</Value> </Compare> <Compare readOnly="false" using="STARTS_WITH"> <Property name="AlternateName" type="device"/> <Value>Cisco*</Value> </Compare> </Match>
グループ パス構文については、スラッシュ文字は、ポストする XML ドキュメントに適切です。 この例では、「/All Groups/Texas/Austin」というグループ構造をすでに持っていると仮定します。
<GroupTree inheritDefault="true" path="/All Groups/Texas/Austin"> <Group desc="" inherit="true" location="" name="CA Officetype="custom group"> <Group desc="" inherit="true" location="" name="Austin Lab" type="custom group"/> </Group> <Group desc="" inherit="true" location="" name="Austin Data Center" type="custom group"/> </GroupTree>
Web サービス リクエスト用の URL で、円記号文字をグループ パスに使用します。 URL にはフォワード スラッシュを使用しないでください。
グループ Web サービスの構文例
グループ Web サービスのパラメータを確認するには、次のコールを発行します。
http://
PC_host
:8181/pc/center/webservice/groups/idNames
サポートされる操作のリストを参照するには、次のコールを発行します。
http://
PC_host
:8181/pc/center/rest/groups/documentation
グループ ツリーの最上位レベルのグループの下にあるすべてのグループのリスト(デフォルトでは[All Groups])を取得するには、groupPath パラメータまたは groupItemId パラメータが使用できます。
groupPath パラメータを使ってデフォルト グループを識別し、次のコールを発行します。
http://
PC_host
:8181/pc/center/webservice/groups/groupPath/All%20Groups
いくつかの REST クライアントを使用する場合、「All%20Groups」ではなく、「All Groups」構文が必要です。 しかし、一般的に、ブランクのスペースは URL 内で有効ではありません。
デフォルト グループ(その groupItemId 値は 1)を識別するために groupItemId パラメータを使って、次のコールを呼び出します。
http://
PC_host
:8181/pc/center/webservice/groups/groupItemId/1
サブグループ構文
指定したグループの下のすべてのサブグループのリストを取得するには、次の 2 つのオプションがあります。
  • groupPath
    パラメータを使用する。
  • groupItemId
    パラメータを使用する。
groupPath パラメータを使ってグループを特定し、次のコールを発行すると、返された XML にそのサブグループが一覧表示されます。
http://
PC_host
:8181/pc/center/webservice/groups/groupPath/All%20Groups%2FInventory
groupItemId パラメータを使ってグループを特定し、次のコールを発行すると、返された XML にそのサブグループが一覧表示されます。
デフォルトの「Inventory」グループの
groupItemId
は 5 です。
http://
PC_host
:8181/pc/center/webservice/groups/groupItemId/5
返される XML には、そのグループに適用されるあらゆるグループ ルールの構文が含まれます。 ユーザ インターフェースで作成するさまざまなルールでテストし、生成された構文を調べてください。
サイト グループ構文
サイト グループを作成するには、POST コマンドで、以下の XML 構文を使用します。
<GroupTree path="/All Groups">
<Group name="
group_name
" desc="
group_description
"
inherit="true" type="site" location="North America"
bHourID="99990" timeZone="EST"/>
</GroupTree>
  • inherit
    グループにグループ メンバの子アイテムを含めるかどうかを指定します。 たとえば、この属性を true に設定すると、デバイスがグループに追加される場合に、デバイス インターフェースがグループに追加されます。
  • type
    グループのタイプを指定します。 以下の値がサポートされています。
    値:
    • user group
      (デフォルト)
      ユーザが作成したグループ
    • site
      物理サイトを表す、ユーザが作成したグループ
  • bHourID
    (オプション)このサイト グループと関連付ける必要がある、内部的に割り当てられた営業時間定義の識別子。
  • timeZone
    (オプション)このサイト グループと関連付けるタイム ゾーン。 タイム ゾーンを関連付けることができるのはサイト グループのみで、ユーザ グループとは関連付けられません。
グループ ルール
グループ ルールは正規表現に加えて、多重比較をサポートします。 たとえば、「Cisco」で始まる名前のルータ グループ内のデバイスを追加するグループ ルールが必要とします。 ルータ グループのグループ ID は 31 です。 XML で、以下の構文を使用します。
<Match> <Compare readOnly="true" using="MEMBER_OF"> <Property name="ItemID" type="device"/> <Value reference="/All Groups/Inventory/All Items/Routers">31</Value> </Compare> <Compare readOnly="false" using="STARTS_WITH"> <Property name="AlternateName" type="device"/> <Value>Cisco*</Value> </Compare> </Match>
グループ ルールの範囲は、できるだけ狭くなるように設定します。 グループ ルールの範囲を[すべてのグループ]に設定しないでください。
AllowDeletes
グループの削除には、
allowDeletes
パラメータを「true」に設定する必要があります。 グループに対して
allowDeletes
パラメータが「true」に設定されている場合、XML 本文から除外されていない限り、
GroupTree path
のグループは保持されます。 XML 本文から除外された
GroupTree path
のグループは削除されます。 グループに対して
allowDeletes
パラメータが「false」に設定されている場合、XML 本文に含まれているかどうかにかかわらず、
GroupTree path
のグループは保持されます。
サブグループを削除する場合、コンテナ グループにこのパラメータを適用して「true」に設定します。 たとえば、以下の XML では Austin の下に記載されていないグループは削除されます。
<GroupTree inheritDefault="true" path="/All Groups/Texas/Austin" allowDeletes=”true”>
<Group desc="" inherit="true" location="" name="CA Office" type="user group">
<Group desc="" inherit="true" location="" name="Austin Lab" type="user group"/>
</Group>
<Group desc="" inherit="true" location="" name="Austin Data Center" type="user group"/>
</GroupTree>
以下の XML では、Texas の下に記載されていないグループは削除されます。 たとえば、この XML では、前記の例から Austin サブグループが削除されます。
<GroupTree path="/All Groups/Texas">
<Group name="USA" desc="Group to represent the entire
United States" allowDeletes="true" type="user group"/>
</GroupTree>
グループ パス構文については、スラッシュ文字は、ポストする XML ドキュメントに適切です。
Web サービス リクエスト用の URL で、円記号文字をグループ パスに使用します。 URL にはフォワード スラッシュを使用しないでください。