API do Import Set

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

    • A API Import Set fornece endpoints que permitem interagir com tabelas de conjunto de importação.

    A 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 a tabelas por meio da REST API é restrito por 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 de URL

    URL com controle de versões: /api/now/{api_version}/import/{stagingTableName}/{sys_id}

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

    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
    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
    Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    Nenhum

    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

    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
    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 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
    resultado.exibição_valor 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
    tabela.resultado 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
    staging_table Nome da tabela de preparação de importação.

    Tipo de dados: cadeia de caracteres

    Exemplo 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 em scripts de transformação são processados e retornados em resposta, junto com quaisquer campos de resposta personalizados.

    Formato de URL

    URL com controle de versões: /api/now/{api_version}/import/{stagingTableName}

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

    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 do conjunto de importação pode 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. 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 serão importados.

    Tipo de dados: cadeia de caracteres
    Tabela 8. Parâmetros de consulta
    Nome Descrição
    Nenhum
    Tabela 9. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    Específico da chamada 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

    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 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"
  }
]
    result.display_name Nome de exibição do conjunto de importação.

    Tipo de dados: cadeia de caracteres
    resultado.exibição_valor 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
    tabela.resultado 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
    staging_table Nome da tabela de preparação de importação.

    Tipo de dados: cadeia de caracteres

    Exemplo 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 de 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 vários [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 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 chave-valor.

    Formato de URL

    URL com controle de versões: /api/now/{api_version}/import/{stagingTableName}/insertMultiple

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

    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 do conjunto de importação pode 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. 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 Principais conceitos de Import Sets.

    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
    executar_depois Sys_id de uma entrada na tabela Import Sets [sys_import_set]. 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 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 da 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 Inserção múltipla REST, crie uma entrada na tabela Inserção múltipla REST [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 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 de acordo com os campos na tabela de preparação.

    O valor da chave padrão do mapeamento de coluna é para a tabela da 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 vários [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 dicionário de dados 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

    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 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 à tabela Import Sets [sys_import_set]. 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
    multi_import_set_id Sys_id do registro adicionado à tabela Conjuntos de importação múltipla [sys_multi_import_set]. Este valor pode ser usado para agrupar vários conjuntos de importação em um conjunto.

    Tipo de dados: cadeia de caracteres

    Exemplo 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 Import Sets [sys_import_set] e Multi Import Sets [sys_multi_import_set].

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