WSD 통합 검색 API

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 04월 28일
  • 소요 시간: 19분

    • WSD 통합 검색 API는 직장 사용자 및 위치 전체에서 검색할 수 있는 엔드포인트를 제공합니다.

    WSD 통합 검색 API는 sn_wsd_core 네임스페이스에서 실행되며 (WSD) 포털에서 워크플레이스 서비스 제공 검색/자동 완성 환경을 강화하여 일치하는 사용자, 공간, 층, 건물, 캠퍼스 및 인접 지역을 단일 응답으로 반환합니다.

    요구 사항

    WSD 통합 검색 API에는 다음이 필요합니다.
    • 호출 사용자에게 sn_wsd_core.workplace_user 역할이 있습니다.
    • Core(com.sn_wsd_core) 플러그인이 워크플레이스 서비스 제공 활성 상태여야 합니다.
    • 직장 위치 계층 구조에 하나 이상의 건물과 층을 구성해야 합니다.

    WSD 통합 검색 - POST /api/sn_wsd_core/wsd_unified_search/users_and_locations

    제공된 검색어와 일치하는 사용자 및 직장 위치(대/소문자 구분 안 함)를 검색합니다. 페이지 매김 지원을 통해 일치하는 결과의 결합된 목록을 반환합니다.

    URL 형식

    버전이 지정된 URL: /api/sn_wsd_core/{api_version}/wsd_unified_search/users_and_locations

    기본 URL: /api/sn_wsd_core/wsd_unified_search/users_and_locations

    지원되는 요청 매개변수

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

    데이터 유형: 문자열
    표 2. 쿼리 매개변수
    이름 설명
    안 함
    표 3. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    search_term 일치하는 사용자 및 직장 위치를 찾는 데 사용되는 검색 쿼리입니다. 콤마로 구분된 값 목록을 사용하여 여러 용어를 동시에 검색할 수 있습니다. 예를 들어, "회의, 데스크" 는 두 용어 중 하나와 일치하는 결과를 반환합니다. 빈 세그먼트는 무시됩니다.

    데이터 유형: 문자열

    기본값: 빈 문자열(모든 결과 반환)
    show_location 결과 레이블에 사용자의 현재 위치를 포함할지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 결과 레이블에 사용자의 현재 위치를 표시합니다.
    • false: 결과 레이블에 사용자의 현재 위치를 표시하지 않습니다.

    데이터 유형: 부울

    기본값: true
    show_loggedin_user 검색어가 제공되지 않은 경우 인증된 사용자를 첫 번째 결과로 표시할지 여부를 나타내는 플래그입니다. 오프셋 0의 데스크톱 클라이언트에만 적용됩니다.
    가능한 값:
    • true: 인증된 사용자를 첫 번째 결과로 표시합니다.
    • false: 인증된 사용자를 첫 번째 결과로 표시하지 않습니다.

    데이터 유형: 부울

    기본값: true
    include_user_email 결과 레이블에 사용자 이메일 주소를 포함하고 이메일 주소로 검색을 허용할지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 결과 레이블에 이메일을 포함하고 이메일 검색을 활성화합니다.
    • false: 결과 레이블에 이메일을 포함하거나 이메일 검색을 활성화하지 않습니다.

    데이터 유형: 부울

    기본값: false
    filterConfig 테이블별로 인코딩된 쿼리. 키는 테이블 이름입니다. 값은 인코딩된 쿼리 문자열입니다.
    유효한 필드(테이블 이름):
    • sys_user
    • sn_wsd_core_workplace_location
    • sn_wsd_core_region
    • sn_wsd_core_site
    • sn_wsd_core_campus
    • sn_wsd_core_building
    • sn_wsd_core_floor
    • sn_wsd_core_area
    • sn_wsd_core_space
    • sn_wsd_core_room
    • sn_wsd_core_neighborhood

    데이터 유형: 객체

    "filterConfig": {
  "<table_name>": Boolean
}

    기본값: {}(적용된 필터 없음, 모든 테이블 검색)
    filterConfig.<table_name> 지정된 테이블의 결과를 포함할지 여부를 나타내는 플래그입니다. 해당 엔터티 유형의 결과를 포함하려면 true로 설정합니다.
    유효한 값은 다음과 같습니다.
    • true: 해당 엔터티 유형의 결과를 포함합니다.
    • false: 해당 엔터티 유형의 결과를 포함하지 않습니다.

    데이터 유형: 부울
    옵션 검색 동작에 대한 추가 구성을 포함하는 객체입니다.

    데이터 유형: 객체

    "options": { 
  "search_in_parent": Boolean,
  "cache": Boolean,
  "rsvModule": {Object}
}
    options.search_in_parent 하위 엔터티로 필터링할 때 상위 위치 기록의 결과를 포함할지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 상위 위치 결과를 포함합니다.
    • false: 상위 위치 결과를 포함하지 않습니다.

    데이터 유형: 부울
    옵션.캐시 캐시된 검색 결과를 사용할지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 사용 가능한 경우 캐시된 결과를 사용합니다.
    • false: 항상 새로운 결과 가져오기

    데이터 유형: 부울
    options.rsv모듈 예약 가능한 모듈 컨텍스트별로 결과를 필터링하기 위한 예약 모듈 구성을 포함하는 객체입니다.

    데이터 유형: 객체

    "rsvModule": { 
  "value": "String"
}
    options.rsvModule.value 사용 가능한 공간을 필터링하는 데 사용할 예약 가능한 모듈의 Sys_id입니다.

    테이블: 예약 가능한 모듈 [sn_wsd_rsv_reservable_module]

    데이터 유형: 문자열
    options.rsvModule.enable_restricted_neighborhood_rules 예약 모듈별로 결과를 필터링할 때 제한된 인접 규칙을 적용할지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 제한된 인접 규칙을 적용합니다.
    • false: 제한된 인접 규칙을 적용하지 않습니다.

    데이터 유형: 부울
    sysparam_offset 페이지 매김 오프셋입니다. 결과를 반환하기 전에 건너뛰는 기록 수입니다. 페이지 매김에 함께 sysparam_limit 사용합니다.

    최소값: 0

    데이터 유형: 숫자

    기본값: 0
    sysparam_limit 요청당 반환할 최대 기록 수입니다. 페이지 매김에 함께 sysparam_offset 사용합니다.

    최소값: 1

    데이터 유형: 숫자

    기본값: 10
    주:
    모든 검색은 대/소문자를 구분하지 않습니다.

    헤더

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

    표 4. 요청 헤더
    머리글 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형: application/json, application/xml, text/xml.
    콘텐츠-형식 요청 본문의 데이터 형식: application/json.
    권한 부여 인증 자격 증명입니다. 기본 인증 또는 세션 기반 인증을 지원합니다.
    표 5. 응답 헤더
    머리글 설명
    콘텐츠-형식 응답 본문의 데이터 형식: application/json.

    상태 코드

    이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

    표 6. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 본문 형식입니다.
    401 인증에 실패했습니다.
    403 사용자에게 필요한 ACL 권한이 없습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다.

    응답 본문 매개변수(JSON 또는 XML)

    이름 설명
    결과 요청의 결과를 포함하는 객체입니다.

    데이터 유형: 객체

    "result": {
  "result": [Array],
  "more": Boolean,
  "isMobile": Boolean
}
    result.isMobile 요청이 모바일 클라이언트에서 시작된 것으로 탐지되었는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 모바일 클라이언트에서 요청이 시작되었습니다.
    • false: 데스크톱 클라이언트에서 요청이 시작되었습니다.

    데이터 유형: 부울
    결과.더 보기 현재 페이지 이상에서 추가 결과를 사용할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 더 많은 결과를 사용할 수 있습니다. 다음 페이지를 검색하려면 증가 sysparam_offset 합니다 sysparam_limit .
    • false: 더 이상 사용할 수 있는 결과가 없습니다.

    데이터 유형: 부울
    결과.결과 일치하는 사용자 및 위치 객체의 배열입니다. 각 객체에는 모든 결과 유형에서 공유되는 공통 필드와 사용자 결과에만 존재하는 유형별 필드가 포함되어 있습니다.

    데이터 유형: 객체 배열

    "result": [
  {
    "displayValue": "String",
    "value": "String",
    "table": "String",
    "label": "String",
    "selectedTreeBranch": "String",
    "timezone": {Object},
    "wsdSource": "String",
    "externalId": "String",
    "floorId": "String",
    "isReservable": Boolean
  }
]
    result.result.displayValue 결과의 표시 이름입니다. 예를 들어 회의실 A - 공간의 경우 1층, 사용자의 경우 Jane Doe 입니다.

    데이터 유형: 문자열
    result.result.externalId 해당하는 경우 외부 소스 시스템에 있는 결과 기록의 식별자입니다.

    데이터 유형: 문자열
    result.result.floorId 결과 위치가 있는 층의 Sys_id입니다. 위치 결과에만 표시됩니다.

    테이블: 직장 층 [sn_wsd_core_floor]

    데이터 유형: 문자열
    result.result.isReserved 가능 결과 위치를 예약할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 위치를 예약할 수 있습니다.
    • false: 위치를 예약할 수 없습니다.

    데이터 유형: 부울
    결과.결과.레이블 결과에 대한 추가 컨텍스트를 제공하는 보조 표시 문자열입니다. 예를 들어 공간의 위치 계층 구조나 사용자의 부서 및 직책이 있습니다.

    데이터 유형: 문자열
    result.result.selectedTreeBranch 이 결과와 연결된 직장 계층 구조의 상위 위치 기록 Sys_id입니다. UI에서 위치 트리를 미리 선택하는 데 사용됩니다.

    데이터 유형: 문자열
    결과.결과.테이블 결과가 시작된 테이블 이름입니다. 예를 들어 sn_wsd_core_space 또는 sys_user입니다.

    데이터 유형: 문자열
    결과.결과.시간대 결과 위치와 연결된 시간대입니다. 위치 결과에 대해 존재합니다.

    데이터 유형: 객체

    "timezone": {
  "displayValue": "String",
  "value": "String"
}
    result.result.timezone.displayValue 사람이 읽을 수 있는 시간대 이름입니다. 예를 들어 동부 표준시입니다.

    데이터 유형: 문자열
    결과.결과.시간대.값 결과 위치의 IANA 시간대 식별자입니다. 예: 아메리카/New_York.

    데이터 유형: 문자열
    result.result.userDetails 사용자 결과에 대한 추가 세부 정보를 포함하는 객체입니다. 사용자 결과에만 표시됩니다(사용자 [sys_user] 테이블).

    데이터 유형: 객체

    "userDetails": {
  "userID": "String",
  "name": "String",
  "department": "String",
  "avatar": "String",
  "initials": "String"
}
    result.result.userDetails.avatar 사용자 프로파일 아바타 이미지의 상대 URL 경로입니다.

    데이터 유형: 문자열
    result.result.userDetails.department 사용자가 속한 부서의 이름입니다.

    데이터 유형: 문자열
    result.result.userDetails.initials 사용자의 표시 이름에서 파생된 이니셜로, 아바타를 사용할 수 없는 경우 대체로 사용됩니다. 예를 들어 Jane Doe의 경우 JD입니다.

    데이터 유형: 문자열
    result.result.userDetails.name 사용자의 전체 표시 이름입니다. 예: Jane Doe.

    데이터 유형: 문자열
    result.result.userDetails.userID 사용자 기록의 Sys_id입니다.

    테이블: 사용자 [sys_user]

    데이터 유형: 문자열.
    결과.결과.값 결과 기록의 Sys_id입니다.

    데이터 유형: 문자열
    result.result.wsdSource 결과의 소스 시스템 식별자입니다. 위치가 외부 통합에서 시작된 경우 사용됩니다.

    데이터 유형: 문자열

    cURL 요청

    다음 예시에서는 특정 건물 내에서 "회의" 또는 "책상"과 일치하는 공간을 검색하여 최대 10개의 결과를 반환합니다.

    curl "https://<instance>.service-now.com/api/sn_wsd_core/wsd_unified_search/users_and_locations" \ 
--request POST \ 
--header "Accept: application/json" \ 
--header "Content-Type: application/json" \ 
--user "username:password" \
--data '{
  "search_term": "Conference, Desk",
  "show_location": true,
  "show_loggedin_user": true,
  "include_user_email": false,
  "filterConfig": {},
  "options": {
       "search_in_parent": false,
       "cache": true
              },
       "sysparam_offset": 0,
       "sysparam_limit": 10 
  }
}'

    응답 본문.

    {
  "result": {
    "result": [
      {
        "displayValue": "Conference Room A - Floor 1",
        "value": "space_123",
        "table": "sn_wsd_core_space",
        "label": "Floor 1, Building A, Main Campus",
        "selectedTreeBranch": "building_456",
        "timezone": {
          "value": "America/New_York",
          "displayValue": "Eastern Standard Time"
        },
        "wsdSource": "",
        "externalId": "",
        "floorId": "floor_789",
        "isReservable": true
      },
      {
        "displayValue": "Jane Doe",
        "value": "user_789",
        "table": "sys_user",
        "label": "Senior Engineer, Engineering",
        "selectedTreeBranch": "building_456",
        "userDetails": {
          "userID": "user_789",
          "name": "Jane Doe",
          "department": "Engineering",
          "avatar": "/avatar/user_789",
          "initials": "JD"
        }
      }
    ],
    "more": true,
    "isMobile": false
  }
}

    cURL 요청

    다음은 다른 검색 기준의 예입니다.

    모든 위치 및 사용자 검색:

    { 
  "search_term": "engineering", 
  "filterConfig": {}, 
  "sysparm_offset": 0, 
  "sysparm_limit": 20
}

    예약 가능한 공간만 검색:

    {
  "search_term": "workspace",
  "filterConfig": {
    "sn_wsd_core_workplace_location": "is_reservable=true^sys_class_name=sn_wsd_core_space"
  },
  "sysparm_offset": 0,
  "sysparm_limit": 10
}

    IT 부서의 활성 사용자만 검색:

    {
  "search_term": "smith",
  "include_user_email": true,
  "filterConfig": {
    "sys_user": "department.name=IT Department"
  },
  "sysparm_offset": 0,
  "sysparm_limit": 10
}

    접근이 제한된 인접 검색 확인:

    {
  "search_term": "team",
  "filterConfig": {
    "sn_wsd_core_neighborhood": ""
  },
  "options": {
    "sn_wsd_core_neighborhood": {
      "validateAccess": true
    },
    "rsvModule": {
      "value": "module_sys_id_here"
    }
  },
  "sysparm_offset": 0,
  "sysparm_limit": 10
}

    WSD 통합 검색 - GET /api/sn_wsd_core/wsd_unified_search/current_location

    활성 예약, 직장 프로파일 또는 인접 지역 할당에 따라 특정 사용자의 현재 위치를 검색합니다. 가장 관련성이 높은 공용 위치를 먼저 반환하고, 공용 위치를 찾을 수 없으면 비공개 위치로 대체합니다.

    URL 형식

    버전이 지정된 URL: /api/sn_wsd_core/{api_version}/wsd_unified_search/current_location

    기본 URL: /api/sn_wsd_core/wsd_unified_search/current_location

    지원되는 요청 매개변수

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

    데이터 유형: 문자열
    표 8. 쿼리 매개변수
    이름 설명
    userSysId 필수 현재 위치를 검색할 사용자의 Sys_id입니다.

    테이블: 사용자 [sys_user]

    데이터 유형: 문자열
    사용 인접 예약 또는 직접 프로파일 위치를 찾을 수 없는 경우 사용자의 직장 프로파일에서 인접 기반 위치를 포함할지 여부를 나타내는 플래그입니다.
    유효한 값은 다음과 같습니다.
    • true: 대체로 인접 기반 위치를 포함합니다.
    • false: 인접 기반 위치를 포함하지 않습니다.

    데이터 유형: 부울

    기본값: false
    표 9. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    안 함

    헤더

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

    표 10. 요청 헤더
    머리글 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    권한 부여 인증 자격 증명입니다. 기본 인증 또는 세션 기반 인증을 지원합니다.
    표 11. 응답 헤더
    머리글 설명
    콘텐츠-형식 응답 본문의 데이터 형식: application/json.

    상태 코드

    이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

    표 12. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    400잘못된 요청입니다. userSysId 매개변수가 누락되었거나 잘못되었습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다.

    응답 본문 매개변수(JSON 또는 XML)

    현재 위치를 찾으면 단일 위치 객체를 반환하고, 위치를 찾을 수 없으면 빈 객체 {}를 반환합니다.
    이름 설명
    isPrivate 반환된 위치가 비공개인지 여부를 나타내는 플래그입니다. 위치가 직장 프로필에서 비공개로 표시되어 있거나 비공개 또는 민감한 상태의 예약과 연결된 경우 비공개로 간주됩니다.
    유효한 값은 다음과 같습니다.
    • true: 위치가 비공개이거나 예약이 비공개/중요 상태입니다.
    • false: 위치가 공개입니다.

    데이터 유형: 부울
    displayValue 결과 위치의 표시 이름입니다. 예를 들어, 건물 A - 2층 - 작업 공간 201입니다.

    데이터 유형: 문자열
    값 결과 위치 기록의 Sys_id입니다.

    데이터 유형: 문자열.

    최대 길이: 32
    테이블 위치가 시작된 ServiceNow 테이블의 이름 예를 들면 sn_wsd_core_space입니다.

    데이터 유형: 문자열
    레이블 위치 계층 구조 컨텍스트를 제공하는 보조 표시 문자열입니다. 예를 들어 2 층, 건물 A입니다.

    데이터 유형: 문자열
    selectedTreeBranch 직장 계층 구조의 상위 위치 기록 Sys_id입니다. UI에서 위치 트리를 미리 선택하는 데 사용됩니다.

    데이터 유형: 문자열
    시간대 결과 위치와 연결된 시간대입니다.

    데이터 유형: 객체

    "timezone": {
  "value": "String",
  "displayValue": "String"
}
    시간대.값 결과 위치의 IANA 시간대 식별자입니다. 예: 아메리카/New_York.

    데이터 유형: 문자열
    timezone.displayValue 사람이 읽을 수 있는 시간대 이름입니다. 예: 미국/동부.

    데이터 유형: 문자열
    wsd소스 위치의 소스 시스템 식별자입니다. 위치가 외부 통합에서 시작된 경우 사용됩니다.

    데이터 유형: 문자열
    externalId 해당되는 경우 외부 소스 시스템의 위치 기록 식별자입니다.

    데이터 유형: 문자열
    floorId 위치가 있는 층의 Sys_id입니다.

    테이블: 직장 층 [sn_wsd_core_floor] 테이블

    데이터 유형: 문자열
    isReserved 가능 위치를 예약할 수 있는지 여부를 나타내는 플래그입니다.
    가능한 값:
    • true: 위치를 예약할 수 있습니다.
    • false: 위치를 예약할 수 없습니다.

    데이터 유형: 부울
    isPrivate 반환된 위치가 비공개인지 여부를 나타내는 플래그입니다.

    위치가 직장 프로파일에서 비공개로 표시되어 있거나 비공개 또는 민감한 상태의 예약과 연결된 경우 비공개로 간주됩니다.

    가능한 값:
    • true: 위치가 비공개입니다.
    • false: 위치가 공개입니다.

    데이터 유형: 부울

    cURL 요청

    다음 예에서는 대체로 인접 기반 위치를 포함하여 특정 사용자의 현재 위치를 검색합니다.

    curl "https://<instance>.service-now.com/api/sn_wsd_core/wsd_unified_search/current_location
  ?userSysId=abc123def456&useNeighborhoods=true" \
  --request GET \
  --header "Accept: application/json" \
  --user "username:password"

    위치가 발견되면 응답 본문입니다.

    {
  "result": {
    "displayValue": "Building A - Floor 2 - Workspace 201",
    "value": "abc123def456",
    "table": "sn_wsd_core_space",
    "label": "Floor 2, Building A",
    "selectedTreeBranch": "building789xyz",
    "timezone": {
      "value": "America/New_York",
      "displayValue": "US/Eastern"
    },
    "wsdSource": "manual",
    "externalId": "EXT-WS-201",
    "floorId": "floor123",
    "isReservable": true,
    "isPrivate": false
  }
}

    위치를 찾을 수 없는 경우의 응답 본문입니다(빈 객체 {}).

    {
  "result": {}
}