Pesquisa com IA API de mapeamento de usuário externo

  • Versão de lançamento: Yokohama
  • Atualizado 30 de jan. de 2025
  • 5 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 do usuário de fontes externas para o. 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 IAtabela de mapeamento de usuário. Cada mapeamento especifica aliases de usuário e grupo definidos externamente para um Now Platformusuário. Pesquisa com IAusa esses aliases para determinar quais resultados de pesquisa de documento externo o usuário pode exibir.

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

    Os nomes de usuário e grupo em mapeamentos de usuários externos 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 POSTAR /ais/external_content/ingestDocument/(schema_table_name) endpoint. Para obter mais informações sobre a ingestão de 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ários externos foram importados corretamente.

    Formato de URL

    URL com controle de versão: /api/now/(api_version)/ais/external_content/user_mapping/import_multiple/(target_table)

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para APIs REST com script, há informações adicionais de versão no 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 para acessar. 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 IAtabela 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 IAtabela de mapeamento de usuário por meio de 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. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    (objeto)

    Necessário. Objeto sem nome.

    Tipo de dados: Objeto

    {
  "records": [Array]
}
    (objeto).registros

    Necessá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"
  }
]
    (objeto).records.external_group

    Matriz de cadeias de caracteres em que cada cadeia de caracteres é o nome de um grupo definido externamente para definir como alias para Now Platformusuário especificado pelo (objeto).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"
]
    (objeto).records.external_user

    Matriz de cadeias de caracteres em que cada cadeia de caracteres é o nome de um usuário definido externamente para definir como alias para Now Platformusuário especificado pelo (objeto).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"
]
    (objeto).records.mapping_value
    E-mail valor de campo que identifica exclusivamente um registro existente. Todos os aliases de usuário e grupo definidos externamente na solicitação são mapeados para Now Platformusuá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 da REST API compatíveis .

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Suporta somente application/json.
    Tipo de conteúdo Formato de dados do corpo da solicitação. Suporta somente 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 REST API códigos de resposta HTTP .

    Tabela 6. Códigos de status
    Código de 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 referente ao 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 que descreve 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 Now PlatformUsuários Beth Anglin e Abel Tuter em um Pesquisa com IAtabela 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 de Conjunto de importação e Conjunto de importação múltipla gerados.

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