API の操作
API を使用するには、POST 操作または GET 操作のいずれかで Cisco NAC ゲスト サーバ API に詳細を渡します。
次の例では、GET 操作で API と Cisco NAC ゲスト サーバのバージョンを取得します。
https://1.1.1.1/sponsor/api/GuestAccount.php?username=sponsor&password=mypass&method=getVersion
データはすべて XML の形式で返されます。
XML 応答
応答はすべて次のような XML 形式になります。
<message>Success</message>
エラーが発生した場合は、code 要素と message 要素にエラー コードとエラー テキストが設定されます。内部エラーの場合は、問題の解決に役立つ開発者向けの情報を含む <details> 要素も返されます。
create
create メソッドでは、スポンサーの権限に応じてゲスト ユーザ アカウントを作成します。
必須入力パラメータ
•
method(必須):create
•
username(必須):スポンサー アカウントのユーザ名
•
password(必須):スポンサー アカウントのパスワード
•
firstName(ポリシーによる):ゲスト ユーザの名
•
surname(ポリシーによる):ゲスト ユーザの姓
•
email(ポリシーによる):ゲスト ユーザの電子メール アドレス
•
role(必須):ゲスト ユーザを作成するロール
•
company(ポリシーによる):ゲスト ユーザの会社名
•
phonecode(ポリシーによる):ゲスト ユーザの携帯電話の電話コード(+44 など)
•
mobilenumber(ポリシーによる):ゲスト ユーザの携帯電話の番号
•
timezone(必須):ゲスト アカウントを作成するタイムゾーン(詳細については、「有効なタイムゾーン」を参照してください)
•
option1(ポリシーによる):任意指定のデータ フィールド 1
•
option2(ポリシーによる):任意指定のデータ フィールド 2
•
option3(ポリシーによる):任意指定のデータ フィールド 3
•
option4(ポリシーによる):任意指定のデータ フィールド 4
•
option5(ポリシーによる):任意指定のデータ フィールド 5
•
startTime(必須):アカウントの開始時刻
•
endTime(必須):アカウントの終了時刻
•
timeProfile(必須):アカウントの作成時に使用する時間プロファイル
create の使用例
ステップ 1
以下の詳細を指定してゲスト アカウントを作成する例を次に示します。
名:John
姓:Carter
電子メール:johncart@cisco.com
ロール:DEFAULT(ユーザ ロール インターフェイスで作成)
会社:Cisco
携帯電話の番号:12345 48434532
電話コード:123
開始時刻:2008 年 11 月 29 日(0 時)
終了時刻:2008 年 11 月 30 日(0 時)
タイムゾーン:Europe/London
時間プロファイル:StartEnd(時間プロファイル ユーザ インターフェイスで作成)
ステップ 2
API の呼び出しは次のようになります。
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=create&fi
rstName=John&surname=Carter&email=johncart%40cisco.com&role=DEFAULT&company=Cisco&mobileNu
mber=12345+48434532&phoneCode=123&startTime=2008-11-29&endTime=2008-11-30&timezone=Europe%
2FLondon&timeProfile=StartEnd
ステップ 3
成功すると、次のような応答が返されます。
<message>Success</message>
<firstName>John</firstName>
<surname>Carter</surname>
<email>johncart@cisco.com</email>
<mobileNumber>12345 48434532</mobileNumber>
<phoneCode>123</phoneCode>
<username>JohnCarter10</username>
<password>!B,4N!32(F1{VJ2</password>
<timezone>Europe/London</timezone>
<startTimeT>2008-11-29T00:00:00+00:00</startTimeT>
<endTimeT>2008-11-30T00:00:00+00:00</endTimeT>
<modifiedUsername>1</modifiedUsername>
<accountType>1</accountType>
<durationUnit>Days</durationUnit>
<durationInUnits>0</durationInUnits>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
<startTime>17:00</startTime>
<startTime>17:00</startTime>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
edit
edit メソッドでは、スポンサーの権限に応じて既存のユーザ アカウントを編集します。
既存のアカウントに関連付けられたフィールドを編集できますが、以下は例外です。
•
開始時刻
•
ロール
•
時間プロファイル
•
タイムゾーン
アカウントを編集するには、「create」 メソッドで返されるアカウント ID を指定する必要があります。
必須入力パラメータ
•
method(必須):edit
•
id(必須):編集するアカウントのデータベース ID
•
username(必須):スポンサー アカウントのユーザ名
•
password(必須):スポンサー アカウントのパスワード
•
firstName(任意):ゲスト ユーザの名
•
surname(任意):ゲスト ユーザの姓
•
email(任意):ゲスト ユーザの電子メール アドレス
•
group(任意):ゲスト ユーザを作成するロール
•
company(任意):ゲスト ユーザの会社名
•
phonecode(任意):ゲスト ユーザの携帯電話の電話コード(+44 など)
•
cellnumber(任意):ゲスト ユーザの携帯電話の番号
•
timezone(任意):ゲスト アカウントを作成するタイムゾーン(詳細については、「有効なタイムゾーン」を参照してください)
•
option1(任意):任意指定のデータ フィールド 1
•
option2(任意):任意指定のデータ フィールド 2
•
option3(任意):任意指定のデータ フィールド 3
•
option4(任意):任意指定のデータ フィールド 4
•
option5(任意):任意指定のデータ フィールド 5
•
startTime(任意):アカウントの開始時刻
•
endTime(任意):アカウントの終了時刻
•
timeProfile(任意):アカウントの作成時に使用する時間プロファイル
edit の使用例
ID が 794 であるアカウントの携帯電話の番号を変更する例を次に示します。
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=edit&id=794&mobileNumber=12345678
「getDetails」 メソッドを使用した場合と同様に、アカウントのすべての詳細が返されます。
<message>Success</message>
<firstName>John</firstName>
<surname>Carter</surname>
<email>johncart@cisco.com</email>
<mobileNumber>12345678</mobileNumber>
<phoneCode>123</phoneCode>
<username>jcarter</username>
<password>cisco</password>
<timezone>Europe/London</timezone>
<startTimeT>2008-10-28T00:00:00+00:00</startTimeT>
<endTimeT>2008-10-29T00:00:00+00:00</endTimeT>
<startTime>2008-08-07T04:06:32+01:00</startTime>
<endTime>2008-08-07T04:06:33+01:00</endTime>
<ipAddress>4.5.6.7</ipAddress>
<startTime>2008-10-02T22:00:00+01:00</startTime>
<endTime>2008-10-03T00:30:00+01:00</endTime>
<ipAddress>4.5.6.7</ipAddress>
<accountType>1</accountType>
<durationUnit>Days</durationUnit>
<durationInUnits>0</durationInUnits>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
<startTime>17:00</startTime>
<startTime>17:00</startTime>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
getDetails
getDetails API では、スポンサーの権限に応じてユーザのアカウントの詳細を取得します。
必須入力パラメータ
•
method(必須):getDetails
•
username(必須):スポンサー アカウントのユーザ名
•
password(必須):スポンサー アカウントのパスワード
•
id(1 つは必須):取得するアカウントの ID
getDetails の使用例
ステップ 1
既存のアカウントの詳細を取得するには、getDetails API 呼び出しを使用し、「create」 メソッドで返されるアカウントの ID を渡します。
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=getDetails&id=815
ステップ 2
成功すると、次のような応答が返されます。
<message>Success</message>
<firstName>John</firstName>
<surname>Carter</surname>
<email>johncart@cisco.com</email>
<mobileNumber>12345 48434532</mobileNumber>
<phoneCode>123</phoneCode>
<username>jcarter</username>
<password>*****</password>
<timezone>Europe/London</timezone>
<startTimeT>2008-10-29T00:00:00+00:00</startTimeT>
<endTimeT>2008-10-30T00:00:00+00:00</endTimeT>
<startTime>2008-08-07T04:06:32+01:00</startTime>
<endTime>2008-08-07T04:06:33+01:00</endTime>
<ipAddress>4.5.6.7</ipAddress>
<startTime>2008-10-02T22:00:00+01:00</startTime>
<endTime>2008-10-03T00:30:00+01:00</endTime>
<ipAddress>4.5.6.7</ipAddress>
<accountType>1</accountType>
<durationUnit>Days</durationUnit>
<durationInUnits>0</durationInUnits>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
<startTime>17:00</startTime>
<startTime>17:00</startTime>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
suspend
suspend メソッドでは、スポンサーの権限に応じてユーザ アカウントを一時停止します。
必須入力パラメータ
•
method(必須):suspend
•
username(必須):スポンサー アカウントのユーザ名
•
password(必須):スポンサー アカウントのパスワード
•
id(必須):一時停止するアカウントのデータベース ID
suspend の使用例
suspend メソッドを実行すると、アカウントが一時停止され、「getDetails」 を実行した場合と同じ XML 応答が返されます。
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=suspend&&&&id=815
notifyEmail
notifyEmail メソッドでは、ゲストの電子メール アカウントに電子メール メッセージを送信します。「getDetails」 を実行した場合と同じ XML が返されます。
必須入力パラメータ
•
method(必須):notifyEmail
•
username(必須):スポンサー アカウントのユーザ名
•
password(必須):スポンサー アカウントのパスワード
•
id(必須):電子メールを送信するアカウントのデータベース ID
•
from(必須):電子メールの送信元の電子メール アドレス
•
to(必須):電子メールの送信先の電子メール アドレス
notifyEmail の使用例
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=notifyEmail.&&&&id=815.
notifySms
notifySms メソッドでは、ゲストの携帯電話に SMS メッセージを送信します。「getDetails」 を実行した場合と同じ XML が返されます。
必須入力パラメータ
•
method(必須):notifySms
•
username(必須):スポンサー アカウントのユーザ名
•
password(必須):スポンサー アカウントのパスワード
•
id(必須):電子メールを送信するアカウントのデータベース ID
notifySms の使用例
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=notifySms&&&&id=815.
getVersion
getVersion メソッドでは、現在の API のバージョンを表示します。
必須入力パラメータ
•
method(必須):getVersion
•
username(必須):スポンサー アカウントのユーザ名
•
password(必須):スポンサー アカウントのパスワード
getVersion の使用例
呼び出しの結果、次のような形式の応答が返されます。
<message>Success</message>
<appName>Cisco NAC Guest Server</appName>
<majorVersion>2</majorVersion>
<minorVersion>0</minorVersion>
<maintenanceVersion>2</maintenanceVersion>
search
search API は、「ゲスト アカウントの管理」 のスポンサー インターフェイスのとおり、スポンサーの権限および設定に従ってレポートのためにゲスト アカウントの詳細を返します。
(注) search API を使用できるのは、バージョン 2.0.1 以降のみです。
必須入力パラメータ
•
username(必須):スポンサー アカウントのユーザ名
•
password(必須):スポンサー アカウントのパスワード
•
method(必須):search
•
sponsor(任意):スポンサーのユーザ名
•
firstName(任意):ゲスト ユーザの名
•
surname(任意):ゲスト ユーザの姓
•
company(任意):ゲスト ユーザの会社名
•
email(任意):ゲスト ユーザの電子メール アドレス
•
ipAddress(任意)
•
startTime(任意):YYYY-MM-DD
•
endTime(任意):YYYY-MM-DD
•
timezone(任意):アカウントが作成されるタイムゾーン
•
option1(任意):
•
option2(任意):
•
option3(任意):
•
option4(任意):
•
option5(任意):
•
statusInactive(任意):
•
statusActive(任意):
•
stautsExpired(任意):
•
statusSuspended(任意):
search の使用例
必須パラメータは必須です。オプション パラメータは、返されるデータのサブセットになります。開始日と終了日を指定しない場合は、直近 24 時間の範囲でアカウントが返されます。
次に、2009 年 3 月 3 日から 2009 年 4 月 15 日の間のアクティブ ゲスト アカウントの詳細を返す例を示します。
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=search&startTime=2009-03-03&endTime=2009-04-15&statusActive=1
成功すると、次のような応答が返されます。
<message>Success</message>
<firstName>Jim</firstName>
<company>Beans Brewery</company>
<email>jim@bean.com</email>
<username> jim@bean.com </username>
<password>Es3TDdd3</password>
<mobileNumber>782394928</mobileNumber>
<timezone>America/Los_Angeles</timezone>
<startTimeT>2009-04-01T04:40:00-07:00</startTimeT>
<endTimeT>2009-04-06T06:59:00-07:00</endTimeT>
<sponsorId>196</sponsorId>
<timeProfileId>1</timeProfileId>
<timeProfile>default</timeProfile>
...further account details meeting the request criteria...
...further account details meeting the request criteria...
...further account details meeting the request criteria...
StartTime、EndTime、Timezone を使用した search の例
「timezone」パラメータは、アカウントが作成されたタイムゾーンを表します。
次に、「Europe/Moscow」のタイムゾーンで作成されたアクティブ ゲスト アカウントの詳細を返す例を示します。ここで、開始時刻と終了時刻は、指定された開始時刻(2012-07-01 21:22:00)および終了時刻(2012-07-02 23:59:00)と重複しています。
search クエリーで、「timezone」は、指定された開始時刻および終了時刻のレコードを取得する「search」API の必須パラメータです。
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=search&startTime=2012-07-01T21:22:00+01:00&endTime=2012-07-02T23:59:00+01:00&timezone=Europe%2FMoscow
成功すると、次のような応答が返されます。
<message>Success</message>
<firstName>Jim</firstName>
<company>Beans Brewery</company>
<email>jim@bean.com</email>
<username>jim@bean.com</username>
<password>Es3TDdd3</password>
<mobileNumber>782394928</mobileNumber>
<timezone>Europe/Moscow</timezone>
<startTimeT>2012-07-01T13:44:00+04:00</startTimeT>
<endTimeT>2012-07-01T15:50:00+04:00</endTimeT>
<sponsorId>196</sponsorId>
<timeProfileId>1</timeProfileId>
<timeProfile>default</timeProfile>
timezone パラメータなしで検索 API を実行すると、スポンサーのタイム ゾーンが開始時刻と終了時刻に適用されます。次のクエリーは、「local」というユーザのタイムゾーンのレコードを返します。
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=search&startTime=2012-07-01T10:52:00&endTime=2012-07-03T01:30:00
開始時刻と終了時刻のパラメータは、ユーザによって作成されたタイムゾーンで表示されます。
エラー コード
応答の <code> 要素に以下のエラー コードが返されます。
値:説明
•
値 0:エラーはありません。
•
値 1:内部アプリケーション エラーです。
•
値 100:スポンサーのユーザ名やパスワードが正しくありません。
•
値 101:HTTPS で API にアクセスできません(管理者が制御)。
•
値 102:HTTP で API にアクセスできません(管理者が制御)。
•
値 1000:必須のフィールドで指定されていないものがあります(メッセージ内にリスト表示されます)。
•
値 1001:管理者によってディセーブルにされた SMS メッセージを送信します。
•
値 1002:管理者によってディセーブルにされた電子メールを送信します。
•
値 1003:渡されたアカウント ID が存在しません。
•
値 1004:正しく指定されていないフィールドがあります(メッセージ内にリスト表示されます)。
•
値 1005:edit メソッドで変更できないフィールドがあります。