Recherche IA API de mappage de l’utilisateur externe

  • Rversion finale: Zurich
  • Mis à jour 31 juil. 2025
  • 5 minutes de lecture

    • L’API de mappage d’utilisateurs externes Recherche IA fournit des points de terminaison qui permettent l’ingestion d’informations de mappage utilisateur provenant de sources externes dans l’index de l’applicationServiceNow® Recherche IA.

    Recherche IA Mappage des utilisateurs externes : POST /ais/external_content/user_mapping/import_multiple/{target_table}

    Importe une liste de mappages d’utilisateurs externes dans une Recherche IA table de mappage d’utilisateurs. Chaque mappage spécifie des alias d’utilisateur et de groupe définis en externe pour un ServiceNow AI Platform utilisateur. Recherche IA utilise ces alias pour déterminer les résultats de recherche de documents externes que l’utilisateur peut afficher.

    Pour savoir comment Recherche IA la sécurité du contenu externe utilise les mappages d’utilisateurs externes, consultez Sécurité du contenu externe pour Recherche IA.

    Les noms d’utilisateurs et de groupes dans les mappages d’utilisateurs externes doivent correspondre à ceux spécifiés dans les autorisations d’accès de sécurité pour les documents externes ingérés via le point de terminaison POST /ais/external_content/ingestDocument/{schema_table_name} de l’API d’ingestion de contenu externe. Pour plus d’informations sur l’ingestion de documents externes avec des autorisations d’accès de sécurité pour des utilisateurs et des groupes définis en externe, consultez API d’ingestion de contenu externe.

    Pour afficher les historiques d’importation des enregistrements de mappage d’utilisateurs externes importés via ce point de terminaison, accédez à Recherche IA > Contenu externe > Historique des importations de mappages de l'utilisateur. À partir d’un enregistrement d’historique, vous pouvez afficher les enregistrements de jeu d’importation [sys_import_set] et de jeux d’importation multiples [sys_multi_import_set] d’une tâche d’importation. Utilisez les informations de ces enregistrements pour vérifier que vos mappages d’utilisateurs externes ont été importés correctement.

    Format d'URL

    URL versionnée : /api/now/{api_version}/ais/external_content/user_mapping/import_multiple/{target_table}

    Remarque :
    Les versions disponibles sont spécifiées dans l’explorateur d’API REST. Pour les API REST basées sur un script, des informations de version supplémentaires sont disponibles sur le formulaire Service REST scripté.

    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 différente de la dernière.

    Type de données : chaîne
    target_table
    Nom de la Recherche IA table de mappage de l’utilisateur dans laquelle vous souhaitez que les mappages importés apparaissent. Par exemple, x_snc_sharepoint_user_table.
    Remarque :
    Vous devez créer la table de mappage de l’utilisateur cible Recherche IA via le Recherche IA > Contenu externe > Créer un mappage utilisateur avant d’utiliser ce point de terminaison. Si vous spécifiez une table de mappage d’utilisateur qui n’existe pas, la demande échoue.

    Type de données : chaîne
    Tableau 2. Paramètres de requête
    Nom Description
    Aucun
    Tableau 3. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    {objet}

    Requis. Objet sans nom.

    Type de données : objet

    {
  "records": [Array]
}
    {objet}.enregistrements

    Requis. Tableau d’objets dans lequel chaque objet représente un mappage d’utilisateur à importer dans la table cible spécifiée.

    Type de données : tableau

    "records": [
  {
    "external_group": [Array],
    "external_user": [Array],
    "mapping_value": "String"
  }
]
    {objet}.records.external_group

    Tableau de chaînes où chaque chaîne est le nom d’un groupe défini de façon externe à définir comme alias pour l’utilisateur ServiceNow AI Platform spécifié par le paramètre {object}.records.mapping_value .

    Type de données : tableau

    Les valeurs peuvent être dans n’importe quel format, en fonction des noms des groupes définis en externe sélectionnés pour le mappage d’utilisateur. Exemples :

    "external_group": [
  "itil",
  "hr-admin",
  "report-dev"
]
    {objet}.records.external_user

    Tableau de chaînes où chaque chaîne est le nom d’un utilisateur défini de manière externe à définir comme alias pour l’utilisateur ServiceNow AI Platform spécifié par le paramètre {object}.records.mapping_value .

    Type de données : tableau

    Les valeurs peuvent être dans n’importe quel format, en fonction des noms des comptes d’utilisateurs définis en externe sélectionnés pour le mappage d’utilisateur. Exemples :

    "external_user": [
  "beth-anglin",
  "ad\beth.anglin",
  "beth-anglin@sharepoint"
]
    {objet}.records.mapping_value
    Valeur du champ d’e-mail qui identifie de manière unique un enregistrement existant. Tous les alias d’utilisateur et de groupe définis en externe dans la demande sont mappés à l’utilisateur ServiceNow AI Platform avec cette adresse e-mail.
    Remarque :
    L’API traite ce paramètre comme l’identificateur unique pour l’enregistrement de mappage de l’utilisateur. Si vous importez un autre mappage d’utilisateur avec la même mapping_value qu’un enregistrement de mappage d’utilisateur existant, le nouvel enregistrement remplace l’enregistrement existant.

    Type de données : chaîne

    Table : Utilisateur [sys_user]

    En-têtes

    Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement 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. Prend uniquement en charge application/json.
    Content-Type Format de données du corps de la demande. Prend uniquement en charge application/json.
    Tableau 5. En-têtes de réponses
    En-tête Description
    Aucun

    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
    201 Réussi. La demande a été correctement traitée.
    400 Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté.
    500 Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur.

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

    Nom Description
    erreur

    Objet décrivant l’erreur rencontrée lors du traitement de la demande.

    Type de données : objet

    "error": {
  "detail": "String",
  "message": "String"
}
    erreur.détail

    Détails de l’erreur rencontrée pendant le traitement de la demande.

    Type de données : chaîne
    message.erreur

    Message pour l’erreur rencontrée pendant le traitement de la demande.

    Type de données : chaîne
    import_set_id

    Sys_id pour le nouvel enregistrement créé dans la table Jeu d’importation [sys_import_set] par une demande réussie.

    Type de données : chaîne
    multi_import_set_id

    Sys_id pour le nouvel enregistrement créé dans la table Multi Import Set [sys_multi_import_set] par une demande réussie.

    Type de données : chaîne
    résultat

    Résultat d’une demande en échec. Inclut un message décrivant le motif de l’échec de la demande.

    Type de données : chaîne
    état

    Statut d’une demande en échec.

    Valeurs valides :
    • failure

    Type de données : chaîne

    Demande cURL

    Importez des alias d’utilisateurs et de groupes définis en externe pour ServiceNow AI Platform les utilisateurs Beth Anglin et Abel Tuter dans une Recherche IA table de mappage d’utilisateurs nommée x_snc_sharepoint_user_table.

    curl -X POST 'https://instance.servicenow.com/api/now/v1/ais/external_content/user_mapping/import_multiple/x_snc_sharepoint_user_table' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password' \
  -d '{
    "records": [
      {
        "mapping_value": "beth.anglin@example.com",
        "external_user": [
          "ad\beth-anglin",
          "beth.anglin@sharepoint"
        ],
        "external_group": [
          "itil",
          "itil-admin",
          "itil-dev"
        ]
      },
      {
        "mapping_value": "abel.tuter@example.com",
        "external_user": [
          "ad\abel-tuter",
          "abel.tuter@sharepoint"
        ],
        "external_group": [
          "hr",
          "hr-admin",
          "hr-dev"
        ]
      }
    ]
  }'

    La réponse indique la sys_ids pour les enregistrements de jeu d’importation et de jeux d’importation multiples générés.

    {
  "import_set_id": "6e9ddb629d987010f877878bd9f0e9dd",
  "multi_import_set_id": "269ddb629d987010f877878bd9f0e9de"
}

    Demande cURL

    Importez une demande non valide contenant un enregistrement de mappage vide.

    curl 'https://instance.servicenow.com/api/now/v1/ais/external_content/user_mapping/import_multiple/u_ext_content_user_mapping' \
  --request POST \
  --user 'username':'password' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "records": [
      {
        "mapping_value": "beth.anglin@example.com",
        "external_user": [
          "ad\beth-anglin",
          "beth.anglin@sharepoint"
        ],
        "external_group": [
          "reports",
          "reports-admin",
          "reports-dev"
        ]
      },
      {}
    ]
  }'

    La demande échoue avec l’état 400 et la réponse indique la nature de l’échec.

    {
  "result": "Error in processing the message"
}