Pesquisa com IA API de mapeamento de usuário externo

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 5 min. de leitura

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

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

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

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

    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 endpoint POST /ais/external_content/ingestDocument/{schema_table_name} da API de ingestão de conteúdo externo. 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 para 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 do Conjunto de importação [sys_import_set] e do 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ões: /api/now/{api_version}/ais/external_content/user_mapping/import_multiple/{target_table}

    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 acessada. 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 da tabela de mapeamento de usuário Pesquisa com IA na qual você deseja que os mapeamentos importados apareçam. Por exemplo, x_snc_sharepoint_user_table.
    Nota:
    Você deve criar a tabela de mapeamento de usuário de destino Pesquisa com IA por meio de Pesquisa com IA > Conteúdo Externo > Criar mapeamento de usuário módulo 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
    Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    {objeto}

    Obrigatório. Objeto sem nome.

    Tipo de dados: objeto

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

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

    Tipo de dados: matriz

    "records": [
  {
    "external_group": [Array],
    "external_user": [Array],
    "mapping_value": "String"
  }
]
    {object}.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 o usuário Now Platform especificado pelo parâmetro {object}.records.mapping_value.

    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"
]
    {object}.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 o usuário Now Platform especificado pelo parâmetro {object}.records.mapping_value.

    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"
]
    {object}.records.mapping_value
    Valor do campo de e-mail que identifica exclusivamente um registro existente na tabela Usuário [sys_user]. Todos os aliases de usuário e grupo definidos externamente na solicitação são mapeados para o usuário Now Platform com este endereço de e-mail.
    Nota:
    A API trata este 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 de um registro de mapeamento de usuário existente, o novo registro substituirá o registro existente.

    Tipo de dados: cadeia de caracteres

    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

    Códigos de status

    Os códigos de status a seguir se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP da REST API.

    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. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
    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"
}
    erro.detalhe

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

    Tipo de dados: cadeia de caracteres
    erro.mensagem

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

    Tipo de dados: cadeia de caracteres
    import_set_id

    Sys_id do novo registro criado na tabela Import Set [sys_import_set] por uma solicitação bem-sucedida.

    Tipo de dados: cadeia de caracteres
    multi_import_set_id

    Sys_id do 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 Platform usuários Beth Anglin e Abel Tuter para uma tabela de mapeamento de usuário Pesquisa com IA 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 e do Conjunto de importação múltiplo gerados.

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

    Solicitação de cURL

    Importar solicitação inválida 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 status 400 e a resposta indica a natureza da falha.

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