CMS - API 関連のトラブルシューティング

[Yusuke Yoshinaga]

• はじめに
• 基本的な確認事項
• ユーザアカウント
• API リクエストの宛先
• よくある問題
• GET リクエストへの応答にすべての値が含まれない
• POST/PUT リクエストのパラメータに設定した値が反映されない
• リクエストへの応答がエラーとなる
• ログ取得手順

はじめに

Cisco Meeting Server(CMS) では各種設定や操作等をAPI で実行することが可能です。

本ドキュメントではAPI を用いて問題が発生した際のトラブルシューティングについて記載します。

基本的な確認事項

ユーザアカウント

送信したAPI リクエストに、エラー「401 Unauthorized」が応答される場合には正しいユーザ名・パスワードを使用しているか確認してください。

API は「api」権限を持つユーザが実行可能です。ユーザアカウントはMMP コマンド「user add <ユーザ名> api」で作成します。詳細は、MMP コマンドリファレンスの「MMP User Account Commands」に記載しています。

参考: CMS - MMPユーザパスワード

API リクエストの宛先

送信したAPI リクエストに、エラー「405 Method Not Allowed」が応答される場合にはリクエストを正しい宛先に送信しているかを確認してください。
API リクエストは「https://<CMS のWeb Admin アドレス>/api/v1」宛に送信します。
Web Admin で使用するポート番号はMMP コマンド「webadmin」で確認可能です。
下記例の場合、Web Admin はポート番号445 を使用しているので、API リクエストは「https://<CMS のWeb Admin アドレス>:445/api/v1」宛に送信します。

> ssh <admin 権限ユーザ名>@<CMSのIPアドレス>   <--- PC からCMS のMMP にSSH でログイン
Please enter password:            <--- CMS のadmin 権限ユーザパスワードを入力
Failed logins since last successful login 0
Last login 2018-Jun-27 11:45:14 using web remote host 192.168.1.1
cms> webadmin
Enabled : true
TLS listening interface : a
TLS listening port : 445
Key file : example.key
Certificate file : example.crt
HTTP redirect : Disabled
STATUS : webadmin running

よくある問題

GET リクエストへの応答にすべての値が含まれない

CMS のAPI は一度の応答に含める要素を最大20 としています。この値は設定で拡張すること等はできません。

例えば20 以上のスペースが作成されているCMS に対してGET /cospaces リクエストを発行すると、応答に含まれるスペース情報の数は20 となります。

20ヶ 以降の情報を取得するためには、API リクエストの宛先URL に「offset=<オフセット値>」を付加してください。

下記例は25 番目以降のスペース情報を最大20 取得するGET リクエストの宛先を示します。

https://<CMS Web Admin アドレス>/api/v1/cospaces?offset=25

POST/PUT リクエストのパラメータに設定した値が反映されない

POST/PUT リクエストで設定等を新規作成・編集する際、パラメータをリクエストボディに指定します。

その際、リクエストボディの形式は「x-www-form-urlencoded」とする必要があります。

API リクエストヘッダに「Content-Type: application/x-www-form-urlencoded」が設定されているかも確認してください。

リクエストへの応答がエラーとなる

送信したリクエストの内容が正しくない場合、CMS は400 Bad Reqeust レスポンスを返送します。

エラー原因を示すメッセージがレスポンスボディの「failureDetails」に含まれますので、その内容を確認してください。

API ガイドの「Failure Reasons」にエラーメッセージ一覧を記載しています。

ログ取得手順

API tracing を有効とすることで、CMS が実際に送受信するAPI リクエスト・レスポンスの内容をログに記録し、詳細に調査を行うことが可能です。

1. CMS のWeb Admin にadmin 権限ユーザでログイン

2. Logs > Detailed tracing のAPI tracing をEnable とする
＊問題事象が発生するまでの十分な時間を選択してください。

＊API tracing が有効になったことはAPI logging status の表示で確認できます。下図は「Enable for 24 hours」とした場合の例です。

3. 調査対象の事象が発生する操作を最初から実施する

4. 調査対象の事象が発生したことを確認する

5. API tracing をDisable とする

＊Enable 時と同じく、API logging status でDisable となったことを確認できます。

6. CMS ログを取得
＊ログファイル内からメッセージが上書きされることを防ぐため、試験実施後、できるだけ早く取得してください。

• CMS Log Collector によるログの取得
• CMS - logbundleの取得(2.2以降)

[注意]

• ログファイルから調査対象箇所を特定するために、CMS の時刻情報が正しいことを確認し、試験を実施した日付と時刻を手順毎に記録してください。

• API tracing を有効にすると、全API メッセージがログに出力されるため、処理負荷が増加します。また、CMS のログファイルの最大サイズ100 MB(変更不可) で、最古の記録から上書きされますので、tracing を有効にし続けると、過去の記録が上書きされやすくなります。これらのことから、API tracing は実運用中に実施することは避け、問題事象の再現条件・手順を確保した上で、業務時間外等にトラブルシューティング目的として実施してください。