Pesquisa com IA API de mapeamento de usuário externo

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 6 min. de leitura

    • . Mapeamento de usuário externo da Pesquisa com IA A API fornece endpoints que permitem a ingestão de informações de mapeamento de usuário de fontes externas no ServiceNow® Pesquisa com IAíndice da aplicação.

    Pesquisa com IA Mapeamento de usuário externo - POST /ais/external_content/user_mapping/import_multiple/

    Importa uma lista de mapeamentos de usuários externos para um Pesquisa com IA tabela de mapeamento de usuário. Cada mapeamento especifica aliases de usuário e grupo definidos externamente para um ServiceNow AI Platform usuário. Pesquisa com IA o usa esses aliases para determinar quais resultados de pesquisa de documento externo o usuário pode exibir.

    Para saber como Pesquisa com IA a segurança de conteúdo externo utiliza mapeamentos de usuário externo, consulte Segurança de conteúdo externo para Pesquisa com IA .

    Os nomes de usuário e grupo em mapeamentos de usuário externo devem corresponder aos especificados nas permissões de acesso de segurança para documentos externos ingeridos por meio do Ingestão de conteúdo externo APIs PUBLIQUE /ais/external_content/ingestDocument/ endpoint. Para obter mais informações sobre como ingerir documentos externos com permissões de acesso de segurança para usuários e grupos definidos externamente, consulte API de ingestão de conteúdo externo .

    Para exibir históricos de importação de registros de mapeamento de usuário externo importados por meio deste endpoint, navegue até Pesquisa com IA > Conteúdo Externo > Histórico de importação de mapeamento de usuário. Em um registro de histórico, você pode exibir os registros Conjunto de importação [sys_import_set] e Conjunto de importação múltipla [sys_multi_import_set] para uma tarefa de importação. Use as informações desses registros para verificar se os mapeamentos de usuário externo foram importados corretamente.

    Formato de URL

    URL com controle de versão: /api/now//api/ais/external_content/user_mapping/import_multiple/

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para REST APIs com script, há informações adicionais de versão no Formulário de serviço REST com script .

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessado. 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
    target_table
    O nome do Pesquisa com IA tabela de mapeamento de usuário na qual você deseja que os mapeamentos importados apareçam. Por exemplo, x_snc_sharepoint_user_table .
    Nota:
    Você deve criar o destino Pesquisa com IA tabela de mapeamento de usuário por meio do Pesquisa com IA > Conteúdo Externo > Criar mapeamento de usuário antes de usar este endpoint. Se você especificar uma tabela de mapeamento de usuário que não existe, a solicitação falhará.

    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
    (objeto)

    Obrigatório. Objeto sem nome.

    Tipo de dados: Objeto

    {
  "records": [Array]
}
    .records

    Obrigatório. Matriz de objetos em que cada objeto representa um mapeamento de usuário para importar para a tabela de destino especificada.

    Tipo de dados: Matriz

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

    Matriz de cadeias de caracteres em que cada cadeia de caracteres é o nome de um grupo definido externamente a ser definido como um alias para ServiceNow AI Platform usuário especificado pelo .records.mapping_value parâmetro.

    Tipo de dados: Matriz

    Os valores podem estar em qualquer formato, dependendo dos nomes dos grupos definidos externamente selecionados para o mapeamento do usuário. Os exemplos incluem:

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

    Matriz de cadeias de caracteres em que cada cadeia de caracteres é o nome de um usuário definido externamente a ser definido como um alias para ServiceNow AI Platform usuário especificado pelo .records.mapping_value parâmetro.

    Tipo de dados: Matriz

    Os valores podem estar em qualquer formato, dependendo dos nomes das contas de usuário definidas externamente selecionadas para o mapeamento de usuário. Os exemplos incluem:

    "external_user": [
  "beth-anglin",
  "ad\beth.anglin",
  "beth-anglin@sharepoint"
]
    .records.mapping_value
    E-mail valor do campo que identifica exclusivamente um registro existente. Todos os aliases de usuário e grupo definidos externamente na solicitação são mapeados para ServiceNow AI Platform usuário com este endereço de e-mail.
    Nota:
    A API trata esse parâmetro como o identificador exclusivo do registro de mapeamento do usuário. Se você importar outro mapeamento de usuário com o mesmo mapping_value como um registro de mapeamento de usuário existente, o novo registro substitui o registro existente.

    Tipo de dados: Cadeia de caracteres

    Tabela: Usuário [sys_user]

    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 de REST API compatíveis .

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Oferece suporte somente a application/json.
    Tipo de conteúdo Formato de dados do corpo da solicitação. Oferece suporte somente a application/json.
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    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 Códigos de resposta HTTP da REST API .

    Tabela 6. Códigos de status
    Código do status Descrição
    201 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Um tipo de solicitação incorreto ou uma solicitação malformada foi detectada.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

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

    Nome Descrição
    erro

    Objeto que descreve o erro encontrado durante o processamento da solicitação.

    Tipo de dados: Objeto

    "error": {
  "detail": "String",
  "message": "String"
}
    error.detail

    Detalhes do erro encontrado durante o processamento da solicitação.

    Tipo de dados: Cadeia de caracteres
    mensagem.erro

    Mensagem do erro encontrado durante o processamento da solicitação.

    Tipo de dados: Cadeia de caracteres
    import_set_id

    Sys_id para o novo registro criado na tabela Conjunto de importação [sys_import_set] por uma solicitação bem-sucedida.

    Tipo de dados: Cadeia de caracteres
    multi_import_set_id

    Sys_id para o novo registro criado na tabela Conjunto de importação múltipla [sys_multi_import_set] por uma solicitação bem-sucedida.

    Tipo de dados: Cadeia de caracteres
    resultado

    Resultado de uma solicitação malsucedida. Inclui uma mensagem descrevendo o motivo da falha na solicitação.

    Tipo de dados: Cadeia de caracteres
    status

    Status de uma solicitação malsucedida.

    Valores válidos:
    • failure

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    Importe aliases de usuário e grupo definidos externamente para ServiceNow AI Platform Beth Anglin e Abel Tuter em um Pesquisa com IA tabela de mapeamento de usuário chamada 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"
        ]
      }
    ]
  }'

    A resposta mostra os sys_ids dos registros do Conjunto de importação gerado e do Conjunto de importação múltiplo.

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

    Solicitação de curl

    Solicitação inválida de importação que contém um registro de mapeamento vazio.

    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"
        ]
      },
      {}
    ]
  }'

    A solicitação falha com o status 400 e a resposta indica a natureza da falha.

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