マクロを使用すると、必要なときにいつでも HTTPS サーバにデータを送信できます。送信するデータを選択し、好きなように構造化することができます。このようにすることで、すでに確立されているサービスにデータを適合させることができます。

セキュリティ対策:

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

  • システム管理者が、HttpClient > AllowHTTPいいえ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>

リストが空でない場合は、リスト内のサーバーにのみHTTP(S)要求を送信できます。リストが空の場合は、要求を任意のHTTP(S)サーバーに送信できます。

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

証明書の検証なしの HTTPS の使用

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

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

HTTP(S)リクエストを送信する

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

  • xCommand HttpClient <Method> [AllowInsecureHTTPS: <True/False>] [Header: <Header text>] [ResponseSizeLimit: <Maximum response size>] [ResultBody: <None/PlainText/Base64>] [Timeout: <Timeout period>] Url: <URL to send the request to>

ヘッダフィールドの追加はオプションですが、最大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 Header: "Content-Type: application/json" URL: "http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state"
{"on":true}
.

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

xcommand HttpClient Post Header: "Content-Type: application/json" URL: "https://mymonitoringserver.com/service/devicemonitoring"
{"Message":"A user reported an issue with this system","systemName":"BoardRoom 4th floor","softwareVersion":"ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Dual"}
.

詳細情報

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

Ciscoサポート(TAC)は、マクロを含むサードパーティコードのデバッグに対応していません。マクロおよびサードパーティコードに関してサポートが必要な場合は、Cisco Collaboration Developerコミュニティに確認してください。また、このサイトには多くの開発者およびインテグレータのリソースがあります。