워크플레이스 커넥터 웹후크 API

  • 릴리스 버전: Xanadu
  • 업데이트 날짜 2024년 08월 01일
  • 읽기8분

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

    이 API는 sn_wsd_wc 네임스페이스에서 실행됩니다. 이 API에 액세스하려면 Workplace Connectors(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.

    직장 커넥터 웹후크 - /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/v1/workplace_connector_webhook/event

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

    지원되는 요청 매개변수

    표 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 .
    • success: 엔드포인트가 성공적으로 완료되었습니다. 기록이 추가되었습니다.

    데이터 유형: 문자열

    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"
}