API do Import Set

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 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 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
    StagingTableName Nome da tabela da qual os dados de importação serão obtidos.

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

    Tabela 6. Códigos de status
    Código do 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"
  }
]
    result.display_name Nome de exibição do conjunto de importação.

    Tipo de dados: Cadeia de caracteres
    result.display_value Valor do conjunto de importação.

    Tipo de dados: Cadeia de caracteres
    result.record_link API de tabela OBTER solicitação para o registro importado.

    Tipo de dados: Cadeia de caracteres
    result.status 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
    result.table Nome da tabela na qual os dados foram importados.

    Tipo de dados: Cadeia de caracteres
    result.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 - POST /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 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

    Nota:
    O método POST do conjunto de importação aceita somente pares nome-valor de tipos de dados 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 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
    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 de 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 Códigos de resposta HTTP da REST API .

    Tabela 12. Códigos de status
    Código do 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"
  }
]
    result.display_name Nome de exibição do conjunto de importação.

    Tipo de dados: Cadeia de caracteres
    result.display_value Valor do conjunto de importação.

    Tipo de dados: Cadeia de caracteres
    result.record_link API de tabela OBTER solicitação para o registro importado.

    Tipo de dados: Cadeia de caracteres
    result.status 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
    result.table Nome da tabela na qual os dados foram importados.

    Tipo de dados: Cadeia de caracteres
    result.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 robusta (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 Inserção múltipla REST [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 de 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 de 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 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

    Nota:
    O método POST do conjunto de importação aceita somente pares nome-valor de tipos de dados 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 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
    StagingTableName Nome da tabela do conjunto de importação da qual os dados serão importados. Consulte Conceitos-chave de conjuntos de importação .

    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. Habilita 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 do corpo da 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 dependendo das propriedades em sua 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] em Caminho para cada linha campo.
    • Para mudar o comportamento padrão do usuário Inserção múltipla REST, crie uma entrada na tabela Inserção múltipla REST [sys_rest_insert_multiple].
    • Habilite o. Formato de fonte de dados do use 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 recordsmatriz de pares de chave-valor correspondentes à coluna da tabela de preparação a ser inserida 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 da chave padrão de 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 Insert Multiple [sys_rest_insert_multiple] e alterando Mapeamento de coluna de Rótulo . 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 de 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 Códigos de resposta HTTP da REST API .

    Tabela 18. Códigos de status
    Código do 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 para importação [sys_import_set] e Conjuntos para importação múltipla [sys_multi_import_set].

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