API de pesquisa unificada do WSD

  • Versão de lançamento: Australia
  • Atualizado 28 de abr. de 2026
  • 13 min. de leitura

    • . Pesquisa unificada do WSD A API fornece um endpoint para pesquisar usuários e locais do local de trabalho.

    . Pesquisa unificada do WSD A API é executada no namespace sn_wsd_core e alimenta a experiência de pesquisa/digitação antecipada no Prestação de serviços no local de trabalho(WSD) portal, retornando usuários correspondentes, espaços, andares, prédios, e bairros em uma única resposta.

    Requisitos

    . Pesquisa unificada do WSD A API requer:
    • O usuário chamador tem a função sn_wsd_core.workplace_user.
    • . Prestação de serviços no local de trabalho O plug-in Core (com.sn_wsd_core) esteja ativo.
    • Pelo menos um prédio e andar devem ser configurados na hierarquia de local do local de trabalho.

    Pesquisa unificada do WSD - POST /api/sn_wsd_core/wsd_unified_search/users_and_locations

    Pesquisa usuários e locais de local de trabalho (sem distinção entre maiúsculas e minúsculas) correspondentes ao termo de pesquisa fornecido. Retorna uma lista combinada de resultados correspondentes com suporte a paginação.

    Formato de URL

    URL com controle de versão: /api/sn_wsd_core//wsd_unified_search/users_and_locations

    URL padrão: /api/sn_wsd_core/wsd_unified_search/users_and_locations

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint para acessar. Por exemplo, v1 ou v2 . Especifique este valor somente para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: Cadeia de caracteres
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 3. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    search_term Consulta de pesquisa usada para encontrar usuários correspondentes e locais de local de trabalho. Aceita uma lista separada por vírgulas de valores para pesquisar vários termos simultaneamente. Por exemplo, "Conferência, mesa" retorna resultados que correspondem a qualquer termo. Segmentos vazios são ignorados.

    Tipo de dados: Cadeia de caracteres

    Valor padrão: Cadeia de caracteres vazia (retorna todos os resultados)
    show_location Sinalizador que indica se o local atual do usuário deve ser incluído no rótulo do resultado.
    Valores possíveis:
    • verdadeiro : Exibe o local atual do usuário no rótulo do resultado.
    • falso : Não exiba o local atual do usuário no rótulo do resultado.

    Tipo de dados: Booliano

    Padrão: verdadeiro
    mostrar_loggedin_user Sinalizador que indica se o usuário autenticado deve ser exibido como o primeiro resultado quando nenhum termo de pesquisa é fornecido. Aplica-se somente a clientes de desktop no deslocamento 0.
    Valores possíveis:
    • verdadeiro : Mostrar o usuário autenticado como o primeiro resultado.
    • falso : Não mostrar o usuário autenticado como o primeiro resultado.

    Tipo de dados: Booliano

    Padrão: verdadeiro
    include_user_email Sinalizador que indica se os endereços de e-mail do usuário devem ser incluídos nos rótulos de resultados e permitir a pesquisa por endereço de e-mail.
    Valores possíveis:
    • verdadeiro : Incluir e-mail nos rótulos de resultados e habilitar a pesquisa de e-mail.
    • falso : Não inclua e-mail nos rótulos de resultados nem habilite a pesquisa de e-mail

    Tipo de dados: Booliano

    Padrão: falso
    filterConfig Consultas codificadas específicas da tabela. As chaves são nomes de tabela. Os valores são cadeias de caracteres de consulta codificadas.
    Campos válidos (nomes de tabela):
    • 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_vizinhança

    Tipo de dados: Objeto

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

    (Nenhum filtro aplicado, pesquisa todas as tabelas)
    FilterConfig.<table_name> Sinalizador que indica se os resultados da tabela especificada devem ser incluídos. Defina como verdadeiro para incluir resultados desse tipo de entidade.
    Valores válidos:
    • verdadeiro : Incluir resultados desse tipo de entidade.
    • falso : Não inclua resultados desse tipo de entidade.

    Tipo de dados: Booliano
    opções Objeto que contém configuração adicional para comportamento de pesquisa.

    Tipo de dados: Objeto

    "options": { 
  "search_in_parent": Boolean,
  "cache": Boolean,
  "rsvModule": {Object}
}
    options.search_in_parent Sinalizador que indica se os resultados dos registros de local primários devem ser incluídos ao filtrar por uma entidade secundária.
    Valores possíveis:
    • verdadeiro : Incluir resultados do local primário.
    • falso : Não incluir resultados de local primário.

    Tipo de dados: Booliano
    options.cache Sinalizador que indica se os resultados de pesquisa em cache devem ser usados.
    Valores possíveis:
    • verdadeiro : Use resultados em cache quando disponíveis.
    • falso : Sempre buscar resultados novos

    Tipo de dados: Booliano
    Options.rsvModule Objeto que contém a configuração do módulo de reserva para filtrar resultados por contexto do módulo reservável.

    Tipo de dados: Objeto

    "rsvModule": { 
  "value": "String"
}
    Valor.rsvModule.Value Sys_id do módulo reservável a ser usado para filtrar espaços disponíveis.

    Tabela: Módulo reservável [sn_wsd_rsv_reservable_module]

    Tipo de dados: Cadeia de caracteres
    Options.rsvModule.enable_restricted_neighbourship_rules Sinalizador que indica se regras de vizinhança restritas devem ser aplicadas ao filtrar resultados por módulo de reserva.
    Valores possíveis:
    • verdadeiro : Aplique regras de vizinhança restritas.
    • falso : Não aplique regras de vizinhança restritas.

    Tipo de dados: Booliano
    syspram_offset Deslocamento de paginação. Número de registros a serem ignorados antes de retornar resultados. Use com sysparam_limitpara paginação.

    Valor mínimo : 0

    Tipo de dados: Número

    Valor padrão: 0
    sysparam_limit Número máximo de registros a serem retornados por solicitação. Use com sysparam_offsetpara paginação.

    Valor mínimo: 1

    Tipo de dados: Número

    Valor padrão: 10
    Nota:
    Todas as pesquisas não diferenciam maiúsculas de minúsculas.

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos da REST API compatíveis .

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: Application/json, application/xml, text/xml.
    Tipo de conteúdo Formato de dados do corpo da solicitação: Aplicação/json.
    Autorização Credenciais de autenticação. Compatível com autenticação básica ou autenticação baseada em sessão.
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Tipo de conteúdo Formato de dados do corpo da resposta: Aplicação/json.

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte REST API códigos de resposta HTTP .

    Tabela 6. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Formato de corpo da solicitação inválido.
    401 Falha de autenticação.
    403 O usuário não tem permissões de ACL necessárias.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    resultado Objeto que contém resultados da solicitação.

    Tipo de dados: Objeto

    "result": {
  "result": [Array],
  "more": Boolean,
  "isMobile": Boolean
}
    Resultado.éMóvel Sinalizador que indica se a solicitação foi detectada como originada de um cliente móvel.
    Valores possíveis:
    • verdadeiro : Solicitação originada de um cliente móvel.
    • falso : Solicitação originada de um cliente de desktop.

    Tipo de dados: Booliano
    resultado.mais Sinalizador que indica se resultados adicionais estão disponíveis além da página atual.
    Valores possíveis:
    • verdadeiro : Mais resultados estão disponíveis. Incremento sysparam_offsetpor sysparam_limitpara recuperar a próxima página.
    • falso : Não há mais resultados disponíveis.

    Tipo de dados: Booliano
    resultado.resultado Matriz de objetos de usuário e local correspondentes. Cada objeto contém campos comuns compartilhados entre todos os tipos de resultado, bem como campos específicos do tipo que estão presentes somente para resultados do usuário.

    Tipo de dados: Matriz de objetos

    "result": [
  {
    "displayValue": "String",
    "value": "String",
    "table": "String",
    "label": "String",
    "selectedTreeBranch": "String",
    "timezone": {Object},
    "wsdSource": "String",
    "externalId": "String",
    "floorId": "String",
    "isReservable": Boolean
  }
]
    Result.result.displayValue Nome de exibição do resultado. Por exemplo, Sala de conferências A - Piso 1 para um espaço ou Jane Doe para um usuário.

    Tipo de dados: Cadeia de caracteres
    Result.result.externalId Identificador do registro de resultado em um sistema de origem externo, quando aplicável.

    Tipo de dados: Cadeia de caracteres
    Result.result.floorId SYS_id do andar no qual o local do resultado reside. Presente somente para resultados de local.

    Tabela: Piso do local de trabalho [sn_wsd_core_floor]

    Tipo de dados: Cadeia de caracteres
    Result.result.isReservado Sinalizador que indica se o local do resultado pode ser reservado.
    Valores possíveis:
    • verdadeiro : O local é reservável.
    • falso : O local não é reservável.

    Tipo de dados: Booliano
    resultado.resultado.rótulo Cadeia de caracteres de exibição secundária que fornece contexto adicional para o resultado. Por exemplo, a hierarquia de local de um espaço ou o departamento e o título de um usuário.

    Tipo de dados: Cadeia de caracteres
    result.result.selectedTreeBranch Sys_id do registro de local primário na hierarquia do local de trabalho associado a este resultado. Usado para pré-selecionar a árvore de local na IU.

    Tipo de dados: Cadeia de caracteres
    resultado.resultado.tabela Nome da tabela da qual o resultado se origina. Por exemplo, sn_wsd_core_space ou sys_user .

    Tipo de dados: Cadeia de caracteres
    result.result.timezone Fuso horário associado ao local do resultado. Apresentar para resultados do local.

    Tipo de dados: Objeto

    "timezone": {
  "displayValue": "String",
  "value": "String"
}
    Result.result.timezone.displayValue Nome do fuso horário legível. Por exemplo, Horário padrão do leste .

    Tipo de dados: Cadeia de caracteres
    result.result.timezone.value Identificador de fuso horário IANA para o local do resultado. Por exemplo, América/Nova_Iorque.

    Tipo de dados: Cadeia de caracteres
    result.result.userDetails Objeto que contém detalhes adicionais sobre um resultado de usuário. Presente somente para resultados do usuário (tabela Usuário [sys_user]).

    Tipo de dados: Objeto

    "userDetails": {
  "userID": "String",
  "name": "String",
  "department": "String",
  "avatar": "String",
  "initials": "String"
}
    result.result.userDetails.avatar Caminho de URL relativo para a imagem do avatar do perfil do usuário.

    Tipo de dados: Cadeia de caracteres
    result.result.userDetails.department Nome do departamento ao qual o usuário pertence.

    Tipo de dados: Cadeia de caracteres
    result.result.userDetails.initials Iniciais derivadas do nome de exibição do usuário, usadas como fallback quando não há avatar disponível. Por exemplo, JD para Jane Doe .

    Tipo de dados: Cadeia de caracteres
    result.result.userDetails.name Nome de exibição completo do usuário. Por exemplo, Jane Doe .

    Tipo de dados: Cadeia de caracteres
    result.result.userDetails.userID Sys_id do registro do usuário.

    Tabela: Usuário [sys_user]

    Tipo de dados: Cadeia de caracteres.
    resultado.resultado.valor Sys_id do registro de resultado.

    Tipo de dados: Cadeia de caracteres
    Result.Result.wsdSource Identificador do sistema de origem do resultado. Usado quando o local se origina de uma integração externa.

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    O exemplo a seguir pesquisa espaços correspondentes a "Conferência" ou "Mesa" em um prédio específico, retornando até 10 resultados.

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

    Corpo da resposta.

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

    Solicitação de curl

    A seguir estão exemplos de diferentes critérios de pesquisa.

    Pesquisar todos os locais e usuários:

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

    Pesquisar somente espaços reserváveis:

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

    Pesquisar somente usuários ativos no departamento DE TI:

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

    Pesquisar bairros com validação de acesso restrito:

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

    Pesquisa unificada do WSD - OBTENHA /api/sn_wsd_core/wsd_unified_search/current_location

    Recupere o local atual de um usuário específico com base em suas reservas ativas, perfil do local de trabalho ou atribuição de bairro. Retorna o local público mais relevante primeiro, retornando para locais privados se nenhum local público for encontrado.

    Formato de URL

    URL com controle de versão: /api/sn_wsd_core//wsd_unified_search/current_location

    URL padrão: /api/sn_wsd_core/wsd_unified_search/current_location

    Parâmetros de solicitação compatíveis

    Tabela 7. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint para acessar. Por exemplo, v1 ou v2 . Especifique este valor somente para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: Cadeia de caracteres
    Tabela 8. Parâmetros de consulta
    Nome Descrição
    userSysId Necessário. Sys_id do usuário cujo local atual será recuperado.

    Tabela: Usuário [sys_user]

    Tipo de dados: Cadeia de caracteres
    UseNeirâncias Sinalizador que indica se um local baseado no bairro do perfil do local de trabalho do usuário deve ser incluído quando nenhuma reserva ou local de perfil direto for encontrado.
    Valores válidos:
    • Verdadeiro: Inclua o local baseado no bairro como um fallback.
    • Falso: Não inclua o local baseado no bairro.

    Tipo de dados: Booliano

    Padrão: falso
    Tabela 9. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    Nenhum(a)

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos da REST API compatíveis .

    Tabela 10. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Autorização Credenciais de autenticação. Compatível com autenticação básica ou autenticação baseada em sessão.
    Tabela 11. Cabeçalhos de resposta
    Cabeçalho Descrição
    Tipo de conteúdo Formato de dados do corpo da resposta: Aplicação/json.

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte REST API códigos de resposta HTTP .

    Tabela 12. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400Solicitação Incorreta. O parâmetro userSysId está ausente ou é inválido.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação.

    Parâmetros do corpo da resposta (JSON ou XML)

    Retorna um único objeto de local quando um local atual é encontrado ou um objeto vazio quando nenhum local é encontrado.
    Nome Descrição
    ÉPrivado Sinalizador que indica se o local retornado é privado. Um local é considerado privado quando marcado como privado no perfil do local de trabalho ou quando associado a uma reserva com status privado ou confidencial.
    Valores válidos:
    • Verdadeiro: O local é privado ou a reserva tem status privado/confidencial.
    • Falso: O local é público.

    Tipo de dados: Booliano
    displayValue Nome de exibição do local do resultado. Por exemplo, Edifício A - Piso 2 - Espaço 201 .

    Tipo de dados: Cadeia de caracteres
    valor Sys_id do registro do local do resultado.

    Tipo de dados: Cadeia de caracteres.

    Comprimento máximo: 32
    tabela Nome da tabela ServiceNow da qual o local se origina, por exemplo, sn_wsd_core_space .

    Tipo de dados: Cadeia de caracteres
    rótulo Cadeia de caracteres de exibição secundária que fornece contexto de hierarquia de local. Por exemplo, Piso 2, Edifício A. .

    Tipo de dados: Cadeia de caracteres
    TreeBranch selecionado Sys_id do registro de local primário na hierarquia do local de trabalho. Usado para pré-selecionar a árvore de local na IU.

    Tipo de dados: Cadeia de caracteres
    Fuso horário Fuso horário associado ao local do resultado.

    Tipo de dados: Objeto

    "timezone": {
  "value": "String",
  "displayValue": "String"
}
    valor.fuso.valor Identificador de fuso horário IANA para o local do resultado. Por exemplo, América/Nova_Iorque .

    Tipo de dados: Cadeia de caracteres
    Timezone.displayValue Nome do fuso horário legível. Por exemplo, Leste/EUA .

    Tipo de dados: Cadeia de caracteres
    WsdSource Identificador do sistema de origem do local. Usado quando o local se origina de uma integração externa.

    Tipo de dados: Cadeia de caracteres
    externalId Identificador do registro de local em um sistema de origem externo, quando aplicável.

    Tipo de dados: Cadeia de caracteres
    floorId SYS_id do andar no qual o local reside.

    Tabela: Piso do local de trabalho [sn_wsd_core_floor] tabela

    Tipo de dados: Cadeia de caracteres
    IsReservável Sinalizador que indica se o local pode ser reservado.
    Valores possíveis:
    • Verdadeiro: O local é reservável.
    • Falso: O local não é reservável.

    Tipo de dados: Booliano
    ÉPrivado Sinalizador que indica se o local retornado é privado.

    Um local é considerado privado quando é marcado como privado no perfil do local de trabalho ou quando está associado a uma reserva com status privado ou confidencial.

    Valores possíveis:
    • Verdadeiro: O local é privado.
    • Falso: O local é público.

    Tipo de dados: Booliano

    Solicitação de curl

    O exemplo a seguir recupera o local atual de um usuário específico, incluindo o local baseado no bairro como um fallback.

    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"

    Responda quando o local for encontrado.

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

    Corpo da resposta quando o local não é encontrado (objeto vazio).

    {
  "result": {}
}