직장 커넥터 웹후크 API

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 8분

    • 직장 커넥터 웹후크 API는 다양한 종류의 직장 하드웨어 또는 센서(예: 배지 시스템 또는 점유 센서)의 데이터를 직장 서비스 제공 테이블에 저장할 수 있는 일반 인터페이스입니다.

    이 API는 sn_wsd_wc 네임스페이스에서 실행됩니다. 이 API에 액세스하려면 com.sn_wsd_wc(작업 공간 커넥터) 플러그인을 활성화해야 합니다.

    이 API를 호출하기 전에 커넥터 구성 [sn_wsd_wc_connector_config] 및 제공자 구성 [sn_wsd_wc_provider_config] 테이블에서 기록을 구성해야 합니다. 이러한 기록을 구성하는 방법에 대한 자세한 내용은 다음 문서를 참조하십시오 Configure Workplace Connectors.

    또한 하드웨어/센서 기반 이벤트 페이로드에서 직원 출석 데이터[sn_wsd_wc_employee_attendance_data] 테이블과 같은 대상 ServiceNow 테이블로의 데이터 변환/매핑을 정의하는 확장점을 설정해야 합니다.

    작업 공간 커넥터 웹후크에 대한 자세한 내용은 다음 문서를 참조하십시오 Workplace Connectors.

    직장 커넥터 웹후크 - POST /workplace_connector_webhook/event

    커넥터 이벤트 [sn_wsd_wc_connector_events] 테이블에 기록을 생성한 다음 엔드포인트의 페이로드에 전달된 하드웨어/센서 기반 이벤트 데이터를 해당 기록의 페이로드 필드에 저장합니다.

    엔드포인트는 페이로드를 저장한 후 커넥터 이벤트 기록 내의 상태 필드를 신규로 설정하여 페이로드가 처리되지 않았음을 나타냅니다.

    예약된 작업은 커넥터 이벤트 테이블에서 새 배지 기록을 찾아 변환하여 직원 출석 데이터[sn_wsd_wc_employee_attendance_data] 테이블에 기록합니다. 그러면 상태 필드가 처리됨으로 설정됩니다.

    커넥터 이벤트 기록의 페이로드 데이터와 직원 출석 데이터 기록 간의 데이터 매핑은 확장점에 정의됩니다. 이 확장점은 연결된 커넥터 구성 [sn_wsd_wc_connector_config] 테이블의 확장점 정의 필드에서 식별됩니다. 이 엔드포인트의 경우 BadgingDataHandler 확장점입니다.

    주:
    처리됨 상태의 커넥터 이벤트 테이블의 기록은 생성 날짜로부터 2일 후에 제거됩니다. 오류 상태의 기록은 생성 날짜로부터 7일 후에 제거됩니다. 새 상태의 기록은 절대 제거되지 않습니다.

    URL 형식

    버전이 지정된 URL: /api/sn_wsd_wc/{api_version}/workplace_connector_webhook/event

    기본 URL: /api/sn_wsd_wc/workplace_connector_webhook/event

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    표 1. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다.

    데이터 유형: 문자열
    표 2. 쿼리 매개변수
    이름 설명
    ni.nolog.id 필수 이벤트 정보를 생성한 하드웨어와 연결된 제공자 구성 기록의 Sys_id입니다.

    데이터 유형: 문자열

    테이블: 제공자 구성 [sn_wsd_wc_provider_config]
    token_name 보안 토큰을 식별하는 사용자 이름 또는 기타 값과 같은 보안 토큰의 이름입니다. 요청을 인증하는 데 사용됩니다.

    데이터 유형: 문자열

    테이블: 제공자 구성 [sn_wsd_wc_provider_config]
    token_value 암호와 같은 보안 토큰과 연결된 값입니다. 요청을 인증하는 데 사용됩니다.

    데이터 유형: 문자열

    테이블: 제공자 구성 [sn_wsd_wc_provider_config]
    표 3. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    <페이로드> 하드웨어/센서 기반 이벤트 데이터의 이름-값 쌍.

    이름은 BadgingDataHandler 확장점에서 식별된 이름과 일치해야 합니다.

    예:

    {
  "Time zone": "(UTC-08:00) Pacific Time (US & Canada)",
  "Event": "Access granted",
  "Door": "L_SJC005_B1.101_ELEVATOR 2 INT",
  "Side": "Reader - In",
  "Cardholder": "ninat.salem",
  "First name": "Nina T",
  "Last name": "Salem",
  "Credential": " ninat.salem's credential",
  "Employee ID (Cardholder)": "10097",
  "Event timestamp": "11/07/2022 00:56:57"
}

    단일 엔드포인트 호출 내에서 여러 이벤트의 데이터를 전달할 수 있습니다. 각 이벤트의 데이터를 별도의 개체에 전달합니다. 각 이벤트의 데이터는 별도의 직원 출석 데이터 기록에 저장됩니다.

    주:
    제공된 타임스탬프가 ISO 8601 형식을 준수하는지 확인하여 날짜 구문 분석 문제를 방지합니다.

    데이터 유형: JSON 객체

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 4. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. application/json만 지원합니다.
    컨텐츠-형식 요청 본문의 데이터 형식입니다. application/json만 지원합니다.
    표 5. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 6. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
    401 승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    404 찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수

    이름 설명
    오류 데이터 처리 중에 발생한 오류에 대한 설명입니다.

    데이터 유형: 객체

    "error": {
  "detail": "String",
  "message": "String"
"status": "String"
}
    오류.상세 정보 오류에 대한 상세 정보를 제공하는 정보입니다.

    데이터 유형: 문자열
    오류.메시지 오류 메시지.

    데이터 유형: 문자열
    상태 엔드포인트 처리의 상태입니다.
    가능한 값:
    • failure: 엔드포인트가 실패했습니다. 자세한 내용은 객체를 참조하십시오 error .
    • 성공: 엔드포인트가 성공적으로 완료되었습니다. 기록이 추가되었습니다.

    데이터 유형: 문자열

    cURL 요청

    다음 코드 예에서는 이 끝점을 호출하여 커넥터 이벤트 테이블에 여러 카드 판독기 이벤트를 추가하는 방법을 보여 줍니다. 요청을 처리하기 전에 요청이 인증됩니다.

    curl http://instance.servicenow.com/api/sn_wsd_wc/v1/workplace_connector_webhook/event?token_name=token&ni.nolog.id=8e666cb0a3053110bc6e146546fcdad1&token_value=babugosha  \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data --data "{
  \"Time zone\": \"(UTC+02:00) Jerusalem\",
  \"Event\": \"Access granted\",
  \"Door\": \"L_TLV001_A3.07_KITCHEN AREA INT\",
  \"Side\": \"Reader - In\",
  \"Cardholder\": \" ninat.alem\",
  \"First name\": \" Nina T\",
  \"Last name\": \" Salem\",
  \"Credential\": \" ninat.salem's credential\",
  \"Employee ID (Cardholder)\": 10097,
  \"Event timestamp\": \"11/07/2022 10:57:24\"
}
{
  \"Time zone\": \"(UTC+02:00) Jerusalem\",
  \"Event\": \"Access granted\",
  \"Door\": \"L_TLV003_A4.07_FRONT ENT\",
  \"Side\": \"Reader - In\",
  \"Cardholder\": \" joe.blue\",
  \"First name\": \" Joe\",
  \"Last name\": \" Blue\",
  \"Credential\": \" joe.blue's credential\",
  \"Employee ID (Cardholder)\": 24098,
  \"Event timestamp\": \"11/07/2022 10:59:33\"
}"

    응답:

    // Successful response
{
  "staus": "success"
}

// Error response
{
  "error": {
    "message": "Events request is invalid. Events query parms incomplete, some fields are missing",
    "detail": "Missing fields: token_name, token_value"
  }
  "status": "failure"
}