API du flux de données de mesure DCIM

Référence de l’API Zurich

Release

zurich

ft:locale

fr-FR

ft:publication_title

Référence de l’API Zurich

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

API du flux de données de mesure DCIM

Rversion finale: Zurich

Mis à jour 31 juil. 2025

9 minutes de lecture

L’API de flux de données de mesure DCIM fournit un point de terminaison pour accepter les données de mesure DCIM (Data Center Infrastructure Management) provenant d’un système externe et stocker les données dans une MetricBase base de données.

Cette API reçoit des données de mesure en temps quasi réel telles que la température, l’humidité et la consommation d’énergie.

Cette API peut être étendue pour une utilisation avec un système externe choisi en implémentant le point d’extension scripté TNIDCIMFeedParser. L’implémentation par défaut TNIDCIMFeedEquinixParser peut être utilisée comme exemple. Pour plus d’informations sur les points d’extension, reportez-vous à la section Utilisation de points d'extension pour étendre les fonctionnalités de l'application.

Cette API est incluse dans l’application Network Inventory Advanced, disponible sur le ServiceNow Store. Cette API nécessite également le MetricBase plugin (com.snc.clotho).

L’utilisateur appelant doit disposer du rôle sn_ni_adv.metric_integrator.

Flux de données de mesures DCIM : POST /sn_ni_adv/dcim/feed/{vendorname}

Stocke des données métriques telles que la température, l’humidité et la consommation d’énergie dans MetricBase.

Par défaut, ce point de terminaison peut être utilisé pour stocker des données sur les types d’éléments de configuration (CI) suivants :

Circuit [cmdb_ci_circuit]
Cabinet [cmdb_ci_container_cabinet]
Cage [cmdb_ci_cage]
Centre de données [cmdb_ci_datacenter]
Zone de centre de données [cmdb_ci_zone]

Pour utiliser ce point de terminaison avec des types de CI supplémentaires, créez des définitions de mesures et implémentez le point d’extension scripté TNIDCIMFeedParser.

Format d'URL

URL par défaut : /api/sn_ni_adv/dcim/feed/{vendorname}

Paramètres de demande pris en charge

Tableau 1. Paramètres de chemin d'accès
Nom	Description
nom du fournisseur	Nom du système externe à partir duquel recevoir les données de mesure. Lors de l’utilisation de l’implémentation par défaut de cette API, cette valeur est `equinix`. Lorsque vous utilisez cette API avec d’autres systèmes externes, les vendorname éléments utilisés ici doivent être inclus dans votre implémentation du point d’extension TNIDCIMFeedParser . Type de données : chaîne

Tableau 2. Paramètres de requête
Nom	Description
Aucun

Tableau 3. Paramètres du corps de la demande (JSON)
Nom	Description
données	Requis. Données à stocker dans .MetricBase Type de données : objet Remarque : Les éléments qui doivent être inclus dans cet objet varient en fonction du paramètre et du type type d’élément de configuration, tel que centre de données ou circuit. `"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} }`
données.puissanceapparente	Données de puissance apparente en kilovolts-ampères. Requis lorsque le paramètre est `l’alimentation`type. Type de données : objet `"apparentPower": { "unit": "String", "value": "String" }`
données.puissanceapparente.unité	Unité de mesure. La seule valeur acceptée est `kVA.` Type de données : chaîne
données.puissanceapparente.valeur	La lecture enregistrée en kilovolts-ampères. Type de données : chaîne
Données.Actif	Données de l’actif. Requis pour les circuits lorsque le paramètre est `la puissance mesurée` ou la type`puissance`. Requis pour les armoires, les cages et les zones lorsque le type paramètre est `environnemental`. Type de données : objet `"asset": { "id": "String", "level": "String", "type": "String" }`
data.asset.id	Nom de l'actif. Table : circuit [cmdb_ci_circuit], armoire [cmdb_ci_container_cabinet], cage [cmdb_ci_cage] ou zone de centre de données [cmdb_ci_zone] Champ : Nom Type de données : chaîne
Niveau.Actif.Données	Type d'actif. Utilisé pour les armoires, les cages et les zones. Valeurs possibles : CABINET CAGE ZONE Type de données : chaîne
données.actif.type	Type d'actif. Utilisé pour les circuits. La seule valeur acceptée est `CIRCUIT.` Type de données : chaîne
data.cabinet	Nom de l’armoire. Requis pour les armoires lorsque le paramètre est `la puissance mesurée` ou `la`type puissance. Table : Armoire de conteneur [cmdb_ci_container_cabinet] Champ : Nom Type de données : chaîne
data.cabinetRating	La consommation d’énergie de l’armoire est évaluée en kilovolts-ampères. Requis lorsque le paramètre est `l’alimentation`type. Type de données : objet `"cabinetRating": { "unit": "String", "value": "String" }`
data.cabinetRating.unit	Unité de mesure. La seule valeur acceptée est `kVA.` Type de données : chaîne
data.cabinetRating.value	La consommation d’énergie de l’armoire. Type de données : chaîne
data.cage	Nom de la cage. Requis pour les cages lorsque le type paramètre est `mesuré - puissance` ou `puissance`. Table : Cage [cmdb_ci_cage] Champ : Nom Type de données : chaîne
données.contractualPouvoir	Consommation d’énergie allouée par le contrat en kilovolts-ampères. Requis lorsque le paramètre est `l’alimentation`type. Type de données : objet `"contractualPower": { "unit": "String", "value": "String" }`
data.contractualPower.unit	Unité de mesure. La seule valeur acceptée est `kVA.` Type de données : chaîne
données.puissancecontractuelle.valeur	La consommation d’énergie allouée par le contrat. Type de données : chaîne
données.ibx	Nom du centre de données. Requis lors du stockage de données de mesures pour un centre de données. Table : Centre de données [cmdb_ci_datacenter] Type de données : chaîne
données.kilowattheure	Données de consommation d’énergie en kilowattheures. Requis lorsque le type paramètre est `dosé-puissance`. Type de données : objet `"kilowattHour": { "unit": "String", "value": "String" }`
données.kilowattheure.unité	Unité de mesure. La seule valeur acceptée est `kWh`. Type de données : chaîne
données.kilowattheure.valeur	Kilowattheures enregistrés. Type de données : chaîne
data.peakLastSevenDays	La consommation maximale d’énergie au cours de la dernière semaine en kilovolts-ampères. Requis lorsque le paramètre est `l’alimentation`type. Type de données : objet `"peakLastSevenDays": { "unit": "String", "value": "String" }`
data.peakLastSevenDays.unit	Unité de mesure. La seule valeur acceptée est `kVA.` Type de données : chaîne
data.peakLastSevenDays.value	La valeur d’utilisation maximale de l’énergie de la dernière semaine. Type de données : chaîne
data.peakLastSevenDaysRatio	Pourcentage maximal d’énergie utilisée par rapport à la quantité allouée par le contrat au cours de la dernière semaine. Requis lorsque le paramètre est `l’alimentation`type. Type de données : objet `"peakLastSevenDaysRatio": { "unit": "String", "value": "String" }`
data.peakLastSevenDaysRatio.unit	Unité de mesure. La seule valeur acceptée est `POURCENTAGE.` Type de données : chaîne
data.peakLastSevenDaysRatio.value	Pourcentage maximal de puissance utilisée. Type de données : chaîne
data.powerConsumptionToContractual	Pourcentage de puissance utilisée par rapport à la quantité allouée par le contrat. Requis lorsque le paramètre est `l’alimentation`type. Type de données : objet `"powerConsumptionToContractual": { "unit": "String", "value": "String" }`
data.powerConsumptionToContractual.unit	Unité de mesure. La seule valeur acceptée est `POURCENTAGE.` Type de données : chaîne
data.powerConsumptionToContractual.value	Pourcentage de puissance utilisée. Type de données : chaîne
data.powerFactor	Données sur le facteur de puissance. Requis lorsque le paramètre est `l’alimentation`type. Type de données : objet `"powerFactor": { "unit": "String", "value": "String" }`
données.facteurpuissance.unité	Unité de mesure. La seule valeur acceptée est `pf`. Type de données : chaîne
données.powerFactor.valeur	La valeur du facteur de puissance. Type de données : chaîne
data.reading	Les données environnementales collectées. Requis lorsque le type paramètre est `environnemental`. Type de données : objet `"reading": { "unit": "String", "value": "String" }`
unité.lecture.données	Unité de mesure. Valeurs possibles : `CELSIUS :` Utilisé quand data.tag.id est `la température`. `POURCENTAGE` : Utilisé quand data.tag.id`c’est de l’humidité`. Type de données : chaîne
valeur.lecture.données	Valeur enregistrée. Type de données : chaîne
data.readingTime	Requis. Date et heure auxquelles les données ont été collectées. Cette valeur doit être au format UTC au format ISO 8601. Par exemple, `2025-07-03T16:22:15.000Z`. Type de données : chaîne
data.realPower	Données de consommation électrique en kilowatts. Requis lorsque le paramètre est `l’alimentation`type. Type de données : objet `"realPower": { "unit": "String", "value": "String" }`
données.puissance.réelle unité	Unité de mesure. La seule valeur acceptée est `kW`. Type de données : chaîne
données.puissanceréelle.valeur	La lecture des kilowatts enregistrés. Type de données : chaîne
données.soldactuelles	Courant électrique alloué par le contrat en ampères. Requis lorsque le paramètre est `l’alimentation`type. Type de données : objet `"soldCurrent": { "unit": "String", "value": "String" }`
données.soldes.actuelle.unité	Unité de mesure. La seule valeur acceptée est `A`. Type de données : chaîne
données.soldes.valeur.actuelle	Courant électrique alloué par le contrat. Type de données : chaîne
balise.données	Objet contenant le type de données environnementales. Requis lorsque le type paramètre est `environnemental`. Type de données : objet `"tag": { "id": "String" }`
data.tag.id	Type de données environnementales. Valeurs possibles : humidité température Type de données : chaîne
type	Requis. Type de données de mesure. Valeurs possibles : `environnemental` : utilisé pour l’humidité ou la température. puissance `mesurée` : utilisée pour la consommation d’énergie en kilowattheures (kWh). `puissance` : Utilisé pour la consommation d’énergie en kilowatts (kW) et en kilovolts-ampères (kVA). Type de données : chaîne

En-têtes

Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

Tableau 4. En-têtes de demandes
En-tête	Description
Accepter	Format de données du corps de la réponse. Prend uniquement en charge application/json;charset=UTF-8.
Autorisation	Basique.
Content-Type	Format de données du corps de la demande. Prend uniquement en charge application/json.

Tableau 5. En-têtes de réponses
En-tête	Description
Type de contenu	Format de données du corps de la réponse. Prend uniquement en charge application/json;charset=UTF-8.

Codes d'état

Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

Tableau 6. Codes d'état
Code d'état	Description
200	Réussi. La demande a été correctement traitée.
400	Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté.
401	Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises.
403	Interdit. L’utilisateur ne dispose pas des droits d’accès à l’enregistrement spécifié.
404	Introuvable. L’élément demandé est introuvable.
429	Trop de demandes.
500	Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur.

Paramètres de corps de réponse (JSON)


Nom	Description
résultat	Détails sur la demande. Type de données : objet `"result": { "status": "String", "sys_id": "String" }`
résultat.état	État de la demande. Type de données : chaîne
result.sys_id	Sys_id du CI mis à jour avec les données de mesure. Table : Circuit [cmdb_ci_circuit], Armoire [cmdb_ci_container_cabinet], Cage [cmdb_ci_cage], Centre de données [cmdb_ci_datacenter] ou Zone de centre de données [cmdb_ci_zone] Type de données : chaîne

Demande cURL

Stocke les données de puissance mesurée pour un centre de données.

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'

Corps de la réponse.

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

Demande cURL

Stocke les données d’alimentation d’un circuit.

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'

Corps de la réponse.

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

Demande cURL

Stocke les données de température d’une zone.

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'

Corps de la réponse.

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

Demande cURL

Stocke les données d’humidité d’une armoire.

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'

Corps de la réponse.

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