ISE APIのinternaluser/name/{name}がUnsupported method exceptionとなる件について

[n.masahiro]

ISE　ver2.6環境にて、

ユーザ名をキーにユーザIDを取得したく、

https://developer.cisco.com/docs/identity-services-engine/v1/#!internaluser

に記載のある

GET　ers/config/internaluser/name/{name}

を実行したところ、405エラーで

Body:
{
"ERSResponse" : {
"operation" : "GET-get by name-internaluser",
"messages" : [ {
"title" : "The requested Method is not supported for that resource!",
"type" : "ERROR",
"code" : "Unsupported method exception"
} ],
"link" : {
"rel" : "related",
"href" : "https://192.168.28.97:9060/ers/config/internaluser/name/{

入力したユーザー名}",
"type" : "application/xml"
}
}
}

となり、情報を取得できませんでした。（同リファレンス内の他のメソッドは実行できました）

リファレンス上ではAPIを用いる上でのISEのバージョンに関する記載は読み取れなかったのですが、

ISE側で予め行っておくべき操作やこのメソッドの実行のために必須となる項目など、

詳細をご存知の方、なにか助言をいただけますでしょうか・・・？

[Tohru Ohzono · Accepted solution]

こんにちは。

手元にすぐ使える環境がなく、すぐは試せないのですが、
以下、確認してみていただければと思います。
(状況によっては、Sandboxを予約して確認とかは検討してみます。)

「ユーザ名」をキーに「ユーザID」を取得ということですが、
ユーザ名は、「ユーザの一意なリソース名」、
ユーザIDは、ユーザの一意なUUIDを意図していますか？

「ユーザ名」は、
ユーザのfirstName, lastNameなどのユーザの姓名ではなく、
各ユーザに一意に設定する、
ユーザのリソース名を意図しているかの確認となります。

また、「ユーザID」は、
"b24b09e2-16f8-4e48-ace1-2c262a9449f1"のような、
内部的なUUIDの取得を意図しているかの確認となります。

以下が、GET Internal Userのレスポンス例ですが、
ユーザ名、ユーザIDは、それぞれ、"name", "id"を意図していますかね？

{
  "InternalUser": {
    "id": "b24b09e2-16f8-4e48-ace1-2c262a9449f1",
    "name": "user_resource_name",
    "description": "description",
    "email": "email@example.com",
    "firstName": "名前",
    "lastName": "苗字",
...以下省略...

「同リファレンス内の他のメソッドは実行できました」というのは、
PUT /ers/config/internaluser/name/{name}
DELETE /ers/config/internaluser/name/{name}
は動作したということでしょうか？
{name}をキーにしたものではない、
"/ers/config/internaluser/{id}"や"/ers/config/internaluser"
リソースに対するAPIは動作したということでしょうか？

405エラーというのは、何かおかしい気はしていますが、
一旦、以下の内容も確認いただければと思います。

最新のAPIリファレンスには、今回問題が発生している{name}リソースに関するAPIは掲載されていないようなので、
以下のGet-All Internal Userにフィルタ付けた場合で取得できないかも確認いただければと思います。

GET /ers/config/internaluser?filter=name.EQ.{URLエンコードしたユーザのリソース名}

ユーザのリソース名が、"test"の場合は、
GET /ers/config/internaluser?filter=name.EQ.test
となります。

ユーザの姓名の名前で検索したい場合は、
GET /ers/config/internaluser?filter=firstName.EQ.{URLエンコードしたユーザの名前}
となります。
こちらの場合は同じ名前の人が複数いる場合は、検索結果は複数返ってきます。

以下のISE ERS API 2.0から3.0のガイドも参照ください。
https://developer.cisco.com/docs/identity-services-engine/3.0/#!setting-up
API Referenceはツリー内の[Cisco ISE API Documentation]になります。
各APIの表に[ISE Version]という項目があり、どのバージョンのISEから使えるAPIかの情報になります。

[n.masahiro]

回答ありがとうございます。

中々着手できず、返信遅れてすみませんでした。

教えて頂いた、

GET /ers/config/internaluser?filter=name.EQ.{URLエンコードしたユーザのリソース名}

でフィルターを掛けるやり方で期待していた動作をさせる事ができました。ありがとうございます。

＞以下が、GET Internal Userのレスポンス例ですが、
ユーザ名、ユーザIDは、それぞれ、"name", "id"を意図していますかね？

はい。この部分に関しては正しいフィールドの値を指定できていました。

＞「同リファレンス内の他のメソッドは実行できました」というのは、
PUT /ers/config/internaluser/name/{name}
DELETE /ers/config/internaluser/name/{name}
は動作したということでしょうか？
{name}をキーにしたものではない、
"/ers/config/internaluser/{id}"や"/ers/config/internaluser"
リソースに対するAPIは動作したということでしょうか？

後者です。前者は同様のエラーが発生しておりました。

＞以下のISE ERS API 2.0から3.0のガイドも参照ください。
https://developer.cisco.com/docs/identity-services-engine/3.0/#!setting-up
API Referenceはツリー内の[Cisco ISE API Documentation]になります。
各APIの表に[ISE Version]という項目があり、どのバージョンのISEから使えるAPIかの情報になります。

左上のプルダウンの内容が、

「1.0」

「Cisco ISE Release : 3.0」

「Cisco ISE Release : 2.7」

「Cisco ISE Release : 2.6」

とあり、確かに3.0以下のリファレンスには{name}をキーとしたメソッドの記述は無かったです。

ただ、一番上の1.0に{name}の記載がある事だけが気になっているのですが、この資料はどのISEのバージョンを対象にしたものなのでしょうか？リファレンスにリリース日時等があれば時系列の推測もできるのですが…。

[Tohru Ohzono]

こんにちは。
ISEのAPI自体には現時点では、バージョニングの概念はないので、
ISE側のバージョンに依存します(※後述のリソースバージョンの概念があります)。

ISE 2.x以降はある程度の互換性は考慮されていると思いますが、
適切なバージョンのガイドを参照するのがいいと思います。

左上のプルダウンでいうと、ISE 2.6をご利用であれば、
APIリファレンス上も、「Cisco ISE Release : 2.6」を参照するのがいいと思います。
「Cisco ISE Release : 3.0」を参照した場合も、2.6の内容も含んではいるので、
利用することはできます(2.6以降の内容も入っているので、その辺は意識する必要はあります)。

Cisco ISE Release 2.xや3.0の「Cisco ISE API Documentation」のツリーに移動すると、
[Release Notes]があるのでプルダウンにない2.0から2.5までの変更内容はここで確認できます。

また、リソースバージョンという概念があって、
個別のAPIのページの表の中などに書かれているのですが、
リソースバージョンが異なると、リクエストやレスポンス内のJSONやXMLのフィールドが
増減しています(バージョンが上がると増えていく)。

ISEのバージョンが上がっても、個別のAPIでは、必ずしもリソースバージョンが変わるわけではありません。
(JSONやXMLのフィールド的には前バージョンと同じAPIもある)。

ISE 2.6をご利用なのであれば、「Cisco ISE Release : 2.6」から見ながら開発する方針が、
課題は少なくなると思います。

[Tohru Ohzono]

こんにちは。

前回回答した内容のリソースバージョンに関する補足となります。

リソースバージョンは、そのISEのバージョンで利用可能なリソースバージョンであれば、
リクエストヘッダで指定は可能です。
以下の[Resource Version and Media Type]参照。
https://developer.cisco.com/docs/identity-services-engine/2.6/#!request-headers/resource-version-and-media-type

指定しない場合は、そのISEで利用可能な最新バージョンのリソースバージョンになります。

指定した方が互換性の助けにはなる可能性はありますが、
基本的には最新のリソースバージョンで動作する方がいいので、
指定する場合も一時的な互換性維持のために本リクエストヘッダーを利用するのがいいと思います。
(指定しない場合も、バージョンアップでのある程度の互換性は考慮されていると思います。)

ベストプラクティスが公開されているわけではないのですが、
個人的には指定する強い理由がないのであれば、リソースバージョンは指定しない方針を基本とするのがいいと思っています。