API do Feed de dados de métrica DCIM

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 9 min. de leitura

    • . Feed de dados de métrica DCIM A API fornece um endpoint para aceitar dados de métrica de Gestão de infraestrutura de datacenter (DCIM) de um sistema externo e armazenar os dados em um MetricBase banco de dados.

    Esta API recebe dados de métrica quase em tempo real, como temperatura, umidade e uso de energia.

    Esta API pode ser estendida para uso com um sistema externo escolhido implementando o ponto de extensão com script TNIDCIMFeedParser . A implementação padrão TNIDCIMFeedEquinixParser pode ser usado como exemplo. Para obter mais informações sobre pontos de extensão, consulte Usando pontos de extensão para estender a funcionalidade da aplicação.

    Esta API está incluída na aplicação Inventário de rede avançado, que está disponível no ServiceNow Store. Esta API também requer o. MetricBase plug-in (com.snc.clotho).

    O usuário chamador deve ter a função sn_ni_adv.metric_integrator.

    Feed de dados de métrica DCIM - POST /sn_ni_adv/dcim/feed/

    Armazena dados de métrica, como temperatura, umidade e uso de energia em MetricBase.

    Por padrão, este endpoint pode ser usado para armazenar dados sobre os seguintes tipos de itens de configuração (ICs):
    • Circuito [cmdb_ci_circle]
    • Gabinete [cmdb_ci_container_cabinet]
    • Gaiola [cmdb_ci_cage]
    • Datacenter [cmdb_ci_datacenter]
    • Zona do datacenter [cmdb_ci_zone]

    Para usar este endpoint com tipos de IC adicionais, criar definições de métrica e implementam o ponto de extensão com script TNIDCIMFeedParser .

    Formato de URL

    URL padrão: /api/sn_ni_adv/dcim/feed/

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    nome do fornecedor Nome do sistema externo do qual receber dados de métrica.

    Ao usar a implementação padrão desta API, este valor é equledge . Ao usar esta API com outros sistemas externos, o. vendornameusado aqui deve ser incluído em sua implementação do TNIDCIMFeedParser ponto de extensão.

    Tipo de dados: Cadeia de caracteres
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 3. Solicitar parâmetros do corpo (JSON)
    Nome Descrição
    dados Obrigatório. Os dados a serem armazenados MetricBase.

    Tipo de dados: Objeto

    Nota:
    Os elementos que devem ser incluídos neste objeto variam de acordo com typee o tipo de item de configuração, como datacenter ou circuito.
    "data": {
   "apparentPower": {Object},
   "asset": {Object},
   "cabinet": "String",
   "cabinetRating": {Object},
   "cage": "String",
   "contractualPower": {Object},
   "ibx": "String",
   "kilowattHour": {Object},
   "peakLastSevenDays": {Object},
   "peakLastSevenDaysRatio": {Object},
   "powerConsumptionToContractual": {Object},
   "powerFactor": {Object},
   "reading": {Object},
   "readingTime": "String",
   "realPower": {Object},
   "soldCurrent": {Object},
   "tag": {Object}
}
    Data.apparentPower Dados de potência aparente em quilovolts-amperes. Necessário quando typeo parâmetro é energia .

    Tipo de dados: Objeto

    "apparentPower": {      
   "unit": "String",
   "value": "String"  
}
    Data.apparentPower.unit Unidade de medida. O único valor aceito é KVA .

    Tipo de dados: Cadeia de caracteres
    Data.apparentPower.Value A leitura de quilovolts-amperes registada.

    Tipo de dados: Cadeia de caracteres
    data.asset Dados do ativo. Necessário para circuitos quando typeo parâmetro é potência medida ou energia . Necessário para gabinetes, gaiolas e zonas quando typeo parâmetro é ambiental .

    Tipo de dados: Objeto

    "asset": {
   "id": "String",
   "level": "String",
   "type": "String"
}
    data.asset.id Nome do ativo.

    Tabela: Circuito [cmdb_ci_circle], Gabinete [cmdb_ci_container_cabinet], Cage [cmdb_ci_cage] ou Zona do datacenter [cmdb_ci_zone]

    Campo: Nome

    Tipo de dados: Cadeia de caracteres
    ativo.data.nível.ativo Tipo de ativo. Usado para armários, gaiolas e zonas.
    Valores possíveis:
    • GABINETE
    • GAIOLA
    • ZONA

    Tipo de dados: Cadeia de caracteres
    ativo.tipo.data Tipo de ativo. Usado para circuitos. O único valor aceito é CIRCUITO .

    Tipo de dados: Cadeia de caracteres
    data.cabinet Nome do gabinete. Necessário para gabinetes quando typeo parâmetro é potência medida ou energia .

    Tabela: Gabinete do contêiner [cmdb_ci_container_cabinet]

    Campo: Nome

    Tipo de dados: Cadeia de caracteres
    data.cabinetRating Uso de energia para a qual o gabinete está classificado em quilovolts-amperes. Necessário quando typeo parâmetro é energia .

    Tipo de dados: Objeto

    "cabinetRating": {      
   "unit": "String",
   "value": "String"  
}
    data.cabinetRating.unit Unidade de medida. O único valor aceito é KVA .

    Tipo de dados: Cadeia de caracteres
    data.cabinetRating.value A classificação de uso de energia do gabinete.

    Tipo de dados: Cadeia de caracteres
    data.cage Nome da gaiola. Necessário para jages quando typeo parâmetro é potência medida ou energia .

    Tabela: Cage [cmdb_ci_cage]

    Campo: Nome

    Tipo de dados: Cadeia de caracteres
    Dados.ContractualPower Consumo de energia alocado pelo contrato em quilovolts-amperes. Necessário quando typeo parâmetro é energia .

    Tipo de dados: Objeto

    "contractualPower": {      
   "unit": "String",
   "value": "String"  
}
    Power.contractualPower.unit Unidade de medida. O único valor aceito é KVA .

    Tipo de dados: Cadeia de caracteres
    Data.ContractualPower.Value O uso de energia alocado pelo contrato.

    Tipo de dados: Cadeia de caracteres
    data.ibx Nome do datacenter.

    Necessário ao armazenar dados de métrica para um datacenter.

    Tabela: Datacenter [cmdb_ci_datacenter]

    Tipo de dados: Cadeia de caracteres
    KilowattHora Dados de uso de energia em quilowatts-hora. Necessário quando typeo parâmetro é potência medida .

    Tipo de dados: Objeto

    "kilowattHour": {      
   "unit": "String",
   "value": "String"  
}
    Data.quilowattHour.unit Unidade de medida. O único valor aceito é KWH .

    Tipo de dados: Cadeia de caracteres
    Data.quilowatHora.Valor A leitura de quilowatts-hora registrada.

    Tipo de dados: Cadeia de caracteres
    Data.peakLastSevenDays O consumo máximo de energia na última semana em quilovolts-amperes. Necessário quando typeo parâmetro é energia .

    Tipo de dados: Objeto

    "peakLastSevenDays": {      
   "unit": "String",
   "value": "String"  
}
    Data.peakLastSevenDays.unit Unidade de medida. O único valor aceito é KVA .

    Tipo de dados: Cadeia de caracteres
    Data.peakLastSevenDays.value O valor máximo de uso de energia da última semana.

    Tipo de dados: Cadeia de caracteres
    Data.peakLastSevenDaysRatio A porcentagem máxima de energia usada do valor alocado pelo contrato na última semana. Necessário quando typeo parâmetro é energia .

    Tipo de dados: Objeto

    "peakLastSevenDaysRatio": {      
   "unit": "String",
   "value": "String"  
}
    Data.peakLastSevenDaysRatio.unit Unidade de medida. O único valor aceito é PERCENTUAL .

    Tipo de dados: Cadeia de caracteres
    Data.peakLastSevenDaysRatio.Value A porcentagem máxima de energia usada.

    Tipo de dados: Cadeia de caracteres
    PowerConsumptionToContratual Percentual de energia usada do valor alocado pelo contrato. Necessário quando typeo parâmetro é energia .

    Tipo de dados: Objeto

    "powerConsumptionToContractual": {      
   "unit": "String",
   "value": "String"  
}
    Data.powerConsumptionToContratual.unit Unidade de medida. O único valor aceito é PERCENTUAL .

    Tipo de dados: Cadeia de caracteres
    Data.powerConsumptionToContratual.Value O percentual de energia usada.

    Tipo de dados: Cadeia de caracteres
    Data.powerFactor Dados do fator de potência. Necessário quando typeo parâmetro é energia .

    Tipo de dados: Objeto

    "powerFactor": {      
   "unit": "String",
   "value": "String"  
}
    Data.powerFactor.unit Unidade de medida. O único valor aceito é pf .

    Tipo de dados: Cadeia de caracteres
    Data.PowerFactor.Value O valor do fator de potência.

    Tipo de dados: Cadeia de caracteres
    data.reading Os dados ambientais coletados. Necessário quando typeo parâmetro é ambiental .

    Tipo de dados: Objeto

    "reading": {      
   "unit": "String",
   "value": "String"  
}
    unidade.leitura.dados Unidade de medida.
    Valores possíveis:
    • CELSIUS : Usado quando data.tag.id. temperatura .
    • PERCENTUAL : Usado quando data.tag.id. umidade .

    Tipo de dados: Cadeia de caracteres
    valor.data.reading.value O valor registrado.

    Tipo de dados: Cadeia de caracteres
    ReadingTime Obrigatório. Data e hora em que os dados foram coletados.

    Este valor deve estar em UTC no formato ISO 8601. Por exemplo, 2025-07-03T16:22:15.000Z .

    Tipo de dados: Cadeia de caracteres
    RealPower Dados de consumo de energia em quilowatts. Necessário quando typeo parâmetro é energia .

    Tipo de dados: Objeto

    "realPower": {      
   "unit": "String",
   "value": "String"  
}
    Power.realPower.unit Unidade de medida. O único valor aceito é KW .

    Tipo de dados: Cadeia de caracteres
    RealPower.Valor.realPower A leitura de quilowatts registada.

    Tipo de dados: Cadeia de caracteres
    Data.soldAtual Corrente elétrica atribuída pelo contrato em amperes. Necessário quando typeo parâmetro é energia .

    Tipo de dados: Objeto

    "soldCurrent": {      
   "unit": "String",
   "value": "String"  
}
    Data.soldCurrent.unit Unidade de medida. O único valor aceito é . .

    Tipo de dados: Cadeia de caracteres
    Data.soldCurrent.Value A corrente elétrica alocada pelo contrato.

    Tipo de dados: Cadeia de caracteres
    data.tag Objeto que contém o tipo de dados ambientais. Necessário quando typeo parâmetro é ambiental .

    Tipo de dados: Objeto

    "tag": {
   "id": "String"
}
    data.tag.id O tipo de dados ambientais.
    Valores possíveis:
    • umidade
    • temperatura

    Tipo de dados: Cadeia de caracteres
    tipo Obrigatório. Tipo de dados de métrica.
    Valores possíveis:
    • ambiental : Usado para umidade ou temperatura.
    • potência medida : Usado para uso de energia em quilowatts-hora (kwh).
    • energia : Usado para uso de energia em quilowatts (kW) e quilovolts-amperes (kVA).

    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 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Oferece suporte somente a application/json;charset=UTF-8.
    Autorização Básico.
    Tipo de conteúdo Formato de dados do corpo da solicitação. Oferece suporte somente a application/json.
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Tipo de conteúdo Formato de dados do corpo da resposta. Oferece suporte somente a application/json;charset=UTF-8.

    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.
    400 Solicitação Incorreta. Um tipo de solicitação incorreto ou uma solicitação malformada foi detectada.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido. O usuário não tem direitos de acesso ao registro especificado.
    404 Não encontrado. O item solicitado não foi encontrado.
    429 Excesso de solicitações.
    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)

    Nome Descrição
    resultado Detalhes sobre a solicitação.

    Tipo de dados: Objeto

    "result": {
   "status": "String",
   "sys_id": "String"
}
    result.status Status da solicitação.

    Tipo de dados: Cadeia de caracteres
    sys_id.result.sys_id Sys_id do IC atualizado com os dados da métrica.

    Tabela: Circuito [cmdb_ci_circle], Gabinete [cmdb_ci_container_cabinet], Cage [cmdb_ci_cage], Datacenter [cmdb_ci_datacenter] ou Zona do datacenter [cmdb_ci_zone]

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    Armazena dados de energia medida para um datacenter.

    curl "https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    "type": "metered-power",
    "data": {
        "ibx": "Datacenter Name",
        "kilowattHour": {
            "value": "40509.323",
            "unit": "kWh"
        },
        "readingTime": "2025-07-03T16:22:15.000Z"
    }
}" \
--user 'username':'password'

    Corpo da resposta.

    {
    "result": {
        "status": "success",
        "sys_id": "c88dde85ff2662109cb9ffffffffffcc"
    }
}

    Solicitação de curl

    Armazena dados de energia para um circuito.

    curl "https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    "type": "power",
    "data": {
        "asset": {
            "id": "Circuit Name",
            "type": "CIRCUIT"
        },
        "realPower": {
            "value": "0.522",
            "unit": "kW"
        },
        "apparentPower": {
            "value": "1.070",
            "unit": "kVA"
        },
        "contractualPower": {
            "value": "60.000",
            "unit": "kVA"
        },
        "powerFactor": {
            "value": "0.48",
            "unit": "pf"
        },
        "soldCurrent": {
            "value": "15.000",
            "unit": "A"
        },
        "powerConsumptionToContractual": {
            "value": "32.151",
            "unit": "PERCENT"
        },
        "cabinetRating": {
            "value": "123.300",
            "unit": "kVA"
        },
        "peakLastSevenDays": {
            "value": "1.146",
            "unit": "kVA"
        },
        "peakLastSevenDaysRatio": {
            "value": "34.424",
            "unit": "PERCENT"
        },
        "readingTime": "2025-07-03T16:22:15.000Z"
    }
}" \
--user 'username':'password'

    Corpo da resposta.

    {
    "result": {
        "status": "success",
        "sys_id": "c67dbe45fc2662109cb9ffffffffffcd"
    }
}

    Solicitação de curl

    Armazena dados de temperatura de uma zona.

    curl "https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    "type": "environmental",
    "data": {
        "asset": {
            "id": "Zone Name",
            "level": "ZONE"
        },
        "reading": {
            "value": "23.300",
            "unit": "CELSIUS"
        },
        "tag": {
            "id": "temperature"
        },
        "readingTime": "2025-07-03T16:22:15.000Z"
    }
}" \
--user 'username':'password'

    Corpo da resposta.

    {
    "result": {
        "status": "success",
        "sys_id": "c64dbc42fe2862109cb9ffffffffffed"
    }
}

    Solicitação de curl

    Armazena dados de umidade para um gabinete.

    curl "https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    "type": "environmental",
    "data": {
        "asset": {
            "id": "Test Cabinet",
            "level": "CABINET"
        },
        "reading": {
            "value": "66.120",
            "unit": "PERCENT"
        },
        "tag": {
            "id": "humidity"
        },
        "readingTime": "2025-07-03T16:22:15.000Z"
    }
}" \
--user 'username':'password'

    Corpo da resposta.

    {
    "result": {
        "status": "success",
        "sys_id": "c24dbc82fe3862107cb9ffffffffffbc"
    }
}