Board、Room、またはデスクデバイスからの HTTP 要求の送信

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

セキュリティ対策：

HTTP(S) クライアント要求機能は、デフォルトでは無効に設定されています。システム管理者は、HttpClient > モードをOn（xConfiguration 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 > AllowInsecureHTTPSをOnに設定できます（xConfiguration HttpClient AllowInsecureHTTPS：On）。これにより、サーバの証明書を検証せずに HTTPS を使用することができます。

HTTP（S）リクエストを送信する

HTTP(S) クライアント要求機能が有効になると、以下のコマンドを使用して、要求を HTTP(S) サーバに送信することができます。<method> は、Post、Put、Patch、Get、あるいは 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コミュニティに確認してください。また、このサイトには多くの開発者およびインテグレータのリソースがあります。