DCIM メトリクスデータフィード API

Zurich API リファレンス

Release

zurich

ft:locale

ja-JP

ft:publication_title

Zurich API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

DCIM メトリクスデータフィード API

リリースバージョン: Zurich

更新日 2025年07月31日

所要時間：17分

DCIM メトリクスデータフィード API は、外部システムからデータセンターインフラストラクチャ管理 (DCIM) メトリクスデータを受け取り、そのデータをメトリックベースデータベースに保存するためのエンドポイントを提供します。

この API は、温度、湿度、電力使用量などのほぼリアルタイムのメトリクスデータを受信します。

この API は、スクリプト拡張ポイント TNIDCIMFeedParser を実装することで、選択した外部システムで使用するために拡張できます。例として、デフォルト実装の TNIDCIMFeedEquinixParser を使用できます。拡張ポイントの詳細については、「拡張ポイントを使用してアプリケーション機能を拡張する」を参照してください。

この API は、 ServiceNow Store で利用可能な Network Inventory Advanced アプリケーションに含まれています。この API には、メトリックベースプラグイン (com.snc.clotho) も必要です。

呼び出し元ユーザーには、sn_ni_adv.metric_integrator ロールが必要です。

DCIM メトリクスデータフィード:POST /sn_ni_adv/dcim/feed/{vendorname}

温度、湿度、電力使用量などのメトリクスデータをメトリックベースに保存します。

デフォルトでは、このエンドポイントを使用して、次のタイプの構成アイテム (CI) に関するデータを保存できます。

回路 [cmdb_ci_circuit]
キャビネット [cmdb_ci_container_cabinet]
ケージ [cmdb_ci_cage]
Data Center [cmdb_ci_datacenter]
データセンターゾーン [cmdb_ci_zone]

このエンドポイントを追加の CI タイプとともに使用するには、メトリクスの定義を作成し、スクリプト化された拡張ポイント TNIDCIMFeedParser を実装します。

URL 形式

デフォルト URL: /api/sn_ni_adv/dcim/feed/{vendorname}

サポートされている要求パラメーター

表 : 1. パスパラメーター
名前	説明
ベンダー名	メトリクスデータを受信する外部システムの名前。この API のデフォルト実装を使用する場合、この値は `equinix` です。この API を他の外部システムで使用する場合は、ここで使用する vendorname を TNIDCIMFeedParser 拡張ポイントの実装に含める必要があります。データタイプ：文字列

表 : 2. クエリパラメーター
名前	説明
なし

表 : 3. 要求本文パラメーター (JSON)
名前	説明
データ	必須。メトリックベースに保存するデータ。データタイプ: オブジェクト注: このオブジェクトに含める必要がある要素は、 type パラメーターと構成アイテムタイプ (データセンターや回路など) によって異なります。 `"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	キロボルトアンペア単位の皮相電力データ。typeパラメーターが`べき乗`の場合は必須です。データタイプ: オブジェクト `"apparentPower": { "unit": "String", "value": "String" }`
data.apparentPower.unit	測定単位。許可される値は `kVA` のみです。データタイプ：文字列
data.apparentPower.value	記録されたキロボルトアンペアの読み取り値。データタイプ：文字列
data.asset	資産データ。typeパラメータが`従量制電力`または`電力`の回路に必要です。typeパラメーターが`環境パラメータ`である場合、キャビネット、ケージ、およびゾーンに必要です。データタイプ: オブジェクト `"asset": { "id": "String", "level": "String", "type": "String" }`
data.asset.id	資産の名前。テーブル:回路 [cmdb_ci_circuit]、キャビネット [cmdb_ci_container_cabinet]、ケージ [cmdb_ci_cage]、またはデータセンターゾーン [cmdb_ci_zone] フィールド:名前データタイプ：文字列
data.asset.level	資産の種類。キャビネット、ケージ、およびゾーンに使用されます。可能な値：内閣籠ゾーンデータタイプ：文字列
data.asset.type	資産の種類。回路に使用されます。許可される値は `CIRCUIT` のみです。データタイプ：文字列
data.cabinet	キャビネットの名前。typeパラメーターが`従量制電力`または`電力`である場合、キャビネットに必要です。テーブル:コンテナキャビネット [cmdb_ci_container_cabinet] フィールド:名前データタイプ：文字列
data.cabinetRating	キャビネットの定格電力使用量はキロボルトアンペアです。typeパラメーターが`べき乗`の場合は必須です。データタイプ: オブジェクト `"cabinetRating": { "unit": "String", "value": "String" }`
data.cabinetRating.unit	測定単位。許可される値は `kVA` のみです。データタイプ：文字列
data.cabinetRating.value	キャビネットの電力使用量定格。データタイプ：文字列
data.cage	ケージの名前。typeパラメーターが`従量制電力`または`電力`である場合、ケージに必要です。テーブル:ケージ [cmdb_ci_cage] フィールド:名前データタイプ：文字列
data.contractualPower	契約によって割り当てられた電力使用量 (キロボルトアンペア)。typeパラメーターが`べき乗`の場合は必須です。データタイプ: オブジェクト `"contractualPower": { "unit": "String", "value": "String" }`
data.contractualPower.unit	測定単位。許可される値は `kVA` のみです。データタイプ：文字列
data.contractualPower.value	契約によって割り当てられた電力使用量。データタイプ：文字列
data.ibx	データセンターの名前。データセンターのメトリクスデータを保存する場合は必須です。テーブル:データセンター [cmdb_ci_datacenter] データタイプ：文字列
data.kilowattHour	電力使用量データ (キロワット時)typeパラメーターが`従量制電力`の場合は必須です。データタイプ: オブジェクト `"kilowattHour": { "unit": "String", "value": "String" }`
data.kilowattHour.unit	測定単位。指定できる値は `kWh` のみです。データタイプ：文字列
data.kilowattHour.value	記録されたキロワット時の読み取り値。データタイプ：文字列
data.peakLastSevenDays	過去 1 週間の最大電力使用量 (キロボルトアンペア)。typeパラメーターが`べき乗`の場合は必須です。データタイプ: オブジェクト `"peakLastSevenDays": { "unit": "String", "value": "String" }`
data.peakLastSevenDays.unit	測定単位。許可される値は `kVA` のみです。データタイプ：文字列
data.peakLastSevenDays.value	先週の最大電力使用量の値。データタイプ：文字列
data.peakLastSevenDaysRatio	過去 1 週間以内に契約によって割り当てられた電力のうち使用された電力の最大割合。typeパラメーターが`べき乗`の場合は必須です。データタイプ: オブジェクト `"peakLastSevenDaysRatio": { "unit": "String", "value": "String" }`
data.peakLastSevenDaysRatio.unit	測定単位。許可される値は `PERCENT` のみです。データタイプ：文字列
data.peakLastSevenDaysRatio.value	使用される電力の最大割合。データタイプ：文字列
data.powerConsumptionToContractual	契約によって割り当てられた量に対する電力の使用率。typeパラメーターが`べき乗`の場合は必須です。データタイプ: オブジェクト `"powerConsumptionToContractual": { "unit": "String", "value": "String" }`
data.powerConsumptionToContractual.unit	測定単位。許可される値は `PERCENT` のみです。データタイプ：文字列
data.powerConsumptionToContractual.value	使用された電力の割合。データタイプ：文字列
data.powerFactor	力率データ。typeパラメーターが`べき乗`の場合は必須です。データタイプ: オブジェクト `"powerFactor": { "unit": "String", "value": "String" }`
data.powerFactor.unit	測定単位。許可される値は `pf` のみです。データタイプ：文字列
data.powerFactor.value	力率の値。データタイプ：文字列
data.reading	収集された環境データ。typeパラメーターが`環境パラメーター`の場合は必須です。データタイプ: オブジェクト `"reading": { "unit": "String", "value": "String" }`
data.reading.unit	測定単位。可能な値： `CELSIUS:data.tag.idが温度`の場合に使用されます。 `PERCENT`:`data.tag.id湿度`の場合に使用されます。データタイプ：文字列
data.reading.value	記録された値。データタイプ：文字列
data.readingTime	必須。データが収集された日時。この値は、ISO 8601 形式の UTC である必要があります。例: `2025-07-03T16:22:15.000Z`。データタイプ：文字列
data.realPower	電力使用量データ (キロワット)。typeパラメーターが`べき乗`の場合は必須です。データタイプ: オブジェクト `"realPower": { "unit": "String", "value": "String" }`
data.realPower.unit	測定単位。指定できる値は `kW` のみです。データタイプ：文字列
data.realPower.value	記録されたキロワットの読み取り値。データタイプ：文字列
data.soldCurrent	契約によって割り当てられた電流 (アンペア)。typeパラメーターが`べき乗`の場合は必須です。データタイプ: オブジェクト `"soldCurrent": { "unit": "String", "value": "String" }`
data.soldCurrent.unit	測定単位。指定できる値は `A` のみです。データタイプ：文字列
data.soldCurrent.value	契約によって割り当てられた電流。データタイプ：文字列
data.tag	環境データのタイプを含むオブジェクト。typeパラメーターが`環境パラメーター`の場合は必須です。データタイプ: オブジェクト `"tag": { "id": "String" }`
data.tag.id	環境データのタイプ。可能な値：湿度温度データタイプ：文字列
タイプ	必須。メトリクスデータのタイプ。可能な値： `環境:`湿度または温度に使用されます。 `従量制電力`:キロワット時 (kWh) 単位で電力使用量に使用されます。 `power`:キロワット (kW) およびキロボルトアンペア (kVA) 単位の電力使用量に使用されます。データタイプ：文字列

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 4. 要求ヘッダー
ヘッダー	説明
Accept	応答本文のデータフォーマット。application/json;charset=UTF-8 のみをサポートします。
認証	基本的な。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 5. 応答ヘッダー
ヘッダー	説明
Content-Type	応答本文のデータフォーマット。application/json;charset=UTF-8 のみをサポートします。

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 6. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
401	権限がありません。ユーザー資格情報が間違っているか、渡されていません。
403	禁止されました。ユーザーには、指定されたレコードへのアクセス権がありません。
404	見つかりません。要求されたアイテムが見つかりませんでした。
429	要求が多すぎます。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター (JSON)


名前	説明
結果	要求の詳細。データタイプ: オブジェクト `"result": { "status": "String", "sys_id": "String" }`
result.status	要求のステータス。データタイプ：文字列
result.sys_id	メトリクスデータで更新された CI のSys_id。テーブル:回線 [cmdb_ci_circuit]、キャビネット [cmdb_ci_container_cabinet]、ケージ [cmdb_ci_cage]、データセンター [cmdb_ci_datacenter]、またはデータセンターゾーン [cmdb_ci_zone] データタイプ：文字列

cURL 要求

データセンターの従量制電力データを格納します。

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'

応答本文。

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

cURL 要求

回路の電源データを保存します。

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'

応答本文。

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

cURL 要求

ゾーンの温度データを格納します。

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'

応答本文。

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

cURL 要求

キャビネットの湿度データを保存します。

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'

応答本文。

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