マクロを使えば、必要なときにいつでも HTTPs サーバにデータを送信することができます。 送信されるデータとその整理方法をコントロールできるため、既存のサービスで使用するためにデータを簡単に調整できます。

セキュリティ対策：

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

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

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

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

この記事で参照されている構成は、端末のウェブ インターフェイスと 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 を オン ( x設定 HttpClient AllowInsecureHTTPS: オン )に設定します。 これにより、サーバの証明書を検証せずに HTTPS を使用することができます。

HTTPs リクエストを送信する

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

  • xCommand HttpClient <方法> [AllowIn セキュア HTTPS: <True/False>] [ヘッダー: <ヘッダーテキスト>] [ResponseSizeLimit: <最大レスポンスサイズ>] [ResultBdy: <None/P PlainText/Base64>] [タイムアウト: <タイムアウト期間>] 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に接続されているライトをオンにするマクロ機能です：

 関数ヒューコマンド (データ) { var url = 'http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state'; varheaders = 'Content-Type: application/JSON'; var command = '{"on":true}'; xapi.command('HttpClient Push', { '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" {"メッセージ":"ユーザがこのシステムに関する問題を報告しました","systemName":"BoardRoom 4th floor","softwareVersion": "ce9.6.0","softwareReleaseDate":"2018-12-13","videomonitors":"Dual"} .

詳細情報

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

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