マクロを使用すると、必要なときにいつでも HTTPs サーバにデータを送信できます。 送信されるデータとその整理方法を制御できるため、既存のサービスで使用できるようにデータを簡単に調整できます。

セキュリティ対策：

  • HTTP(S) クライアント要求機能は、デフォルトでは無効に設定されています。 システム管理者は、 HttpClient > Mode を On ( xConfiguration HttpClient Mode: On ) に設定して、この機能を明示的に有効にする必要があります。

  • システム管理者は、 HttpClient > AllowHTTP を False ( xConfiguration HttpClient AllowHTTP: False ) に設定することで、HTTP の使用を防ぐことができます。

  • システム管理者は、デバイスがデータの送信を許可されているHTTP(S) サーバのリストを指定することができます。 （xCommand HttpClient Allow Hostname コマンドを参照してください。）

  • 同時 HTTP(S) 要求の数は制限されています。

この記事で参照されている構成は、デバイスの Web インターフェイスと API の両方で利用できます。 コマンドは API を通じて利用できます。 WebインターフェイスにアクセスしてAPIを使用する方法については、詳細設定の項目を参照してください。

許可されているHTTP（S）サーバーのリスト

システム管理者は、次のコマンドを使用して、許可された最大 10 の HTTPS サーバ（ホスト）のリストを設定および維持できます。

  • xCommand HttpClientホスト名追加式の許可：<HTTP（S）サーバーのホスト名またはIPアドレスに一致する正規表現>

  • xCommand HttpClient でホスト名をクリアする

  • xCommand HttpClient許可ホスト名リスト

  • xCommand HttpClientホスト名の削除を許可するID：<リスト内のエントリのID>

リストにサーバ エントリが含まれている場合は、それらのサーバにのみ HTTPs 要求を送信できます。 ただし、リストが空の場合は、任意の HTTPs サーバにリクエストを送信できます。

許可されたサーバーのリストに対するチェックは、データの安全でない（HTTP）転送と安全な（HTTPS）転送の両方を使用するときに実行されます。

証明書検証なしの HTTPS

HTTPS 経由で要求を送信する場合、デバイスはデフォルトで HTTPS サーバの証明書をチェックします。 HTTPS サーバ証明書が有効でない場合は、エラーメッセージが表示されます。 デバイスはそのサーバーにデータを送信しません。

証明書検証でHTTPSを使用することをお勧めします。 証明書の検証が不可能な場合、システム管理者は HttpClient > AllowInsecureHTTPS を On ( xConfiguration HttpClient AllowInsecureHTTPS: On ) に設定できます。 これにより、サーバの証明書を検証せずに HTTPS を使用することができます。

HTTPS リクエストの送信

HTTP(S) クライアント要求機能が有効になると、以下のコマンドを使用して、要求を HTTP(S) サーバに送信することができます。 <method> は、Post、Put、Patch、Get、あるいは Delete のいずれかになります。

  • xCommand HttpClient <Method> [AllowInsecureHTTPS: <True/False>] [Header: <ヘッダー テキスト>] [ResponseSizeLimit: <最大応答サイズ>] [ResultBody: <None/PlainText/Base64>] [Timeout: <タイムアウト期間>] Url: <リクエストの送信先の URL>

ヘッダー フィールドの追加はオプションであり、最大 20 個のフィールドを追加できます。

AllowInsecureHTTPSパラメーターは、システム管理者がサーバーの証明書を検証せずにHTTPSの使用を許可した場合にのみ効果があります。 その場合、パラメータが[真(True)]に設定されていれば、サーバ証明書を検証せずにサーバにデータを送信できます。 パラメータを省略するか、または[偽(False)]に設定すると、証明書の検証に失敗した場合にデータは送信されません。

ResposenSizeLimit パラメータは、デバイスがサーバからの応答として許容する最大ペイロード サイズ（バイト）です。 応答ペイロードがこの最大サイズを超過する場合、コマンドはステータス エラーを返します。 エラー メッセージには、最大ファイル サイズを超過していることが示されます。 ただし、このエラーはサーバ側への影響はなく、サーバは、要求を適切に受信し、処理します。

コマンド結果でサーバからの HTTP 応答の本文をフォーマットする方法を指定するには、ResultBody パラメータを使用します。 次の 3 つのオプションがあります。

  • なし：HTTP レスポンスの本文は、コマンドの結果に含めない。

  • Base64：本文を結果に含める前に Base64 がエンコードを行う。

  • プレーンテキスト：本文をプレーンテキスト形式で結果に含める。 応答に印字不可能な文字が含まれている場合、コマンドはステータス エラーを返し、印刷できないデータが検出された、というメッセージを返します。

タイムアウト期間（秒）を設定するには、タイムアウト パラメータを使用します。 指定した期間内で要求が完了しないと、API がエラーを返します。

コマンドを発行した直後にペイロード（データ）を入力してください。 改行を含め、入力したものはペイロードの一部です。 終了したら、改行(“\n”)とピリオドとそれに続く改行(“.\n”)だけで構成される別の行で終了します。 これでコマンドが実行され、データがサーバに送信されます。

例

どちらの例でも、メッセージの本文はJSONです。 メッセージを受信しているサービスの予想される形式に応じて、任意の形式にすることができます。

例 1：HTTP Post を使用した IoT デバイスコントロール

これは、Philips Hue Bridgeに接続されているライトをオンにするマクロ機能です：

 function hue_command(data) { var url = 'http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state'; var headers = 'Content-Type: application/json'; var command = '{"on":true}'; xapi.command('HttpClient PUT', { 'Url': url, 'Header': headers }, command); }

API を使用してコマンドラインでも同じことができます：

 xcommand HttpClient PUT ヘッダー: "Content-Type: application/json" URL: "http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state" {"on":true}。

例 2：HTTP Post を使用して監視ツールにデータを投稿する 

 xcommand HttpClient POST ヘッダー: "Content-Type: application/json" URL: "https://mymonitoringserver.com/service/devicemonitoring" {"Message":"ユーザからこのシステムに関する問題が報告されました","systemName":"BoardRoom 4 階","softwareVersion":"ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Dual"} .

詳細情報

HTTP クライアント要求の使用方法の詳細は、カスタマイズ ガイドを参照してください。 最新バージョンを選択します。

Ciscoサポート（TAC）は、マクロを含むサードパーティコードのデバッグに対応していません。 マクロやサードパーティのコードに関するサポートが必要な場合は、 https://roomos.cisco.com を確認してください。