API do Import Set

  • Versão de lançamento: Yokohama
  • Atualizado 30 de jan. de 2025
  • 11 min. de leitura

    • A API do conjunto de importação fornece endpoints que permitem que você interaja com tabelas de conjunto de importação.

    Esta API transforma os 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 reflete a interface SOAP existente.

    Segurança

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

    Conjunto de importação - GET /now/import/{stagingTableName}/{sys_id}

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

    Formato da URL

    URL com controle de versão: /api/now/{api_version}/import/{stagingTableName}/{sys_id}

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

    Nota:
    As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário 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 acessada. Por exemplo, v1 ou v2. Somente especifique este valor 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. Parâmetros do corpo da solicitação (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/json ou 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 códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de 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 conjunto de importação são excluídas com frequência com base em uma programação, as solicitações GET podem retornar respostas 404 Não encontrado 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"
  }
]
    resultado.display_name Nome de exibição do conjunto de importação.

    Tipo de dados: cadeia de caracteres
    resultado.display_value Valor do conjunto de importação.

    Tipo de dados: cadeia de caracteres
    resultado.registro_link Solicitação GET da API da tabela para o registro importado.

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

    Tipo de dados: cadeia de caracteres
    resultado.sys_id Sys_id do registro de importação.

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

    Tipo de dados: cadeia de caracteres
    resultado.transformar_mapa Nome do mapa de transformação.

    Tipo de dados: cadeia de caracteres
    preparação_tabela Nome da tabela de preparação de importação.

    Tipo de dados: cadeia de caracteres

    Amostra de solicitação cURL

    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/{stagingTableName}

    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 sobre os 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 da URL

    URL com controle de versão: /api/now/{api_version}/import/{stagingTableName}

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

    Nota:
    As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário 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 de 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 poderá não estar em conformidade com o formato pretendido. Por exemplo, a noção ":" do objeto JSON aninhado é alterada para "=".
    Tabela 7. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor 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 serão importados.

    Tipo de dados: cadeia de caracteres
    Tabela 8. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 9. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    Chamada específica Pares de 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/json ou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/json ou 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 códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de 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"
  }
]
    resultado.display_name Nome de exibição do conjunto de importação.

    Tipo de dados: cadeia de caracteres
    resultado.display_value Valor do conjunto de importação.

    Tipo de dados: cadeia de caracteres
    resultado.registro_link Solicitação GET da API da tabela para o registro importado.

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

    Tipo de dados: cadeia de caracteres
    resultado.sys_id Sys_id do registro de importação.

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

    Tipo de dados: cadeia de caracteres
    resultado.transformar_mapa Nome do mapa de transformação.

    Tipo de dados: cadeia de caracteres
    preparação_tabela Nome da tabela de preparação de importação.

    Tipo de dados: cadeia de caracteres

    Amostra de solicitação cURL

    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/{stagingTableName}/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 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 do arquivo de 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 chave-valor.

    Formato da URL

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

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

    Nota:
    As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário 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 de 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 poderá não estar em conformidade com o formato pretendido. Por exemplo, a noção ":" do objeto JSON aninhado é alterada para "=".
    Tabela 13. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    stagingTableName Nome da tabela de conjunto de importação da qual os dados serão importados. Consulte Conceitos-chave de Conjuntos para 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 para importação múltipla [sys_multi_import_set]. Se especificado, adiciona a importação atual a este conjunto de importação múltiplo em vez de adicionar a um novo conjunto de importação múltiplo.

    Tipo de dados: cadeia de caracteres

    "Table" (Tabela):
    executar_após 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 de importações.

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

    Tipo de dados: cadeia de caracteres

    Tabela: conjuntos para importação [sys_import_set]
    Tabela 15. Corpo da solicitação (JSON)
    Formato Descrição
    Arquivo de 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 sua fonte de dados. Consulte as informações de 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 Criar 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 campo Caminho para cada linha.
    • Para mudar o comportamento padrão do usuário REST Inserir Múltiplos, crie uma entrada na tabela REST Inserir Múltiplos [sys_rest_insert_multiple].
    • Habilite Usar formato de fonte de dados na entrada múltipla de inserção REST.

    Tipo de dados: objeto
    Coluna da tabela de preparação (padrão) Este formato de corpo de solicitação corresponde às colunas da tabela de preparação. Use a matriz records de pares de chave-valor que correspondem à 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 na sua tabela de preparação.

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

    {
   "records":[
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      },
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      }
   ]
}
    Você pode modificar as configurações de mapeamento adicionando uma entrada na tabela Múltiplos de inserção de REST [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>"
      }
   ]
}

    O Data dictionary tables fornece detalhes sobre os campos da 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 códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de 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 deste processo de conjunto de importação.

    Tipo de dados: cadeia de caracteres

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

    Tipo de dados: cadeia de caracteres

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

    Amostra de solicitação cURL

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