API de recherche unifiée WSD

  • Rversion finale: Australia
  • Mis à jour 28 avr. 2026
  • 13 minutes de lecture

    • L’API Recherche unifiée WSD fournit un point de terminaison pour effectuer des recherches sur les utilisateurs et les emplacements du lieu de travail.

    L’API Recherche unifiée WSD s’exécute dans l’espace de noms sn_wsd_core et alimente l’expérience de recherche/saisie automatique dans le portail (WSD), renvoyant les utilisateurs, les espaces, les étages, les bâtiments, les Prestation de services de lieu de travail campus et les quartiers correspondants dans une réponse unique.

    Besoins

    L’API Recherche unifiée WSD nécessite :
    • L’utilisateur appelant a le rôle sn_wsd_core.workplace_user.
    • Le Prestation de services de lieu de travail module d’extension Core (com.sn_wsd_core) doit être actif.
    • Au moins un bâtiment et un étage doivent être configurés dans la hiérarchie des emplacements du lieu de travail.

    Recherche unifiée WSD : POST /api/sn_wsd_core/wsd_unified_search/users_and_locations

    Recherche des utilisateurs et des emplacements de lieux de travail (sans respect de la casse) correspondant au terme de recherche fourni. Renvoie une liste combinée des résultats correspondants avec prise en charge de la pagination.

    Format d'URL

    URL avec version : /api/sn_wsd_core/{api_version}/wsd_unified_search/users_and_locations

    URL par défaut : /api/sn_wsd_core/wsd_unified_search/users_and_locations

    Paramètres de demande pris en charge

    Tableau 1. Paramètres de chemin d'accès
    Nom Description
    api_version Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison autre que la plus récente.

    Type de données : chaîne
    Tableau 2. Paramètres de requête
    Nom Description
    Néant
    Tableau 3. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    search_term Requête de recherche utilisée pour trouver des utilisateurs et des emplacements de lieu de travail correspondants. Accepte une liste de valeurs séparées par des virgules pour rechercher plusieurs termes simultanément. Par exemple, « Conférence, bureau » renvoie les résultats correspondant à l’un ou l’autre terme. Les segments vides sont ignorés.

    Type de données : chaîne

    Valeur par défaut : chaîne vide (renvoie tous les résultats)
    show_location Marqueur indiquant s’il faut inclure l’emplacement actuel de l’utilisateur dans l’étiquette de résultat.
    Valeurs possibles :
    • vrai : affiche l’emplacement actuel de l’utilisateur dans l’étiquette de résultat.
    • faux : n’affiche pas l’emplacement actuel de l’utilisateur dans l’étiquette de résultat.

    Type de données : booléennes

    Par défaut : true
    show_loggedin_user Marqueur indiquant s’il faut afficher l’utilisateur authentifié comme premier résultat lorsqu’aucun terme de recherche n’est fourni. S’applique uniquement aux clients de bureau avec un décalage de 0.
    Valeurs possibles :
    • vrai : afficher l’utilisateur authentifié comme premier résultat.
    • faux : ne pas afficher l’utilisateur authentifié comme premier résultat.

    Type de données : booléennes

    Par défaut : true
    include_user_email Marqueur indiquant s’il faut inclure les adresses e-mail des utilisateurs dans les étiquettes de résultats et autoriser la recherche par adresse e-mail.
    Valeurs possibles :
    • vrai : inclure l’e-mail dans les étiquettes de résultats et activer la recherche d’e-mails.
    • faux : n’incluez pas les e-mails dans les étiquettes de résultats et n’activez pas la recherche d’e-mails

    Type de données : booléennes

    Valeur par défaut : false
    filterConfig Requêtes codées spécifiques à une table. Les clés sont des noms de tables. Les valeurs sont des chaînes de requête codées.
    Champs valides (noms de tables) :
    • 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

    Type de données : objet

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

    Valeur par défaut : {} (aucun filtre appliqué, recherche toutes les tables)
    filterConfig.<table_name> Marqueur indiquant s’il faut inclure les résultats de la table spécifiée. Définissez la valeur sur vrai pour inclure les résultats de ce type d’entité.
    Valeurs valides :
    • vrai : inclure les résultats de ce type d’entité.
    • faux : n’incluez pas les résultats de ce type d’entité.

    Type de données : booléennes
    options Objet contenant une configuration supplémentaire pour le comportement de recherche.

    Type de données : objet

    "options": { 
  "search_in_parent": Boolean,
  "cache": Boolean,
  "rsvModule": {Object}
}
    options.search_in_parent Marqueur indiquant s’il faut inclure les résultats des enregistrements d’emplacement parent lors du filtrage par une entité enfant.
    Valeurs possibles :
    • vrai : inclure les résultats de l’emplacement parent.
    • faux : n’incluez pas les résultats d’emplacement parent.

    Type de données : booléennes
    options.cache Marqueur indiquant s’il faut utiliser les résultats de recherche mis en cache.
    Valeurs possibles :
    • vrai : utiliser les résultats mis en cache lorsqu’ils sont disponibles.
    • faux : toujours extraire des résultats actualisés

    Type de données : booléennes
    option.rsvModule Objet contenant la configuration du module de réservation pour filtrer les résultats par contexte de module réservable.

    Type de données : objet

    "rsvModule": { 
  "value": "String"
}
    options.rsvModule.valeur Sys_id du module réservable à utiliser pour filtrer les espaces disponibles.

    Table : module réservable [sn_wsd_rsv_reservable_module]

    Type de données : chaîne
    options.rsvModule.enable_restricted_neighborhood_rules Marqueur indiquant s’il faut appliquer des règles de quartier restreint lors du filtrage des résultats par module de réservation.
    Valeurs possibles :
    • vrai : appliquer les règles de quartier restreint.
    • faux : N’appliquez pas de règles de voisinage restreintes.

    Type de données : booléennes
    sysparam_offset Décalage de pagination. Nombre d’enregistrements à ignorer avant de renvoyer les résultats. Utiliser avec sysparam_limit pour la pagination.

    Valeur minimale : 0

    Type de données : nombre

    Valeur par défaut : 0
    sysparam_limit Nombre maximal d’enregistrements à renvoyer par demande. Utiliser avec sysparam_offset pour la pagination.

    Valeur minimale : 1

    Type de données : nombre

    Valeur par défaut : 10
    Remarque :
    Toutes les recherches ne sont pas sensibles à la casse.

    En-têtes

    Les en-têtes de demande et de réponse suivants s’appliquent uniquement à cette action HTTP ou s’appliquent à cette action d’une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 4. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json, application/xml, texte/xml.
    Type de contenu Format des données du corps de la demande : application/json.
    Autorisation Informations d’identification d’authentification. Prend en charge l’authentification de base ou l’authentification basée sur la session.
    Tableau 5. En-têtes de réponses
    En-tête Description
    Type de contenu Format des données du corps de la réponse : application/json.

    Codes d'état

    Les codes d’état suivants s’appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 6. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été traitée avec succès.
    400 Demande incorrecte. Format de corps de demande non valide.
    401 Échec de l'authentification.
    403 L’utilisateur ne dispose pas des autorisations ACL requises.
    500 Erreur interne du serveur. Une erreur inattendue s’est produite lors du traitement de la demande.

    Paramètres du corps de la réponse (JSON ou XML)

    Nom Description
    résultat Objet contenant les résultats de la demande.

    Type de données : objet

    "result": {
  "result": [Array],
  "more": Boolean,
  "isMobile": Boolean
}
    résultat.isMobile Marqueur indiquant si la demande a été détectée comme provenant d’un client mobile.
    Valeurs possibles :
    • vrai : la demande provient d’un client mobile.
    • faux : la demande provient d’un client de bureau.

    Type de données : booléennes
    résultat.plus Marqueur indiquant si des résultats supplémentaires sont disponibles au-delà de la page actuelle.
    Valeurs possibles :
    • vrai : d’autres résultats sont disponibles. Incrémentez sysparam_offset par sysparam_limit pour récupérer la page suivante.
    • faux : aucun autre résultat n’est disponible.

    Type de données : booléennes
    résultat.résultat Tableau des objets utilisateur et emplacement correspondants. Chaque objet contient des champs communs partagés par tous les types de résultats, ainsi que des champs spécifiques au type qui ne sont présents que pour les résultats utilisateur.

    Type de données : tableau d’objets

    "result": [
  {
    "displayValue": "String",
    "value": "String",
    "table": "String",
    "label": "String",
    "selectedTreeBranch": "String",
    "timezone": {Object},
    "wsdSource": "String",
    "externalId": "String",
    "floorId": "String",
    "isReservable": Boolean
  }
]
    résultat.résultat.valeurd’affichage Nom d’affichage du résultat. Par exemple, Salle de conférence A - Étage 1 pour un espace ou Jane Doe pour un utilisateur.

    Type de données : chaîne
    résultat.résultat.identificateurexterne Identificateur de l’enregistrement du résultat dans un système source externe, le cas échéant.

    Type de données : chaîne
    résultat.résultat.floorId Sys_id de l’étage sur lequel se trouve l’emplacement des résultats. Présenter pour les résultats d’emplacement uniquement.

    Table : Étage du lieu de travail [sn_wsd_core_floor]

    Type de données : chaîne
    résultat.résultat.estréservable Marqueur indiquant si l’emplacement des résultats peut être réservé.
    Valeurs possibles :
    • vrai : l’emplacement est réservable.
    • faux : l’emplacement n’est pas réservable.

    Type de données : booléennes
    résultat.résultat.étiquette Chaîne d’affichage secondaire fournissant un contexte supplémentaire pour le résultat. Par exemple, la hiérarchie des emplacements d’un espace, ou le département et le titre d’un utilisateur.

    Type de données : chaîne
    résultat.résultat.selectedTreeBranch Sys_id de l’enregistrement de l’emplacement parent dans la hiérarchie du lieu de travail associée à ce résultat. Utilisé pour présélectionner l’arborescence d’emplacement dans l’interface utilisateur.

    Type de données : chaîne
    résultat.résultat.table Nom de la table d’où provient le résultat. Par exemple, sn_wsd_core_space ou sys_user.

    Type de données : chaîne
    Résultat.Résultat.Fuseau horaire Fuseau horaire associé à l’emplacement des résultats. Présenter pour les résultats de localisation.

    Type de données : objet

    "timezone": {
  "displayValue": "String",
  "value": "String"
}
    résultat.résultat.fuseau horaire.valeurd’affichage Nom du fuseau horaire explicite. Par exemple, heure normale de l’Est.

    Type de données : chaîne
    Résultat.Résultat.Fuseau horaire.Valeur Identificateur du fuseau horaire IANA pour l’emplacement des résultats. Par exemple, Amérique/New_York.

    Type de données : chaîne
    résultat.résultat.détailsutilisateur Objet contenant des détails supplémentaires sur un résultat utilisateur. Présent pour les résultats utilisateur uniquement (table Utilisateur [sys_user]).

    Type de données : objet

    "userDetails": {
  "userID": "String",
  "name": "String",
  "department": "String",
  "avatar": "String",
  "initials": "String"
}
    résultat.résultat.détailsutilisateur.avatar Chemin d’accès de l’URL relative à l’image d’avatar du profil de l’utilisateur.

    Type de données : chaîne
    résultat.résultat.détailsutilisateur.département Nom du département auquel l’utilisateur appartient.

    Type de données : chaîne
    résultat.résultat.détailsutilisateur.initiales Initiales dérivées du nom d’affichage de l’utilisateur, utilisées comme solution de secours lorsqu’aucun avatar n’est disponible. Par exemple, JD pour Jane Doe.

    Type de données : chaîne
    result.result.userDetails.name Nom d’affichage complet de l’utilisateur. Par exemple, Jane Doe.

    Type de données : chaîne
    result.result.userDetails.userID Sys_id de l’enregistrement utilisateur.

    Table : Utilisateur [sys_user]

    Type de données : chaîne.
    résultat.résultat.valeur Sys_id de l’enregistrement des résultats.

    Type de données : chaîne
    résultat.résultat.wsdSource Identificateur du système source pour le résultat. Utilisé lorsque l’emplacement provient d’une intégration externe.

    Type de données : chaîne

    Demande cURL

    L’exemple suivant recherche les espaces correspondant à « Conférence » ou « Bureau » dans un bâtiment spécifique, renvoyant jusqu’à 10 résultats.

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

    Corps de la réponse.

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

    Demande cURL

    Voici des exemples de critères de recherche différents.

    Rechercher tous les emplacements et les utilisateurs :

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

    Rechercher uniquement des espaces réservables :

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

    Rechercher uniquement les utilisateurs actifs dans le département IT :

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

    Rechercher des quartiers avec validation d’accès restreint :

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

    Recherche unifiée WSD : GET /api/sn_wsd_core/wsd_unified_search/current_location

    Récupérez l’emplacement actuel d’un utilisateur spécifique en fonction de ses réservations actives, de son profil de lieu de travail ou de son affectation de quartier. Renvoie d’abord l’emplacement public le plus pertinent et revient aux emplacements privés si aucun emplacement public n’est trouvé.

    Format d'URL

    URL versionnée : /api/sn_wsd_core/{api_version}/wsd_unified_search/current_location

    URL par défaut : /api/sn_wsd_core/wsd_unified_search/current_location

    Paramètres de demande pris en charge

    Tableau 7. Paramètres de chemin d'accès
    Nom Description
    api_version Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison autre que la plus récente.

    Type de données : chaîne
    Tableau 8. Paramètres de requête
    Nom Description
    userSysId Requis. Sys_id de l’utilisateur dont l’emplacement actuel doit être récupéré.

    Table : Utilisateur [sys_user]

    Type de données : chaîne
    useNeighborhoods Marqueur indiquant s’il faut inclure un emplacement basé sur le quartier à partir du profil du lieu de travail de l’utilisateur lorsqu’aucune réservation ou emplacement de profil direct n’est trouvée.
    Valeurs valides :
    • vrai : inclure l’emplacement basé sur le quartier comme solution de secours.
    • faux : n’incluez pas l’emplacement basé sur le quartier.

    Type de données : booléennes

    Valeur par défaut : false
    Tableau 9. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    Néant

    En-têtes

    Les en-têtes de demande et de réponse suivants s’appliquent uniquement à cette action HTTP ou s’appliquent à cette action d’une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 10. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Autorisation Informations d’identification d’authentification. Prend en charge l’authentification de base ou l’authentification basée sur la session.
    Tableau 11. En-têtes de réponses
    En-tête Description
    Type de contenu Format des données du corps de la réponse : application/json.

    Codes d'état

    Les codes d’état suivants s’appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 12. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été traitée avec succès.
    400Demande incorrecte. Le paramètre userSysId est manquant ou non valide.
    500 Erreur interne du serveur. Une erreur inattendue s’est produite lors du traitement de la demande.

    Paramètres du corps de la réponse (JSON ou XML)

    Renvoie un seul objet d’emplacement lorsqu’un emplacement actuel est trouvé ou un objet vide {} lorsqu’aucun emplacement n’est trouvé.
    Nom Description
    isPrivate Marqueur indiquant si l’emplacement renvoyé est privé. Un emplacement est considéré comme privé lorsqu’il est marqué comme privé dans le profil du lieu de travail ou lorsqu’il est associé à une réservation dont l’état est privé ou sensible.
    Valeurs valides :
    • vrai : l’emplacement est privé ou la réservation a un statut privé/sensible.
    • faux : l’emplacement est public.

    Type de données : booléennes
    displayValue Nom d’affichage de l’emplacement des résultats. Par exemple, Bâtiment A - Étage 2 - Espace de travail 201.

    Type de données : chaîne
    valide Sys_id de l’enregistrement de l’emplacement des résultats.

    Type de données : chaîne.

    Longueur maximale : 32
    Table Nom de la table ServiceNow d’où provient l’emplacement Par exemple, sn_wsd_core_space.

    Type de données : chaîne
    étiquette Chaîne d’affichage secondaire fournissant le contexte de hiérarchie des emplacements. Par exemple, Étage 2, Bâtiment A.

    Type de données : chaîne
    selectedTreeBranch Sys_id de l’enregistrement de l’emplacement parent dans la hiérarchie du lieu de travail. Utilisé pour présélectionner l’arborescence d’emplacement dans l’interface utilisateur.

    Type de données : chaîne
    fuseau horaire Fuseau horaire associé à l’emplacement des résultats.

    Type de données : objet

    "timezone": {
  "value": "String",
  "displayValue": "String"
}
    fuseauhoraire.valeur Identificateur du fuseau horaire IANA pour l’emplacement des résultats. Par exemple, Amérique/New_York.

    Type de données : chaîne
    timezone.displayValue Nom du fuseau horaire explicite. Par exemple, États-Unis/Est.

    Type de données : chaîne
    wsdSource Identificateur du système source de l’emplacement. Utilisé lorsque l’emplacement provient d’une intégration externe.

    Type de données : chaîne
    externalId Identificateur de l’enregistrement de l’emplacement dans un système source externe, le cas échéant.

    Type de données : chaîne
    floorId Sys_id de l’étage où se trouve l’emplacement.

    Table : table Étage du lieu de travail [sn_wsd_core_floor]

    Type de données : chaîne
    isReservable Marqueur indiquant si l’emplacement peut être réservé.
    Valeurs possibles :
    • vrai : l’emplacement est réservable.
    • faux : l’emplacement n’est pas réservable.

    Type de données : booléennes
    isPrivate Marqueur indiquant si l’emplacement renvoyé est privé.

    Un emplacement est considéré comme privé lorsqu’il est marqué comme privé dans le profil du lieu de travail ou lorsqu’il est associé à une réservation dont l’état est privé ou sensible.

    Valeurs possibles :
    • vrai : l’emplacement est privé.
    • faux : l’emplacement est public.

    Type de données : booléennes

    Demande cURL

    L’exemple suivant récupère l’emplacement actuel d’un utilisateur spécifique, y compris l’emplacement basé sur le quartier comme solution de secours.

    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"

    Corps de la réponse lorsque l’emplacement est trouvé.

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

    Corps de réponse lorsque l’emplacement est introuvable (objet vide {}).

    {
  "result": {}
}