WSD 統一検索 API

  • リリースバージョン: Australia
  • 更新日 2026年04月28日
  • 所要時間：21分

    • WSD 統一検索 API は、職場のユーザーと場所を検索するためのエンドポイントを提供します。

    WSD 統一検索 API は sn_wsd_core 名前空間で実行され、ワークプレイスサービスデリバリ (WSD) ポータルでの検索/先行入力エクスペリエンスを強化し、一致するユーザー、スペース、フロア、建物、敷地、および近隣を単一の応答で返します。

    要件

    WSD 統一検索 API には次のものが必要です。
    • 呼び出し元ユーザーには sn_wsd_core.workplace_user ロールがあります。
    • ワークプレイスサービスデリバリ Core (com.sn_wsd_core) プラグインがアクティブである。
    • 少なくとも 1 つの建物とフロアが職場の場所階層で構成されている必要があります。

    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 一致するユーザーと職場の場所を検索するために使用される検索クエリ。複数の用語を同時に検索するための値のカンマ区切りリストを受け入れます。たとえば 、「Conference, Desk」の場合、 いずれかの用語に一致する結果が返されます。空のセグメントは無視されます。

    データタイプ：文字列

    デフォルト値:空の文字列 (すべての結果を返します)
    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:親場所の結果を含めません。

    データタイプ：ブーリアン
    options.cache キャッシュされた検索結果を使用するかどうかを示すフラグ。
    可能な値：
    • true:キャッシュされた結果が利用可能な場合は使用します。
    • false:常に新しい結果をフェッチします

    データタイプ：ブーリアン
    options.rsvModule 予約可能モジュールコンテキストで結果をフィルタリングするための予約モジュール構成を含むオブジェクト。

    データタイプ: オブジェクト

    "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。
    Content-Type 要求本文のデータ形式:application/json。
    認証 認証情報。ベーシック認証またはセッションベースの認証をサポートします。
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    Content-Type 応答本文のデータ形式:application/json。

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。要求本文の形式が無効です。
    401 認証に失敗しました。
    403 必要な ACL 権限がユーザーにありません。
    500 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    result 要求の結果を含むオブジェクト。

    データタイプ: オブジェクト

    "result": {
  "result": [Array],
  "more": Boolean,
  "isMobile": Boolean
}
    result.isMobile 要求がモバイルクライアントからのものとして検出されたかどうかを示すフラグ。
    可能な値：
    • true:要求はモバイルクライアントから発信されました。
    • false:要求はデスクトップクライアントから発信されました。

    データタイプ：ブーリアン
    result.more 現在のページ以外に追加の結果があるかどうかを示すフラグ。
    可能な値：
    • true:より多くの結果が利用可能です。次のページを取得するには、sysparam_limitでsysparam_offsetをインクリメントします。
    • false:これ以上結果は使用できません。

    データタイプ：ブーリアン
    result.result 一致するユーザーオブジェクトと場所オブジェクトのアレイ。各オブジェクトには、すべての結果タイプで共有される共通フィールドと、ユーザーの結果にのみ存在するタイプ固有のフィールドが含まれています。

    データタイプ：オブジェクトのアレイ

    "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.isReservable 結果の場所を予約できるかどうかを示すフラグ。
    可能な値：
    • true:場所は予約可能です。
    • false:場所は予約できません。

    データタイプ：ブーリアン
    result.result.label 結果の追加コンテキストを提供するセカンダリ表示文字列。たとえば、スペースの場所階層や、ユーザーの部門と役職などです。

    データタイプ：文字列
    result.result.selectedTreeBranch この結果に関連付けられている職場階層内の親の場所レコードのSys_id。UI で場所ツリーを事前に選択するために使用されます。

    データタイプ：文字列
    result.result.table 結果の発生元のテーブル名。たとえば、 sn_wsd_core_space や sys_user などです。

    データタイプ：文字列
    result.result.timezone 結果の場所に関連付けられたタイムゾーン。場所の結果に存在します。

    データタイプ: オブジェクト

    "timezone": {
  "displayValue": "String",
  "value": "String"
}
    result.result.timezone.displayValue 分かりやすいタイムゾーン名。たとえば、 東部標準時などです。

    データタイプ：文字列
    result.result.timezone.value 結果の場所の 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]

    データタイプ:文字列。
    result.result.value 結果レコードの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]

    データタイプ：文字列
    useNeighborhoods 予約または直接プロファイルの場所が見つからない場合に、ユーザーのワークプレイスプロファイルから近隣ベースの場所を含めるかどうかを示すフラグ。
    有効な値：
    • true:フォールバックとして近隣ベースの場所を含めます。
    • false:近隣ベースの場所を含めません。

    データタイプ：ブーリアン

    デフォルト値：false
    表 : 9. 要求本文パラメーター (XML または JSON)
    名前 説明
    なし

    ヘッダー

    次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 10. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    認証 認証情報。ベーシック認証またはセッションベースの認証をサポートします。
    表 : 11. 応答ヘッダー
    ヘッダー 説明
    Content-Type 応答本文のデータ形式:application/json。

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 12. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400要求が正しくありません。userSysId パラメーターがないか、無効です。
    500 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。

    応答本文のパラメーター (JSON または XML)

    現在の場所が見つかった場合は単一の場所オブジェクトを返し、場所が見つからない場合は空のオブジェクト {} を返します。
    名前 説明
    isPrivate 返された場所がプライベートであるかどうかを示すフラグ。場所は、ワークプレイスプロファイルでプライベートとしてマークされている場合、またはプライベートまたは機密ステータスの予約に関連付けられている場合、プライベートと見なされます。
    有効な値：
    • true:場所がプライベートであるか、予約のステータスがプライベート/機密です。
    • false:場所は公開されています。

    データタイプ：ブーリアン
    displayValue 結果の場所の表示名。たとえば、 建物 A - フロア 2 - ワークスペース 201 などです。

    データタイプ：文字列
    value 結果の場所レコードのSys_id。

    データタイプ:文字列。

    最大長:32
    table 場所の発生元の ServiceNow テーブルの名前 たとえば、「 sn_wsd_core_space」などです。

    データタイプ：文字列
    label 場所階層コンテキストを提供するセカンダリ表示文字列。たとえば 、建物 A の 2 階などです。

    データタイプ：文字列
    selectedTreeBranch 職場階層内の親の場所レコードのSys_id。UI で場所ツリーを事前に選択するために使用されます。

    データタイプ：文字列
    タイムゾーン 結果の場所に関連付けられたタイムゾーン。

    データタイプ: オブジェクト

    "timezone": {
  "value": "String",
  "displayValue": "String"
}
    timezone.value 結果の場所の IANA タイムゾーン識別子。たとえば、 アメリカ/New_Yorkなどです。

    データタイプ：文字列
    timezone.displayValue 分かりやすいタイムゾーン名。たとえば、 米国/東部です。

    データタイプ：文字列
    wsd ソース 場所のソースシステム識別子。場所が外部統合から取得される場合に使用されます。

    データタイプ：文字列
    externalId 外部ソースシステム内の場所レコードの識別子 (該当する場合)。

    データタイプ：文字列
    floorId 場所が存在するフロアのSys_id。

    テーブル:職場フロア [sn_wsd_core_floor] テーブル

    データタイプ：文字列
    予約可能 場所を予約できるかどうかを示すフラグ。
    可能な値：
    • 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": {}
}