Recherche IA API de mappage d’utilisateur externe

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 5 minutes de lecture

    • L’API de mappage des utilisateurs externes Recherche IA fournit des points de terminaison qui permettent l’ingestion d’informations de mappage d’utilisateurs à partir 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 table de Recherche IA mappage d’utilisateurs. Chaque mappage spécifie des alias d’utilisateur et de groupe définis en externe pour un Now 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 les utilisateurs et les groupes définis en externe, consultez API d’ingestion de contenu externe.

    Pour afficher les historiques d’importation des enregistrements de mappage d’utilisateur externe importés via ce point de terminaison, naviguez vers Recherche IA > Contenu externe > Historique des importations de mappages de l'utilisateur. Depuis un enregistrement d’historique, vous pouvez afficher les enregistrements du jeu d’importation [sys_import_set] et du jeu d’importation multiple [sys_multi_import_set] pour une tâche d’importation. Utilisez les informations issues 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}

    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. 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
    Le nom de la Recherche IA table de mappage des utilisateurs 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’utilisateurs 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]
}
    {object}.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 en externe à définir comme alias pour l’utilisateur Now 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’utilisateurs. 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 en externe à définir comme alias pour l’utilisateur Now 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’utilisateurs. Exemples :

    "external_user": [
  "beth-anglin",
  "ad\beth.anglin",
  "beth-anglin@sharepoint"
]
    {objet}.records.mapping_value
    Valeur de champ d’e-mail qui identifie de façon unique un enregistrement existant dans la table Utilisateur [sys_user]. Tous les alias d’utilisateur et de groupe définis en externe dans la demande sont mappés à l’utilisateur Now Platform disposant de cette adresse e-mail.
    Remarque :
    L’API traite ce paramètre comme l’identificateur unique de l’enregistrement de mappage de l’utilisateur. Si vous importez un autre mappage d’utilisateur avec le 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

    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 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"
}
    error.detail

    Détails de l’erreur rencontrée lors du traitement de la demande.

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

    Message de l’erreur rencontrée lors du traitement de la demande.

    Type de données : chaîne
    import_set_id

    Sys_id du 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 du 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 ayant échoué. Inclut un message décrivant le motif de l’échec de la demande.

    Type de données : chaîne
    statut

    Statut d’une demande ayant échoué.

    Valeurs valides :
    • failure

    Type de données : chaîne

    Demande cURL

    Importez des alias d’utilisateur et de groupe définis en externe pour Now Platform les utilisateurs Beth Anglin et Abel Tuter dans une table de mappage d’utilisateurs Recherche IA 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 affiche les sys_ids pour les enregistrements générés du jeu d’importation et du jeu d’importation multiple.

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

    Demande cURL

    Demande d’importation 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 la défaillance.

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