매크로를 사용하면 필요할 때마다 HTTP 서버로 데이터를 보낼 수 있습니다. 전송되는 데이터와 구성 방법을 제어할 수 있으므로 기존 서비스에 사용할 수 있도록 데이터를 간단하게 조정할 수 있습니다.

보안 수단:

  • 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) 동시 요청 수는 제한되어 있습니다.

이 문서에서 참조하는 구성은 디바이스의 웹 인터페이스와 API 모두에서 사용할 수 있습니다. 명령은 API 통해 사용할 수 있습니다. 웹 인터페이스에 액세스하고 API를 사용하는 방법에 대한 자세한 내용은 고급 설정 문서를 참조하십시오.

허용되는 HTTP(S) 서버 목록

시스템 관리자는 다음 명령을 사용하여 최대 10개의 허용되는 HTTP(S) 서버(호스트) 목록을 설정하고 유지 관리할 수 있습니다.

  • xCommand HttpClient 호스트 이름 추가 허용 식: <HTTP(S) 서버의 호스트 이름 또는 IP 주소와 일치하는 정규식>

  • xCommand HttpClient 호스트 이름 지우기 허용

  • xCommand HttpClient 호스트 이름 목록 허용

  • xCommand HttpClient 호스트 이름 Id 제거 허용: <목록에서 항목의 id>

목록에 서버 항목이 포함된 경우 해당 서버에만 HTTP 요청을 보낼 수 있습니다. 그러나 목록이 비어 있는 경우 모든 HTTP 서버에 요청을 보낼 수 있습니다.

허용 서버 목록에 대한 검사는 비보안(HTTP) 데이터 전송과 보안(HTTPS) 데이터 전송을 모두 사용할 때 수행됩니다.

인증서 유효성 검사가 없는 HTTPS

HTTPS를 통해 요청을 보낼 때 장치는 기본적으로 HTTPS 서버의 인증서를 검사합니다. HTTPS 서버 인증서가 유효하지 않은 경우 오류 메시지가 나타납니다. 장치가 해당 서버로 아무런 데이터도 전송하지 않습니다.

인증서 검증과 함께 HTTPS를 사용하는 것이 좋습니다. 인증서 유효성 검사가 불가능한 경우 시스템 관리자는 HttpClient > AllowInsecureHTTPS 를 On ( xConfiguration HttpClient AllowInsecureHTTPS: On )으로 설정할 수 있습니다. 이렇게 하면 서버 인증서의 유효성을 검증하지 않고 HTTPS를 사용할 수 있습니다.

HTTP 요청 보내기

HTTP(S) 클라이언트 요청 기능을 활성화하면 다음 명령을 사용하여 HTTP(S) 서버에 요청을 보낼 수 있습니다. <method>는 Post, Put, Patch, Get 또는 Delete 중 하나입니다.

  • xCommand HttpClient<메서드> [AllowInsecureHTTPS: <참/거짓>] [헤더: <헤더 텍스트>] [ResponseSizeLimit: <최대 응답 크기>] [ResultBody: <없음/PlainText/Base64>] [시간 초과: <시간 초과 기간>] URL: <요청을 보낼 URL입니다>

헤더 필드 추가는 선택 사항이며 최대 20개의 필드를 추가할 수 있습니다.

AllowInsecureHTTPS 매개 변수는 시스템 관리자가 서버 인증서를 검증하지 않고 HTTPS 사용을 허용한 경우에만 유효합니다. 이 경우 매개 변수가 True로 설정된 경우 서버 인증서를 검증하지 않고 데이터를 서버로 전송할 수 있습니다. 매개 변수를 생략하거나 False로 설정한 경우 인증서 검증이 실패하면 데이터가 전송되지 않습니다.

ResposenSizeLimit 매개 변수는 장치가 서버의 응답으로 받아들이는 최대 페이로드 크기(바이트)입니다. 응답 페이로드가 이 최대 크기보다 크면 이 명령은 상태 오류를 반환합니다. 최대 파일 크기가 초과되었다는 오류 메시지가 표시됩니다. 그러나 이 오류는 서버측에 영향을 미치지 않습니다. 서버에서 요청을 올바르게 수신 하고 처리합니다.

Resultbody 매개 변수를 사용하여 명령 결과에서 서버로부터 HTTP 응답의 본문에 대한 형식을 지정하는 방법을 결정합니다. 다음 세 가지 옵션을 사용할 수 있습니다.

  • None: 명령 결과에 HTTP 응답의 본문을 포함하지 않습니다.

  • Base64: Base64는 결과에 포함하기 전에 본문을 인코딩합니다.

  • PlainText: 결과에 본문을 일반 텍스트로 포함합니다. 응답에 인쇄되지 않는 문자가 포함된 경우 이 명령은 인쇄할 수 없는 데이터가 있음을 알리는 메시지와 함께 상태 오류를 반환합니다.

Timeout 매개 변수를 사용하여 시간 초과 기간(초)을 설정합니다. 이 기간 동안 요청이 완료되지 않으면 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 포스트 헤더: "Content-Type: application/json" URL: "https://mymonitoringserver.com/service/devicemonitoring" {"Message":"사용자가 이 시스템에 문제를 보고했습니다","systemName":"BoardRoom 4th floor","softwareVersion":"ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Dual"} .

추가 정보

사용자 지정 설명서에서 HTTP 클라이언트 요청을 사용하는 방법에 대한 자세한 내용을 확인하십시오. 최신 버전을 선택합니다.

Cisco 지원(TAC)은 매크로를 비롯한 타사 코드의 디버깅을 지원하지 않습니다. 매크로 및 타사 코드에 대한 도움이 필요한 경우 https://roomos.cisco.com 를 확인하십시오 .