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

セキュリティ対策:

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

  • システム管理者は、 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 オン ( xConfiguration HttpClient AllowInsecureHTTPS: オン )に設定できます。 これにより、サーバの証明書を検証せずに HTTPS を使用することができます。

HTTPS リクエストの送信

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

  • xCommand HttpClient <メソッド> [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 コマンド = '{"on":true}'; xapi.command('HttpClient Put', { 'Url': URL, 'Header': ヘッダー }, command); } 

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

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

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

 xcommand HttpClient 投稿ヘッダー: "Content-Type: application/json" URL: "https://mymonitoringserver.com/service/devicemonitoring" {"Message":"ユーザからこのシステムの問題が報告されました","systemName":"BoardRoom 4th Floor","softwareVersion": "ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"デュアル"}。 

詳細情報

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

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