API do conjunto de importação

  • Versão de lançamento: Australia
  • Atualizado 12 de mar. de 2026
  • 11 min. de leitura

    • . Conjunto de importação A API fornece endpoints que permitem interagir com tabelas de conjuntos de importação.

    Esta API transforma dados de entrada com base nos mapas de transformação associados. A API do conjunto de importação oferece suporte a transformações síncronas. A API do conjunto de importação espelha a interface SOAP existente.

    Segurança

    O acesso a tabelas por meio da REST API é restrito pelo BasicAuth. Para permitir acesso a tabelas sem autenticação ou autorização, adicione o nome da tabela a sys_public.list. As ACLs definidas nas tabelas ainda são impostas, e é responsabilidade do administrador desativar as ACLs.

    Conjunto de importação - OBTER /now/import/stagingTableName/sys_id

    Recupera o registro de preparação de importação especificado e o resultado da transformação resultante.

    Formato de URL

    URL com controle de versão: /api/now/

    URL padrão: /api/now/import/stagingTableName/sys_id

    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
    StagingTableName Nome da tabela da qual obter os dados de importação.

    Tipo de dados: Cadeia de caracteres
    sys_id Sys_id do registro que contém os dados.

    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
    Nenhum(a)

    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. Tipos compatíveis: application/jsonou application/xml.

    Padrão: 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
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    404 Indica que o recurso especificado não estava disponível. Como as tabelas de conjuntos de importação são excluídas com frequência com base em uma programação, as solicitações GET podem retornar 404 respostas Não encontradas se o resultado da transformação não existir mais.
    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
    import_set Nome do conjunto de importação.

    Tipo de dados: Cadeia de caracteres
    resultado Lista de objetos que contêm informações sobre os conjuntos de dados que foram importados.
    Tipo de dados: Matriz
    "result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]
    display_name.display_name Nome de exibição da coluna específica na tabela para a qual o valor de exibição é verdadeiro. Por exemplo, número .

    Tipo de dados: Cadeia de caracteres
    display_value.display_value Valor de exibição do display_namecoluna. Por exemplo, CHG0000123 .

    Tipo de dados: Cadeia de caracteres
    record_link.record_link Solicitação de OBTENÇÃO da API de tabela para o registro importado.

    Tipo de dados: Cadeia de caracteres
    status.resultado Status da importação.

    Tipo de dados: Cadeia de caracteres
    sys_id.result.sys_id Sys_id do registro de importação.

    Tipo de dados: Cadeia de caracteres
    tabela.resultado Nome da tabela na qual os dados foram importados.

    Tipo de dados: Cadeia de caracteres
    resultado.transform_map Nome do mapa de transformação.

    Tipo de dados: Cadeia de caracteres
    staging_table Nome da tabela de preparação de importação.

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl de amostra

    curl "https://instance.servicenow.com/api/now/import/imp_user/e2928be64f411200adf9f8e18110c777" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    {
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.service-now.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

    Conjunto de importação - PUBLICAR /now/import/

    Insere dados de entrada em uma tabela de preparação especificada e aciona a transformação com base em mapas de transformação predefinidos na tabela de conjunto de importação.

    A transformação ocorre de forma síncrona. Para cada mapa de transformação definido, as respostas incluem resultados de transformação, como informações nos registros de destino.
    Nota:
    Os campos status_message e error_message nos scripts de transformação são processados e retornados em resposta, junto com todos os campos de resposta personalizados.

    Formato de URL

    URL com controle de versão: /api/now/

    URL padrão: /api/now/import/stagingTableName

    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

    Nota:
    O método POST do conjunto de importação aceita somente pares nome-valor de tipos de dados de cadeia de caracteres nos parâmetros do corpo da solicitação. Se qualquer outro tipo de dados for fornecido, o valor resultante armazenado na tabela de conjunto de importação pode não estar em conformidade com o formato pretendido. Por exemplo, a noção ":" do objeto JSON aninhado é mudada para ":".
    Tabela 7. 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
    StagingTableName Nome da tabela da qual importar os dados.

    Tipo de dados: Cadeia de caracteres
    Tabela 8. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 9. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    Chamada específica Pares nome-valor a serem inseridos nos campos de importação.

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

    Tabela 10. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Tabela 11. 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 12. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    201 Bem-sucedido. A solicitação foi criada com sucesso.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    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
    import_set Nome do conjunto de importação.

    Tipo de dados: Cadeia de caracteres
    resultado Lista de objetos que contêm informações sobre os conjuntos de dados que foram importados.
    Tipo de dados: Matriz
    "result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]
    display_name.display_name Nome de exibição da coluna específica na tabela para a qual o valor de exibição é verdadeiro. Por exemplo, número .

    Tipo de dados: Cadeia de caracteres
    display_value.display_value Valor de exibição do display_namecoluna. Por exemplo, CHG0000123 .

    Tipo de dados: Cadeia de caracteres
    record_link.record_link Solicitação de OBTENÇÃO da API de tabela para o registro importado.

    Tipo de dados: Cadeia de caracteres
    status.resultado Status da importação.

    Tipo de dados: Cadeia de caracteres
    sys_id.result.sys_id Sys_id do registro de importação.

    Tipo de dados: Cadeia de caracteres
    tabela.resultado Nome da tabela na qual os dados foram importados.

    Tipo de dados: Cadeia de caracteres
    resultado.transform_map Nome do mapa de transformação.

    Tipo de dados: Cadeia de caracteres
    staging_table Nome da tabela de preparação de importação.

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl de amostra

    curl "https://instance.servicenow.com/api/now/import/imp_user" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{'first_name':'John','last_name':'Public','user_id':'john.public','email':'john.public@company.com'}" \
--user "username":"password"
    {
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.servicenow.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

    Conjunto de importação - POST /now/import//insertMultiple

    Insere vários registros em uma tabela de preparação especificada e aciona a transformação com base em mapas de transformação predefinidos ou configurações do Mecanismo de transformação robusto (RTE) em uma única solicitação.

    A transformação é assíncrona por padrão. Para definir a transformação síncrona, crie um novo registro na tabela REST Inserir múltiplos [sys_rest_insert_multiple], selecione a tabela de origem e defina a transformação como síncrona.

    Este endpoint pode enviar um corpo de solicitação em dois formatos possíveis.
    Formato de arquivo da fonte de dados
    Se você gerar uma tabela de preparação a partir de uma fonte de dados JSON, corresponda ao formato JSON do arquivo de origem.
    Formato da coluna da tabela de preparação
    Padrão. Corresponde ao formato do corpo da solicitação da coluna da tabela de preparação em pares de valor-chave.

    Formato de URL

    URL com controle de versão: /api/now//import//stagingTableName/insertMultiple

    URL padrão: /api/now/import/stagingTableName/insertMultiple

    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

    Nota:
    O método POST do conjunto de importação aceita somente pares nome-valor de tipos de dados de cadeia de caracteres nos parâmetros do corpo da solicitação. Se qualquer outro tipo de dados for fornecido, o valor resultante armazenado na tabela de conjunto de importação pode não estar em conformidade com o formato pretendido. Por exemplo, a noção ":" do objeto JSON aninhado é mudada para ":".
    Tabela 13. 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
    StagingTableName Nome da tabela do conjunto de importação da qual importar os dados. Consulte A importação define conceitos-chave .

    Tipo de dados: Cadeia de caracteres
    Tabela 14. Parâmetros de consulta
    Nome Descrição
    multi_import_set_id Sys_id de uma entrada na tabela Conjuntos de importação múltipla [sys_multi_import_set]. Se especificado, adiciona a importação atual a este conjunto de importação múltipla em vez de adicionar a um novo conjunto de importação múltipla.

    Tipo de dados: Cadeia de caracteres

    Tabela:
    run_after Sys_id da entrada a ser executada. Permite a execução do conjunto de importação atual após a conclusão do conjunto de importação especificado. Você pode usar este parâmetro para impor a ordem sequencial das importações.

    Este parâmetro só é válido em transformações assíncronas.

    Tipo de dados: Cadeia de caracteres

    Tabela: Conjuntos de importação [sys_import_set]
    Tabela 15. Corpo da solicitação (json)
    Formato Descrição
    Arquivo da fonte de dados Este formato de corpo de solicitação corresponde ao formato de arquivo JSON usado para criar a fonte de dados. Forneça o corpo da solicitação no mesmo formato que o JSON na fonte de dados. A entrada JSON varia de acordo com as propriedades na fonte de dados. Consulte as informações JSON em Fonte de dados do tipo de arquivo .
    • Esta opção só estará disponível se a tabela de preparação tiver sido criada usando uma fonte de dados JSON. Consulte Crie uma fonte de dados de tipo de arquivo .
    • Você deve definir o caminho da fonte de dados na tabela Fonte de dados [sys_data_source] no Caminho para cada linha campo.
    • Para mudar o comportamento padrão do usuário Inserir REST múltiplo, crie uma entrada na tabela Inserir REST múltiplos [sys_rest_insert_multiple].
    • Habilite o. Usar o formato da fonte de dados No REST, insira várias entradas.

    Tipo de dados: Objeto
    Coluna da tabela de preparação (padrão) Este formato do corpo da solicitação corresponde às colunas da tabela de preparação. Use o. recordsmatriz de pares chave-valor correspondentes à coluna da tabela de preparação para inserir nos campos de importação. Cada chave JSON mapeia a coluna da tabela para um valor JSON que representa o valor a ser inserido. A entrada JSON varia dependendo de quais campos estão em sua tabela de preparação.

    O valor de chave padrão do mapeamento de coluna é para a tabela de coluna.

    {
   "records":[
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      },
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      }
   ]
}
    Você pode modificar as configurações de mapeamento adicionando uma entrada na tabela REST Inserir múltiplos [sys_rest_insert_multiple] e alterando o. Mapeamento de coluna de Rótulo para Nome da coluna .
    {
   "records":[
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      },
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      }
   ]
}

    . Data dictionary tables fornece detalhes sobre campos de tabela no sistema.

    Tipo de dados: Matriz

    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 16. 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 17. 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 18. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    201 Bem-sucedido. A solicitação foi criada com sucesso.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Corpo da resposta (json)

    Nome Descrição
    import_set_id Sys_id do registro adicionado. Para solicitações assíncronas, você pode usar este valor para executar outro conjunto de importação após a conclusão desse processo de conjunto de importação.

    Tipo de dados: Cadeia de caracteres

    Tabela: Conjuntos de importação [sys_import_set]
    multi_import_set_id Sys_id do registro adicionado. Use este valor para agrupar vários conjuntos de importação em um conjunto.

    Tipo de dados: Cadeia de caracteres

    Tabela: Conjuntos de importação múltipla [sys_multi_import_set]

    Solicitação de curl de amostra

    O exemplo a seguir mostra como executar uma transformação em uma tabela de importação chamada u_employee_import_set_table usando o formato de coluna da tabela de preparação.

    curl "https://instance.servicenow.com/api/now/import/u_employee_import_set_table/insertMultiple" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"records\": [
  {
   \"Address\": \"Hollywood\",
   \"Name\": \"Tom\",
   \"ID\": \"123\"
  },
  {
   \"Address\": \"Vine\",
   \"Name\": \"Irene\",
   \"ID\": \"456\"
  }
  ]
}" \
--user 'username':'password'

    Os resultados incluem sys_ids para novos registros nas tabelas Conjuntos de importação [sys_import_set] e Conjuntos de importação múltipla [sys_multi_import_set].

    {
  "import_set_id": "<import_set_sys_id>",
  "multi_import_set_id": "<multi_import_set_sys_id>"
}