CMDB API de ingestão de dados

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

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

    Aviso:
    Esta API não é mais recomendada. Para obter a mesma funcionalidade com escalabilidade e estabilidade aprimoradas, use Conjunto de importação - POST /now/import/stagingTableName/insertMultipleendpoint. Em Quebecversão em diante, qualquer uso do API de ingestão de dados do CMDB deve ser migrado para usar o. Conjunto de importação - insertMultiple em vez disso, endpoint.

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

    Esta API é ativada por meio de 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 de importação associada ao registro da fonte de dados identificado pelo sys_id aprovado.

    Aviso:
    Esta API não é mais recomendada. Para obter a mesma funcionalidade com escalabilidade e estabilidade aprimoradas, use Conjunto de importação - POST /now/import/stagingTableName/insertMultipleendpoint. Em Quebecversão em diante, qualquer uso do API de ingestão de dados do CMDB deve ser migrado para usar o. Conjunto de importação - insertMultiple em vez disso, endpoint.

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

    O corpo da solicitação deve conter a matriz JSON de objetos (carga) para inserir na tabela Conjunto de importação. Cada objeto equivale a uma linha na tabela, cada par nome-valor equivale a uma coluna. A carga JSON deve aproveitar os nomes de campo do conjunto de 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 de importação existir, o endpoint anexará as linhas (objetos) à tabela Conjunto de importação existente. Nenhuma verificação de duplicatas ou atualização de registros existentes é realizada.

    Se você estiver criando inicialmente uma aplicação, primeiro crie 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 de importação existente, não será necessário criar o registro da fonte de dados, mas você deve conhecer seu sys_id. O registro da fonte de dados descreve a tabela Conjunto de importação na qual inserir a carga especificada. 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 Fontes de dados .

    Se a tabela Conjunto de importação definida no registro da fonte de dados não existir, o endpoint anexará a carga transmitida ao registro da fonte de dados. Para criar a tabela do 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 associada, clique em Carregar 20 registros de carga de teste ou Carregar todos os registros Link 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 pares nome-valor forem passados posteriormente que não existam na tabela Conjunto de importação, eles serão ignorados sem aviso. Se você precisar modificar as colunas na tabela Conjunto de importação, poderá adicioná-las manualmente à tabela. Você também pode excluir ou renomear a tabela Conjunto de 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 de URL

    URL com controle de versão: /api/now//cmdb/ingest/(data_source_sys_id)

    URL padrão: /api/now/cmdb/ingest/

    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
    data_source_sys_id Sys_id do registro da fonte de 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
    Matriz Matriz de forma livre de objetos que descrevem os dados a serem anexados à tabela Conjunto de importação associada. Cada objeto na matriz define uma linha na tabela Conjuntos de importação; cada nome-valor combina uma coluna.
    Nota:
    Esta matriz deve ser nomeada, como "Registros":["hostname": "Hostname1", "número de série": "2acd3873-7fc5-454c-8844-e7769e4d6cfc", "model": "ID do modelo", "fornecedor": "Co"] .

    Tipo de dados: Matriz de objetos

    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
    Tipo de conteúdo Formato de dados do corpo da solicitação. 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
    201 Criado. Um anexo foi adicionado à fonte de dados.
    202 Aceito. Linhas foram adicionadas à tabela Conjunto de importação.
    400 Solicitação Incorreta. Um tipo de solicitação incorreto ou uma solicitação malformada foi detectada.
    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"
}
    error.details 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 do conjunto de importação à qual a carga foi anexada.

    Tipo de dados: Cadeia de caracteres
    staged_row_count Número de linhas anexadas à tabela Conjunto de importação.

    Tipo de dados: Número
    staging_table Nome do registro da fonte de dados usado para preparar a carga.

    Tipo de dados: Cadeia de caracteres
    status Status do erro.

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl de amostra

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