CMDB API de ingestão de dados

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

    • A API de ingestão de dados do CMDB fornece endpoints que permitem a ingestão em lote de uma matriz de objetos em uma tabela de conjunto para importação.

    Aviso:
    Esta API não é mais recomendada. Para a mesma funcionalidade com escalabilidade e estabilidade aprimoradas, use o endpoint Conjunto de importação - POST /now/import/{stagingTableName}/insertMultiple. A partir da versão Quebec, qualquer uso da API de ingestão de dados do CMDB deve ser migrado para usar o endpoint do conjunto de importação – insertMutiple.

    Além disso, esta API não funcionará por padrão para instâncias zbootadas.

    Esta API é ativada por meio do plug-in Configuration Management Database (CMDB) (com.snc.cmdb) e requer a função cmdb_import_api_admin.

    CMDB Ingestão de dados - POST /cmdb/ingest/{data_source_sys_id}

    Insere registros na tabela Conjunto para importação associada ao registro da fonte de dados identificado pelo sys_id passado.

    Aviso:
    Esta API não é mais recomendada. Para a mesma funcionalidade com escalabilidade e estabilidade aprimoradas, use o endpoint Conjunto de importação - POST /now/import/{stagingTableName}/insertMultiple. A partir da versão Quebec, qualquer uso da API de ingestão de dados do CMDB deve ser migrado para usar o endpoint do conjunto de importação – insertMutiple.

    Além disso, esta API não funcionará por padrão para instâncias zbootadas.

    O corpo da solicitação deve conter a matriz JSON de objetos (carga útil) a ser inserida na tabela Conjunto para importação. Cada objeto é igual a uma linha na tabela, cada par de nome-valor é igual a uma coluna. A carga JSON deve aproveitar os nomes de campo do conjunto para importação sem o prefixo "u_". Por exemplo, o nome do campo "u_matching_record" deve ser "matching_record" na carga do corpo da solicitação. Se a tabela Conjunto para importação existir, o endpoint anexará as linhas (objetos) à tabela Conjunto para importação existente. Nenhuma verificação de duplicatas ou atualização de registros existentes é realizada.

    Se você estiver criando inicialmente uma aplicação, deverá primeiro criar o registro de fonte de dados associado em sua instância antes de chamar este endpoint. Se você estiver usando este endpoint apenas para adicionar registros a uma tabela de Conjunto para importação existente, não precisará criar o registro da fonte de dados, mas deverá conhecer seu sys_id. O registro da fonte de dados descreve a tabela Conjunto para importação na qual a carga especificada será inserida. Esta tabela deve estender a tabela Linhas do conjunto de importação [sys_import_set_row]. Além disso, a fonte de dados deve ser definida como Anexo e o formato definido como JSON. Para obter mais informações sobre fontes de dados, consulte Fontesde dados .

    Se a tabela Conjunto de importação definida no registro da fonte de dados não existir, o endpoint anexará a carga passada ao registro da fonte de dados. Para criar a tabela Conjunto de importação inicial, você deve importar manualmente os dados para a tabela Conjunto de importação. Para importar os dados, no formulário Fonte de dados associado, clique no link Testar carga de 20 registros ou Carregar todos os registros na seção Links relacionados. Depois que a tabela Conjunto de importação for criada, você não poderá adicionar colunas à tabela usando este endpoint. Se os pares de nome-valor forem passados posteriormente e não existirem na tabela Conjunto para importação, eles serão ignorados sem aviso. Se você precisar modificar as colunas na tabela Conjunto para importação, poderá adicioná-las manualmente à tabela. Você também pode excluir ou renomear a tabela Conjunto para importação e chamar o endpoint novamente usando a nova carga.

    Você deve ter a função cmdb_import_api_admin para acessar este endpoint.

    Formato da URL

    URL com controle de versão: /api/now/{api_version}/cmdb/ingest/{data_source_sys_id}

    URL padrão: /api/now/cmdb/ingest/{data_source_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. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    data_source_sys_id Sys_id do registro da fonte de dados.
    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
    Matriz Matriz de forma livre de objetos que descreve os dados a serem anexados à tabela Conjunto para importação associada. Cada objeto na matriz define uma linha na tabela Conjuntos para importação; cada par de nome-valor tem uma coluna.
    Nota:
    Esta matriz deve ser nomeada, como "{" registros ": [{" "hostname": "Hostname1", "serialnumber": "2acd3873-7fc5-454c-8844-e7769e4d6cfc", \model\: \ID do modelo\}, {\fornecedor\\: \ABC Co\}]}".

    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
    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 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 de status Descrição
    201 Criado. Um anexo foi adicionado à fonte de dados.
    202 Aceito. Linhas foram adicionadas à tabela Conjunto para importação.
    400 Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
    404 Não encontrado. O item solicitado não foi encontrado.
    409 Conflito. O anexo já existe na fonte de dados.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.
    501 Não implementado. O formato de solicitação não é compatível.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    erro Descreve um erro encontrado.

    Tipo de dados: objeto

    "error": {
  "details": "String",
  "message": "String"
}
    detalhes.erro Informações adicionais sobre o erro.

    Tipo de dados: cadeia de caracteres
    mensagem.erro Mensagem descrevendo o erro.

    Tipo de dados: cadeia de caracteres
    import_set Nome da tabela de conjunto de importação à qual a carga foi anexada.

    Tipo de dados: cadeia de caracteres
    contagem_de_linhas_preparada Número de linhas anexadas à tabela Conjunto para importação.

    Tipo de dados: número
    preparação_tabela Nome do registro da fonte de dados usado para preparar a carga.

    Tipo de dados: cadeia de caracteres
    status Status de erro.

    Tipo de dados: cadeia de caracteres

    Amostra de solicitação cURL

    curl "instance.service-now.com/api/now/cmdb/ingest/4dd9686d1b9800103d374087bc4bcb3d" \
--request POST \
--header "Accept: application/json" \
--header "Content-Type:application/json" \
--data "{\"records\":[{\"hostname\": \"Hostname1\", \"serialnumber\": \"2acd3873-7fc5-454c-8844-e7769e4d6cfc\", \"model\": \"Model 5100"},{\"vendor\": \"ABC Co\"},
{\"hostname\": \"Hostname2\", \"serialnumber\": \"3adb3873-7fc5-564d-8844-e7769e4d6ded\", \"model\": \"Model 5200"},{\"vendor\": \"ACME Co\"}]}"
--user "username":"password"

    Resposta bem-sucedida:

    {
  "result": {
    "staged_row_count": 2,
    "import_set": "ISET0010010",
    "staging_table": "sn_my_demo_integra_demo_data_source_01"
  }
}