VIGI 카메라 OpenAPI 기능 사용 방법

내용

소개

요구 사항

설정

OpenAPI 액세스 설정

Control 인터페이스 인증 및 API 요청

Stream 인터페이스 인증 및 스트림 요청

검증

결론

질문과 답변
 

소개

VIGI 카메라 OpenAPI를 사용하면 타사 애플리케이션이 네트워크를 통해 VIGI 카메라와 통신하여 장치 설정, 이벤트 구독 및 스트림 관련 작업을 수행할 수 있습니다. 제어 인터페이스를 통해 OpenAPI 클라이언트는 카메라 매개변수를 조회하거나 설정하고, 이벤트 메시지를 구독할 수 있습니다. 스트림 인터페이스를 통해 미리 보기, 재생, 녹화 파일 다운로드, 대화와 같은 스트림 관련 작업을 수행할 수 있습니다.

이 문서에서는 VIGI 카메라에서 OpenAPI를 활성화하고, 인증을 완료하며, 제어 인터페이스 API를 호출하고, 스트림 인터페이스 요청의 일반적인 워크플로를 이해하는 방법을 소개합니다.

요구 사항

• OpenAPI를 지원하는 VIGI IP 카메라 (지원되는 모델을 확인하려면 ‘VIGI Open API 지원 장치’를 참조하십시오)
• VIGI IP 카메라 OpenAPI 문서
• 네트워크를 통해 카메라에 액세스할 수 있는 OpenAPI 클라이언트

설정

OpenAPI 액세스 설정

VIGI 카메라 OpenAPI 인터페이스를 호출하기 전에 카메라에서 OpenAPI를 활성화해야 합니다. 다음 단계에서는 카메라 웹 관리 페이지를 예시로 사용합니다.

1단계. 카메라의 IP 주소를 사용하여 카메라 웹 인터페이스에 로그인합니다. 사용자 이름과 비밀번호를 입력한 후 로그인을 클릭합니다.

2단계. 설정 > 네트워크 설정 > OpenAPI로 이동하여 OpenAPI 스위치를 켠 다음, 적용을 클릭하여 설정을 저장합니다.

Control 인터페이스 인증 및 API 요청

VIGI 카메라 OpenAPI 제어 인터페이스는 HTTPS를 사용합니다. 제어 인터페이스를 호출하기 전에 OpenAPI 클라이언트는 Do Auth 인증을 완료하고 토큰을 획득해야 합니다. 기본 OpenAPI 제어 포트는 20443입니다.

1단계. 첫 번째 doAuth 요청을 전송하여 인증 필드를 가져옵니다.

https://<CAMERA_IP>:20443으로 POST 요청을 전송합니다. 요청 본문에서 method를 doAuth로 , params를 공란 으로 설정합니다. 카메라는 응답을 계산하는 데 사용되는 인증 필드(realm, nonce, algorithm, uri, method 등)를 반환합니다.
Windows에서 사용할 수 있는 curl 명령어 예시는 다음과 같습니다.
요청:
curl.exe --% -k -X POST https://192.168.0.100:20443 -H "Content-Type: application/json" -d "{\"method\":\"doAuth\",\"params\":null}"
응답:
{"method":"doAuth","authenticate":{"realm":"TP-LINK IP-Camera","nonce":"c51594999c7dcfd020e97a2688d431d0","algorithm":"SHA-256","uri":"doAuth","method":"POST"},"errCode":-10020}

2단계. 토큰을 얻기 위해 두 번째 doAuth 요청을 전송합니다.
1단계에서 반환된 인증 필드와 카메라 로그인 비밀번호를 기반으로 응답을 계산합니다. 반환된 알고리즘이 SHA-256인 경우, 다음과 같이 응답을 계산합니다:

A1 = SHA256(admin:<realm>:<password>)

A2 = SHA256(<method>:<uri>)

response = SHA256(A1:<nonce>:A2)
그런 다음 https://<CAMERA_IP>:20443으로 POST 요청을 전송합니다. 요청 본문에서 method를 doAuth로 설정하고, 반환된 nonce와 계산된 response를 params에 포함시킵니다.

Windows에서 curl 명령어를 사용하는 예시는 다음과 같습니다:

요청:
curl.exe --% -k -X POST https://192.168.0.100:20443 -H "Content-Type: application/json" -d "{\"method\":\"doAuth\",\"params\":{\"nonce\":\"c51594999c7dcfd020e97a2688d431d0\",\"response\":\"ae990e323d2370c9a6cbcf638b5808f006f2c32343034787205f00d81c1fe16a\"}}"
응답:
{"method":"doAuth","stok":"jqNXOtUS7*Qu0XSvOqO0uOXst1ZlOOcD","errCode":0}

3단계. 제어 인터페이스 API 호출

stok을 획득한 후, 이를 요청 URL에 추가하고 대상 제어 인터페이스 요청을 JSON 형식으로 전송합니다. 요청 method는 POST이며, 요청 URL 형식은 https://<Camera_IP>:20443/stok=<stok>입니다.

이 섹션에서는 카메라 시간대 설정을 위한 일반적인 제어 인터페이스 요청 예시와 이벤트 메시지를 수신하기 위한 이벤트 구독 요청 예시 두 가지를 제공합니다.

예제 1: 카메라 시간대 설정
setTimeZone 인터페이스는 카메라 시간대를 설정하는 데 사용됩니다. 요청 본문에서 method를 setTimeZone으로 설정하고, params에 시간대(timezone)와 지역(area)을 설정합니다. 다음 예제는 카메라 시간대를 America/Los_Angeles로 설정합니다.

요청:
curl.exe --% -k -X POST https://192.168.0.100:20443/stok=jqNXOtUS7*Qu0XSvOqO0uOXst1ZlOOcD -H "Content-Type: application/json" -d "{\"method\":\"setTimeZone\",\"params\":{\"timezone\":\"UTC-08:00\",\"area\":\"America/Los_Angeles\"}}"
응답:
{"method":"setTimeZone","errCode":0}

예제 2: 이벤트 메시지 구독

subscribeMsg 인터페이스는 이벤트 감지 메시지를 구독하는 데 사용됩니다. 요청 본문에서 method를 subscribeMsg로 설정하고, params에서 event_type 및 heartbeat를 구성하십시오. 요청을 전송한 후에는 연결을 열어 두십시오. 카메라는 주기적으로 하트비트 패킷을 전송하며, 이벤트가 발생하면 동일한 연결을 통해 이벤트 메시지를 푸시합니다.

요청:

curl.exe --% -k -N -X POST https://192.168.0.100:20443/stok=jqNXOtUS7*Qu0XSvOqO0uOXst1ZlOOcD -H "Content-Type: application/json" -d "{\"method\":\"subscribeMsg\",\"params\":{\"event_type\":[\"all\"],\"heartbeat\":10}}"

응답:

{"method":"subscribeMsg","errCode":0}

Stream 인터페이스 인증 및 스트림 요청

VIGI 카메라 OpenAPI 스트림 인터페이스는 RTSP를 통해 구축됩니다. OpenAPI 클라이언트는 스트림 관련 요청을 전송하기 전에 다이제스트 인증을 완료해야 합니다. 이 섹션에서는 녹화 파일 다운로드 시나리오를 예로 들어 일반적인 스트림 인터페이스 워크플로를 설명합니다.

1단계. 필요한 경우 스트림 요청 매개변수를 가져옵니다.

스트림 인터페이스 다운로드 요청과 같은 일부 스트림 작업의 경우, 클라이언트는 먼저 제어 인터페이스를 통해 필요한 매개변수를 확보해야 합니다. 예를 들어, 다운로드 요청을 전송하기 전에 VIGI IP 카메라 OpenAPI 문서의 4.11.1절에 있는 getMediaList를 호출하여 녹화 시작 시간, 종료 시간, FileID, event_type 및 기타 관련 정보를 확보해야 합니다. 그런 다음 스트림 인터페이스 다운로드 요청에서 필요한 매개변수를 사용합니다.

2단계. RTSP 포트를 확인합니다.

카메라 웹 관리 페이지의 설정 > 네트워크 설정 > 네트워크 서비스 > RTSP에서 카메라의 RTSP 포트를 확인하십시오. 이 예시에서 RTSP 포트는 554입니다. 포트 포워딩을 통해 카메라에 접속하는 경우, 카메라의 내부 RTSP 포트 대신 라우터에 매핑된 외부 RTSP 포트를 사용하십시오.

3단계. RTSP 연결을 설정하고 다이제스트 인증을 완료합니다.

클라이언트는 카메라의 RTSP 포트에 TCP 연결을 설정하고 초기 MULTITRANS 요청을 전송합니다. 카메라는 Digest Authentication 매개변수가 포함된 401 Unauthorized 응답을 반환합니다. 클라이언트는 사용자 이름, 비밀번호, 요청 메서드, 요청 URI 및 반환된 인증 매개변수를 기반으로 인증 응답을 계산한 다음, 인증 헤더를 포함하여 MULTITRANS 요청을 다시 전송합니다. Digest Authentication 계산에 대한 자세한 내용은 VIGI IP 카메라 OpenAPI 문서의 2.2.2장의 다이제스트 인증을 참조하십시오.

4단계. 스트림 인터페이스 요청을 전송합니다.

다이제스트 인증이 성공하면 클라이언트는 미리보기, 재생, 녹화 파일 다운로드, 중지, 재생, I-프레임 강제 전송 또는 대화와 같은 필요한 스트림 인터페이스 요청을 전송합니다. 녹화 파일 다운로드의 경우, 카메라는 코덱 정보와 함께 200 OK를 반환하고 TCP 연결을 통해 RTP 데이터 전송을 시작합니다. 스트림 인터페이스 메서드 및 매개변수에 대한 자세한 내용은 VIGI IP 카메라 OpenAPI 문서의 5장 OpenAPI 스트림 인터페이스를 참조하십시오.

5단계. RTP 데이터 수신 및 파싱.

스트림 데이터는 TCP를 통해 RTP로 전송됩니다. 클라이언트는 선두에 있는 $ 바이트를 통해 RTP 패킷을 식별하고, 채널 ID와 페이로드 길이를 읽은 다음, RTP 헤더와 페이로드를 파싱해야 합니다. 또한 클라이언트는 RTP 페이로드 유형에 따라 미디어 유형을 식별해야 합니다. TCP를 통한 RTP 패킷 구조에 대한 자세한 내용은 제2.3절 데이터 전송을 참조하십시오. 페이로드 유형 정의에 대해서는 VIGI IP 카메라 OpenAPI 문서의 부록 2 페이로드 유형을 참조하십시오.

6단계. 오디오 데이터가 포함된 경우 오디오 코덱을 확인하고 처리합니다.

스트림 작업에 오디오 데이터(예: 오디오가 포함된 녹화 다운로드 또는 대화)가 포함된 경우, 먼저 VIGI IPC OpenAPI 문서의 4.4.6절에 있는 getAudioEncode 인터페이스를 호출하여 카메라 오디오 코덱을 확인해야 합니다. 클라이언트는 반환된 encode_type에 따라 오디오 RTP 페이로드를 처리해야 합니다.

검증

위의 예제에서 제어 인터페이스 API를 호출한 후, 다음과 같이 결과를 확인하십시오.
예제 1 확인: 카메라 시간대
설정 setTimeZone 요청이 "errCode": 0을 반환한 후, 카메라 웹 관리 페이지에 로그인하여 설정 > 시스템 설정 > 기본 설정 > 날짜로 이동하십시오. 시간대 값이 설정한 시간대로 변경되었는지 확인하십시오. 이 예제에서는 시간대가 (UTC-08:00) 태평양 표준시로 변경되어야 합니다.

예제 2 등록: 이벤트 메시지 구독

subscribeMsg 요청이 "result": "success" 및 "errCode": 0을 반환한 후, 명령어를 계속 실행 상태로 유지합니다. 카메라는 설정된 하트비트 간격에 따라 하트비트 패킷을 전송하며, 이벤트가 트리거되면 동일한 연결을 통해 이벤트 메시지를 푸시합니다.

이 예제에서 event_type은 all로, heartbeat는 10으로 설정되어 있습니다. 따라서 터미널에는 10초마다 하트비트 패킷이 출력되고, 구독한 이벤트가 트리거될 때마다 이벤트 메시지가 출력되어야 합니다.

결론

이 문서의 단계를 완료하면 VIGI 카메라에서 OpenAPI를 활성화하고, 인증을 완료한 후 필요에 따라 제어 인터페이스(Control Interface) 또는 스트림 인터페이스(Stream Interface)를 호출할 수 있습니다. 또한 이 예제를 통해 일반적인 제어 인터페이스 호출을 등록하는 방법과 스트림 인터페이스 요청의 전반적인 워크플로를 파악할 수 있습니다.

질문과 답변

Q1: 클라이언트가 제어 인터페이스를 호출할 때 연결을 어떻게 관리해야 합니까?
A1: 제어 인터페이스 호출의 경우, 각 API 요청마다 새로운 연결을 생성해야 합니다.

doAuth를 통해 stok을 획득한 후, 해당 stok을 사용하여 getDeviceInfo나 setTimeZone과 같은 필요한 제어 인터페이스 API를 호출하십시오. 각 API 요청은 독립적으로 전송 및 처리될 수 있도록 별도의 연결을 통해 전송되어야 합니다.

subscribeMsg의 경우, 구독이 성공한 후에도 연결을 열어 두어야 합니다. 카메라는 이 연결을 사용하여 하트비트 패킷과 이벤트 메시지를 전송합니다.

Q2: VIGI IP 카메라 OpenAPI 문서는 어디에서 찾을 수 있나요?
A2: 다운로드 센터로 이동하여 카메라 모델을 검색한 후, 해당 제품 다운로드 페이지를 엽니다. 매뉴얼 섹션에서 해당 VIGI IP 카메라 OpenAPI 문서를 다운로드하십시오.

각 기능 및 설정에 대한 자세한 내용을 확인하려면 다운로드 센터에서 해당 제품의 설명서를 다운로드하십시오.
 

이 문서에는 기계 번역이 적용되었으며, 정확한 내용을 확인하려면 원본 영문 문서를 참고하시기 바랍니다.