Recherche IA API de mappage des utilisateurs externes

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 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 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 Now Platform utilisateur. Recherche IA utilise ces alias pour déterminer les résultats de recherche de documents externes visibles par l’utilisateur.

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

    Les noms d’utilisateur et de groupe 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 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, 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 Jeu d’importation [sys_import_set] et Multi Import Set [sys_multi_import_set] pour 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}

    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
    Nom de la Recherche IA table de mappage 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 utilisateur qui n’existe pas, la demande échoue.

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

    Requis. Objet sans nom.

    Type de données : objet

    {
  "records": [Array]
}
    {object}.records

    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 manière 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 avec cette adresse e-mail.
    Remarque :
    L’API traite ce paramètre comme identificateur unique pour 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 une 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 une 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 de 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"
}
    erreur.détail

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

    Type de données : chaîne
    message d’erreur

    Message de l’erreur rencontrée lors du 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 qui n’a pas abouti. Inclut un message décrivant le motif de l’échec de la demande.

    Type de données : chaîne
    statut

    État 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 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

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