{ "asyncapi": "3.1.0", "info": { "title": "Tensor Energy蓄電池最適化API", "version": "2.8.0", "description": "Tensor Cloud蓄電池最適化サービスの通信プロトコル仕様。EMS端末がMQTTメッセージングを通じてTensor Cloudと通信するための仕様。タイムスタンプ規則：ウィンドウ測定（ウィンドウエネルギーテレメトリ、およびaggregationが 'average' の電力・系統周波数テレメトリ）では、'measurement_ts' は常に値が対象とする期間の開始時刻を表し、終了時刻や中間時刻は表しません。瞬時値のテレメトリでは、測定した時点そのものを表します。出力抑制スケジュールは例外で、TSOが発行したスケジュールの作成時刻、またはEMSがTSOから受信した時刻を表します。", "termsOfService": "https://docs.tensorenergy.jp/legal/terms-of-use/", "externalDocs": { "description": "Tensor Cloud蓄電池最適化ドキュメンテーション", "url": "https://docs.tensorenergy.jp/guides/ems-integration/integrator-guide" }, "contact": { "name": "Tensor Energy", "url": "https://www.tensorenergy.jp" } }, "servers": { "テスト環境": { "host": "mqtt.staging.tensorenergy.jp", "protocol": "mqtt", "protocolVersion": "3.1.1", "description": "テスト用Tensor Cloud MQTTブローカー（AWS IoT Core）", "security": [ { "$ref": "#/components/securitySchemes/awsIotCore" } ] }, "本番環境": { "host": "mqtt.tensorenergy.jp", "protocol": "mqtt", "protocolVersion": "3.1.1", "description": "Tensor Cloud本番MQTTブローカー（AWS IoT Core）", "security": [ { "$ref": "#/components/securitySchemes/awsIotCore" } ] } }, "defaultContentType": "application/json", "channels": { "lifetimeTelemetry": { "address": "dt/{siteId}/{gatewayId}/{metric}/lifetime", "title": "累積エネルギーテレメトリ", "summary": "累積エネルギー（kWh）を公開。Tensor Cloudは累積値かウィンドウ集計値のいずれかを必須（可能なら両方）。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" }, "metric": { "$ref": "#/components/parameters/lifetimeMetric" } }, "messages": { "energyLifetime": { "$ref": "#/components/messages/EnergyLifetime" } } }, "energyTelemetry": { "address": "dt/{siteId}/{gatewayId}/{metric}/energy/{window}", "title": "ウィンドウエネルギーテレメトリ", "summary": "時間ウィンドウあたりのエネルギー（kWh）を公開。累積値かウィンドウ集計値のいずれかを必須（可能なら両方）。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" }, "metric": { "$ref": "#/components/parameters/energyMetric" }, "window": { "$ref": "#/components/parameters/window" } }, "messages": { "energyWindowed": { "$ref": "#/components/messages/EnergyWindowed" } } }, "powerTelemetry": { "address": "dt/{siteId}/{gatewayId}/{metric}/power", "title": "瞬時電力テレメトリ", "description": "瞬時電力（kW）を公開。必須ではないが、高頻度（10分以下）で送信すると推定精度が向上。オフライン監視のリソースが一次調整力を提供する場合、このトピックは一次調整力アセスメントⅡ用の1秒解像度の供出電力も伝送する。すべての一次調整力約定コマについて、meter_export_acとmeter_import_ac（受電点参入）またはbattery_discharge_acとbattery_charge_ac（機器点参入）を1 Hzで公開する。詳細は連携ガイドの「アセスメントⅡ報告」を参照。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" }, "metric": { "$ref": "#/components/parameters/powerMetric" } }, "messages": { "powerInstant": { "$ref": "#/components/messages/PowerInstant" } } }, "stateTelemetry": { "address": "dt/{siteId}/{gatewayId}/{metric}/state", "title": "装置状態テレメトリ", "summary": "装置の瞬間的な動作状態。蓄電池最適化にはSoEと残存容量が必須。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" }, "metric": { "$ref": "#/components/parameters/batteryStateMetric" } }, "messages": { "batteryState": { "$ref": "#/components/messages/BatteryStateValue" } } }, "curtailment": { "address": "dt/{siteId}/{gatewayId}/curtailment", "title": "出力抑制スケジュール", "description": "出力抑制スケジュールのテレメトリはこのトピックにパブリッシュします。系統用蓄電池システムを含むすべての構成で必須です。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" } }, "messages": { "curtailment": { "$ref": "#/components/messages/Curtailment" } } }, "irradiationTelemetry": { "address": "dt/{siteId}/{gatewayId}/irradiation", "title": "日射量テレメトリ", "description": "発電所に設置された日射量センサーの測定値を公開。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" } }, "messages": { "irradiation": { "$ref": "#/components/messages/Irradiation" } } }, "solarDcTelemetry": { "address": "dt/{siteId}/{gatewayId}/solar", "title": "太陽光DC電気テレメトリ", "description": "DCリンクの太陽光発電＋蓄電池システムにおける太陽光アレイのDC電圧および電流を公開。電圧と電流は同一時刻にサンプリングした一組として送信します。DCリンクのサイトにのみ適用されます。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" } }, "messages": { "solarDcElectrical": { "$ref": "#/components/messages/SolarDcElectrical" } } }, "gridFrequencyTelemetry": { "address": "dt/{siteId}/{gatewayId}/frequency", "title": "系統周波数テレメトリ", "description": "系統周波数（Hz）の測定値を公開。リソースが一次調整力に約定した場合、EMSはすべての一次調整力約定コマの全期間にわたり、系統周波数を各1秒ウィンドウの平均として1 Hz（1秒あたり1回）で公開しなければならない（MUST）。周波数は系統接続ポイントで実際のAC電圧波形から測定し、0.0001 Hz以上の分解能で報告すること。公称値・スケジュール値・その他の導出値を公開してはならない。これらの測定値は一次調整力アセスメントⅡで用いる1 Hzの供出電力テレメトリと時刻を揃えており、両者を直接比較できる。詳細は連携ガイドの「アセスメントⅡ報告」を参照。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" } }, "messages": { "gridFrequency": { "$ref": "#/components/messages/GridFrequency" } } }, "powerTelemetryBatch": { "address": "dt/{siteId}/{gatewayId}/{metric}/power/batch", "title": "瞬時電力テレメトリ（バッチ）", "description": "瞬時電力トピックのバッチ形式（任意）。1計測ごとに1メッセージを送る代わりに、単一メトリックの多数の計測値を1つのメッセージにまとめて送信します。1 Hzの高頻度送信や、通信断からの復旧時にたまったデータを送り直す用途を想定しています。各計測値は自身の message_id と measurement_ts を保持し、unit、aggregation、aggregation_window、pre_qualification はバッチ全体に対して一度だけ指定します。バッチは全体が受理されるか、全体が拒否されるかのいずれかです。バッチ送信はTensor Cloudがサイトごとに有効化し、既定では復旧送信（バックフィル）のみです。VPP構成の低圧蓄電池のようにライブテレメトリが毎秒到着する必要があるサイトでは、ライブの計測値は単一メッセージで送信し、バックフィルのみをバッチ化します。統合ガイドの「バッチテレメトリ」節を参照。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" }, "metric": { "$ref": "#/components/parameters/powerMetric" } }, "messages": { "powerInstantBatch": { "$ref": "#/components/messages/PowerInstantBatch" } } }, "gridFrequencyTelemetryBatch": { "address": "dt/{siteId}/{gatewayId}/frequency/batch", "title": "系統周波数テレメトリ（バッチ）", "description": "系統周波数トピックのバッチ形式（任意）。バッチ電力トピックと同じ規則に従います。多数の計測値を1つのメッセージにまとめ、各計測値は自身の message_id と measurement_ts を保持し、unit、aggregation、aggregation_window、pre_qualification はバッチ全体に対して一度だけ指定します。バッチは全体が受理されるか、全体が拒否されるかのいずれかです。バッチ送信はTensor Cloudがサイトごとに有効化し、既定では復旧送信（バックフィル）のみです。統合ガイドの「バッチテレメトリ」節を参照。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" } }, "messages": { "gridFrequencyBatch": { "$ref": "#/components/messages/GridFrequencyBatch" } } }, "batteryPowerCommand": { "address": "cmd/{siteId}/battery/power", "title": "蓄電池電力設定値コマンドスケジュール", "description": "蓄電池の実電力設定値コマンドスケジュールのトピック。蓄電池が一次調整力モードで運用される場合、このコマンドは一次調整力参加時の基準出力も決定し、基準出力は各区間の reference_point を引き継ぎます。設定値をどの地点で計測するかは、すべての区間で reference_point により示され、サイトの構成から推測することはありません。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" } }, "messages": { "batteryPowerCommand": { "$ref": "#/components/messages/BatteryPowerCommand" } } }, "batteryFcrCommand": { "address": "cmd/{siteId}/battery/fcr", "title": "一次需給調整市場（オフライン）のコマンドスケジュール", "description": "一次需給調整市場（オフライン）のコマンドスケジュールのトピック", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" } }, "messages": { "batteryFcrCommand": { "$ref": "#/components/messages/BatteryFcrCommand" } } }, "commandResponse": { "address": "ack-cmd/{siteId}", "title": "コマンドレスポンス", "description": "EMSからTensor Cloudへのコマンド実行結果。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" } }, "messages": { "commandResponse": { "$ref": "#/components/messages/CommandResponse" } } }, "alertEvent": { "address": "dt/{siteId}/{gatewayId}/alert", "title": "アラートイベント", "summary": "サイトアラートの状態変更イベント。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" } }, "messages": { "alertEvent": { "$ref": "#/components/messages/AlertEvent" } } }, "alertState": { "address": "dt/{siteId}/{gatewayId}/alert/active", "title": "アラートスナップショット", "summary": "現在アクティブなすべてのアラートの定期スナップショット。", "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" } }, "messages": { "alertState": { "$ref": "#/components/messages/AlertState" } } }, "telemetryFeedback": { "address": "ack-dt/{siteId}/{gatewayId}", "title": "テレメトリフィードバック", "description": "各テレメトリに対する`error`/`ok`の明示ACK。開発用途。テスト環境のみ（本番では無視）。", "servers": [ { "$ref": "#/servers/テスト環境" } ], "parameters": { "siteId": { "$ref": "#/components/parameters/siteId" }, "gatewayId": { "$ref": "#/components/parameters/gatewayId" } }, "messages": { "telemetryFeedback": { "$ref": "#/components/messages/TelemetryFeedback" } } } }, "operations": { "sendLifetimeTelemetry": { "action": "send", "channel": { "$ref": "#/channels/lifetimeTelemetry" }, "summary": "累積エネルギー（kWh）を送信。累積かウィンドウ集計のいずれか必須（可能なら両方）。", "messages": [ { "$ref": "#/channels/lifetimeTelemetry/messages/energyLifetime" } ] }, "sendEnergyTelemetry": { "action": "send", "channel": { "$ref": "#/channels/energyTelemetry" }, "summary": "ウィンドウエネルギーを送信", "messages": [ { "$ref": "#/channels/energyTelemetry/messages/energyWindowed" } ] }, "sendPowerTelemetry": { "action": "send", "channel": { "$ref": "#/channels/powerTelemetry" }, "summary": "瞬時電力を送信", "messages": [ { "$ref": "#/channels/powerTelemetry/messages/powerInstant" } ] }, "sendBatteryState": { "action": "send", "channel": { "$ref": "#/channels/stateTelemetry" }, "summary": "単一の蓄電池状態測定値を送信", "description": "送信する値はチャンネルのmetric（battery_soe / battery_energy_remaining）で決まる。", "messages": [ { "$ref": "#/channels/stateTelemetry/messages/batteryState" } ] }, "sendCurtailment": { "action": "send", "channel": { "$ref": "#/channels/curtailment" }, "summary": "出力抑制スケジュールを送信", "description": "EMSが出力抑制スケジュールを送信。", "messages": [ { "$ref": "#/channels/curtailment/messages/curtailment" } ] }, "sendIrradiation": { "action": "send", "channel": { "$ref": "#/channels/irradiationTelemetry" }, "summary": "日射量テレメトリを送信", "description": "EMSが発電所に設置された日射量センサーの測定値を送信。", "messages": [ { "$ref": "#/channels/irradiationTelemetry/messages/irradiation" } ] }, "sendSolarDc": { "action": "send", "channel": { "$ref": "#/channels/solarDcTelemetry" }, "summary": "太陽光DC電気テレメトリを送信", "description": "EMSがDCリンクサイトの太陽光アレイのDC電圧および電流をTensor Cloudへ送信。", "messages": [ { "$ref": "#/channels/solarDcTelemetry/messages/solarDcElectrical" } ] }, "sendGridFrequency": { "action": "send", "channel": { "$ref": "#/channels/gridFrequencyTelemetry" }, "summary": "系統周波数テレメトリを送信", "description": "EMSが系統接続ポイントで測定した系統周波数をTensor Cloudに送信。すべての一次調整力約定コマの全期間にわたり1 Hzで必須。", "messages": [ { "$ref": "#/channels/gridFrequencyTelemetry/messages/gridFrequency" } ] }, "sendPowerTelemetryBatch": { "action": "send", "channel": { "$ref": "#/channels/powerTelemetryBatch" }, "summary": "瞬時電力テレメトリをバッチ送信する", "description": "EMSが単一メトリックの多数の瞬時電力計測値を1つのメッセージで送信します。任意機能であり、Tensor Cloudがサイトごとに有効化します。当該サイトにライブのバッチ送信が許可されていない限り、バックフィルのみが対象です。", "messages": [ { "$ref": "#/channels/powerTelemetryBatch/messages/powerInstantBatch" } ] }, "sendGridFrequencyBatch": { "action": "send", "channel": { "$ref": "#/channels/gridFrequencyTelemetryBatch" }, "summary": "系統周波数テレメトリをバッチ送信する", "description": "EMSが多数の系統周波数計測値を1つのメッセージで送信します。任意機能であり、Tensor Cloudがサイトごとに有効化します。当該サイトにライブのバッチ送信が許可されていない限り、バックフィルのみが対象です。", "messages": [ { "$ref": "#/channels/gridFrequencyTelemetryBatch/messages/gridFrequencyBatch" } ] }, "receivePowerCommand": { "action": "receive", "channel": { "$ref": "#/channels/batteryPowerCommand" }, "summary": "充放電コマンドを受信", "description": "EMSゲートウェイがTensor Cloudから蓄電池の充放電スケジュールを受信。", "messages": [ { "$ref": "#/channels/batteryPowerCommand/messages/batteryPowerCommand" } ] }, "receiveFcrCommand": { "action": "receive", "channel": { "$ref": "#/channels/batteryFcrCommand" }, "summary": "一次需給調整市場（オフライン）のコマンドを受信", "description": "EMSゲートウェイがTensor Cloudから一次需給調整市場（オフライン）の落札スケジュールを受信。", "messages": [ { "$ref": "#/channels/batteryFcrCommand/messages/batteryFcrCommand" } ] }, "sendCommandResponse": { "action": "send", "channel": { "$ref": "#/channels/commandResponse" }, "summary": "コマンドレスポンスを送信", "description": "レスポンストピックはack-cmd/{siteId}/名前空間内。デフォルトはack-cmd/{siteId}。外れるとブローカーに拒否される。", "messages": [ { "$ref": "#/channels/commandResponse/messages/commandResponse" } ] }, "sendAlertEvent": { "action": "send", "channel": { "$ref": "#/channels/alertEvent" }, "summary": "アラート状態変更イベントを送信", "messages": [ { "$ref": "#/channels/alertEvent/messages/alertEvent" } ] }, "sendAlertState": { "action": "send", "channel": { "$ref": "#/channels/alertState" }, "summary": "現在のアクティブアラートスナップショットを送信", "messages": [ { "$ref": "#/channels/alertState/messages/alertState" } ] }, "receiveTelemetryFeedback": { "action": "receive", "channel": { "$ref": "#/channels/telemetryFeedback" }, "summary": "テレメトリフィードバックを受信", "description": "各テレメトリに対するACK/エラー。テスト環境のみ。レスポンストピックはack-dt/{siteId}/{gatewayId}に限定。", "messages": [ { "$ref": "#/channels/telemetryFeedback/messages/telemetryFeedback" } ] } }, "components": { "parameters": { "siteId": { "description": "Tensor Cloudが最適化する系統接続ポイントを一意に識別するサイトID。\nフォーマット: 'si_' + 小文字英数字6桁\n例: si_qcf9gn\nオンボーディング時にTensor Energyが付与。" }, "gatewayId": { "description": "Tensor Cloud接続EMS端末を一意に識別するゲートウェイID。\nフォーマット: 'gw_' + 小文字英数字6桁\n例: gw_0uv3tf\nオンボーディング時にTensor Energyが付与。" }, "powerMetric": { "description": "瞬時電力（kW）のメトリック名。ユースケースにより必須は異なる。", "enum": [ "meter_export_ac", "meter_import_ac", "grid_to_load_ac", "load_demand_ac", "solar_net_generation_ac", "battery_charge_ac", "battery_discharge_ac", "solar_to_grid_ac", "solar_to_battery_ac", "solar_to_load_ac", "battery_to_grid_ac", "battery_to_load_ac", "grid_to_battery_ac", "solar_generation_dc", "battery_charge_dc", "battery_to_inverter_dc", "inverter_net_output_ac", "solar_to_battery_dc", "solar_to_inverter_dc", "inverter_to_battery_dc", "inverter_to_load_ac", "inverter_to_grid_ac", "grid_to_inverter_ac" ] }, "energyMetric": { "description": "集計エネルギー（kWh）のメトリック名。ユースケースにより必須は異なる。", "enum": [ "meter_export_ac", "meter_import_ac", "grid_to_load_ac", "load_demand_ac", "solar_net_generation_ac", "battery_charge_ac", "battery_discharge_ac", "solar_to_grid_ac", "solar_to_battery_ac", "solar_to_load_ac", "battery_to_grid_ac", "battery_to_load_ac", "grid_to_battery_ac", "solar_generation_dc", "battery_charge_dc", "battery_to_inverter_dc", "inverter_net_output_ac", "solar_to_battery_dc", "solar_to_inverter_dc", "inverter_to_battery_dc", "inverter_to_load_ac", "inverter_to_grid_ac", "grid_to_inverter_ac" ] }, "lifetimeMetric": { "description": "累積エネルギー（kWh）のメトリック名。増加カウンター（リセットは処理可能）。", "enum": [ "meter_export_ac", "meter_import_ac", "grid_to_load_ac", "load_demand_ac", "solar_net_generation_ac", "battery_charge_ac", "battery_discharge_ac", "solar_to_grid_ac", "solar_to_battery_ac", "solar_to_load_ac", "battery_to_grid_ac", "battery_to_load_ac", "grid_to_battery_ac", "solar_generation_dc", "battery_charge_dc", "battery_to_inverter_dc", "inverter_net_output_ac", "solar_to_battery_dc", "solar_to_inverter_dc", "inverter_to_battery_dc", "inverter_to_load_ac", "inverter_to_grid_ac", "grid_to_inverter_ac" ] }, "window": { "description": "集計ウィンドウ長（ISO 8601期間）", "enum": ["PT1M", "PT5M", "PT10M", "PT15M", "PT30M", "PT1H"] }, "batteryStateMetric": { "description": "蓄電池状態メトリック。少なくとも、バッテリー状態エネルギー（SoE）とエネルギー残量（定格温度での蓄電池容量の残存kWh、劣化効果を含む）が必要です。\n\n- battery_soe: 現在この瞬間に蓄電池に蓄積されているエネルギー（State of ChargeのkWh相当）。頻繁に更新されます。有効範囲：0 ≤ battery_soe ≤ battery_energy_remaining。\n- battery_energy_remaining: 劣化および故障セルを考慮した、定格温度（約25°C）における蓄電池の総利用可能容量。蓄電池が保持できる最大エネルギーを表します。更新頻度は低い（通常1日1回）。", "enum": ["battery_soe", "battery_energy_remaining"] } }, "messages": { "EnergyLifetime": { "name": "EnergyLifetime", "title": "累積エネルギー読み取りテレメトリ", "summary": "kWh単位の累積エネルギー。", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "measurement_ts": { "description": "ISO-8601準拠のタイムスタンプ。EMSによってテレメトリが測定された時刻。", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:26:10.000+09:00"] }, "measurement_value": { "description": "累積エネルギー（kWh）の測定値", "type": "object", "properties": { "value": { "description": "運用開始以来の累積エネルギー。これは、電力メーターのように時間とともに増加するカウンターである必要があります。Tensor Cloudはカウンターのリセットを処理できます。", "type": "number", "minimum": 0 }, "unit": { "description": "測定単位", "type": "string", "enum": ["kWh"] } }, "required": ["value", "unit"], "additionalProperties": false } }, "additionalProperties": true, "required": ["message_id", "measurement_ts", "measurement_value", "schema_version"] } }, "EnergyWindowed": { "name": "EnergyWindowed", "title": "ウィンドウエネルギー読み取りテレメトリ", "summary": "時間ウィンドウ集計エネルギー。", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "measurement_ts": { "description": "ISO-8601準拠のタイムスタンプ。EMSによってテレメトリが測定された時刻。これはウィンドウ測定のため、ウィンドウの開始時刻を表し、measurement_value.start_tsと一致させる必要があります。ウィンドウの終了時刻や中間時刻を設定してはいけません。", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:00:00.000+09:00"] }, "measurement_value": { "description": "ウィンドウ内のエネルギー測定。タイムスタンプは左側が含まれ、右側は含まれません。つまり、*end_ts* が10:30の場合、10:29:59.999... までは含まれますが、10:30自体は含まれません。", "type": "object", "properties": { "start_ts": { "description": "ISO-8601準拠のタイムスタンプ。ウィンドウの開始時刻（含む）", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:00:00.000+09:00"] }, "end_ts": { "description": "ISO-8601準拠のタイムスタンプ。ウィンドウの終了時刻（含まれない）", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:30:00.000+09:00"] }, "value": { "description": "ウィンドウ内の総エネルギー測定", "type": "number", "minimum": 0 }, "unit": { "description": "測定単位", "type": "string", "enum": ["kWh"] } }, "required": ["start_ts", "end_ts", "value", "unit"], "additionalProperties": false } }, "additionalProperties": true, "required": ["message_id", "measurement_ts", "measurement_value", "schema_version"] } }, "PowerInstant": { "name": "PowerInstant", "title": "瞬時電力読み取りテレメトリ", "summary": "瞬時電力（kW）。", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "measurement_ts": { "description": "ISO-8601準拠のタイムスタンプ。EMSによってテレメトリが測定された時刻。'instant' の測定ではサンプリングした時点そのもの。ウィンドウ測定（'average'）ではaggregation_windowの開始時刻を表し、終了時刻や中間時刻を設定してはいけません。", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:26:10.000+09:00"] }, "pre_qualification": { "description": "任意。EMSが一次調整力事前審査（プレクオリフィケーション）モードで送信するテレメトリにtrueを設定する。このモードはTensor CloudではなくEMS運用者が有効化する。瞬時電力および系統周波数のテレメトリにのみ適用される。通常運用時は省略する（またはfalse）。Tensor Cloudはこのフラグを用いて、該当期間を最適化および一次調整力アセスメントⅡの提出対象から除外する。", "type": "boolean", "default": false }, "measurement_value": { "description": "瞬時電力値", "type": "object", "properties": { "value": { "description": "電力値。aggregationが 'instant' のときはmeasurement_tsにおける瞬時値、'average' のときはmeasurement_tsから始まるaggregation_windowにわたる平均値。", "type": "number", "minimum": 0 }, "unit": { "description": "測定単位", "type": "string", "enum": ["kW"] }, "aggregation": { "description": "'value' がmeasurement_tsにおける瞬時点サンプル（'instant'、デフォルト）か、measurement_tsから始まる区間の平均（'average'）かを示す。オフラインの一次調整力アセスメントⅡでは 'average' を1秒ウィンドウで公開する。", "type": "string", "enum": ["instant", "average"], "default": "instant" }, "aggregation_window": { "description": "'average' 値を算出した区間のISO-8601期間（例: 'PT1S'）。aggregationが 'average' のとき必須、'instant' のときは省略する。", "type": "string", "examples": ["PT1S"] } }, "required": ["value", "unit"], "additionalProperties": false, "if": { "properties": { "aggregation": { "const": "average" } }, "required": ["aggregation"] }, "then": { "required": ["aggregation_window"] } } }, "additionalProperties": true, "required": ["message_id", "measurement_ts", "measurement_value", "schema_version"] }, "examples": [ { "name": "一次調整力アセスメントⅡの1秒平均電力サンプル", "payload": { "schema_version": "2.8.0", "message_id": "msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "measurement_ts": "2024-01-04T03:00:00.000+09:00", "measurement_value": { "value": 1480.5, "unit": "kW", "aggregation": "average", "aggregation_window": "PT1S" } } }, { "name": "事前審査の電力サンプル", "summary": "実際の一次調整力コマと同じ1 Hz電力テレメトリだが、EMS運用者がサイトを事前審査モードにしている間はpre_qualification: trueを付与する。", "payload": { "schema_version": "2.8.0", "message_id": "msg_b91ee208-58fb-45db-9a77-51e8c5e99388", "measurement_ts": "2024-01-04T03:00:00.000+09:00", "pre_qualification": true, "measurement_value": { "value": 1480.5, "unit": "kW", "aggregation": "average", "aggregation_window": "PT1S" } } } ] }, "Curtailment": { "name": "出力抑制", "title": "出力抑制スケジュールテレメトリ", "summary": "出力抑制スケジュールのテレメトリメッセージ。系統用蓄電池システムを含むすべての構成で必須です。太陽光を併設しないサイトであってもTSOの出力抑制の対象となる場合があります。詳細は連携ガイドの「すべての構成に共通」のテレメトリ表を参照してください。", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "measurement_ts": { "description": "ISO-8601準拠のタイムスタンプ。出力抑制スケジュールの時刻。一般送配電事業者（TSO）のデータにスケジュールの作成時刻が含まれる場合はその作成時刻を、含まれない場合はEMSがTSOからスケジュールを受信した時刻を設定します。これはウィンドウ測定ではありません。スケジュールが対象とする期間はmeasurement_value[].start_tsおよびmeasurement_value[].end_tsで表します。", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:26:10.000+09:00"] }, "measurement_value": { "description": "出力抑制スケジュール", "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "properties": { "start_ts": { "description": "ISO-8601準拠のタイムスタンプ。出力抑制イベントの開始時刻を示します。左側は含まれます。`end_ts`より前である必要があります。", "type": "string", "format": "date-time", "examples": ["2024-01-04T14:00:00.000+09:00"] }, "end_ts": { "description": "ISO-8601準拠のタイムスタンプ。出力抑制イベントの終了時刻を示します。右側は含まれません。`start_ts`より後である必要があります。", "type": "string", "format": "date-time", "examples": ["2024-01-04T14:30:00.000+09:00"] }, "limit_percent": { "description": "TSOによって許可される最大サイト出力の割合。0は100%のエネルギーが抑制され、サイト出力が許可されないことを意味します。値は[0,100]の範囲内である必要があります。", "type": "integer", "minimum": 0, "maximum": 100 } }, "required": ["start_ts", "end_ts", "limit_percent"] } } }, "additionalProperties": true, "required": ["message_id", "measurement_ts", "measurement_value", "schema_version"] } }, "Irradiation": { "name": "Irradiation", "title": "日射量テレメトリ", "summary": "発電所に設置された日射量センサーの測定値（kW/m2）", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "measurement_ts": { "description": "ISO-8601準拠のタイムスタンプ。EMSによってテレメトリが測定された時刻。", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:26:10.000+09:00"] }, "measurement_value": { "description": "発電所に設置された日射量センサーの測定値", "type": "object", "properties": { "value": { "description": "瞬時日射量", "type": "number", "minimum": 0 }, "unit": { "description": "測定単位", "type": "string", "enum": ["kW/m2"] } }, "required": ["value", "unit"], "additionalProperties": false } }, "additionalProperties": true, "required": ["message_id", "measurement_ts", "measurement_value", "schema_version"] }, "examples": [ { "name": "日射量測定例", "payload": { "schema_version": "2.8.0", "message_id": "msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "measurement_ts": "2024-01-04T12:30:00.000+09:00", "measurement_value": { "value": 0.845, "unit": "kW/m2" } } } ] }, "SolarDcElectrical": { "name": "SolarDcElectrical", "title": "太陽光DC電気テレメトリ", "summary": "太陽光アレイ全体のDC電圧（V）および電流（A）のテレメトリメッセージ。DCリンクの太陽光発電＋蓄電池サイト向けに、一組の測定値として報告します。", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "measurement_ts": { "description": "ISO-8601準拠のタイムスタンプ。EMSによってテレメトリが測定された時刻。このメッセージの電圧と電流は、この同一時刻にサンプリングする必要があります。", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:26:10.000+09:00"] }, "measurement_value": { "description": "DCリンクにおいて、インバータより上流で測定した太陽光アレイのDC電圧および電流。アレイ全体を集約した単一の値です。電圧と電流は同一時刻にサンプリングし、一組の測定値を構成します。", "type": "object", "properties": { "voltage": { "description": "DCリンクにおける太陽光アレイの瞬時DC電圧（アレイ全体の集約値）", "type": "object", "properties": { "value": { "description": "DC電圧（ボルト）", "type": "number", "minimum": 0 }, "unit": { "description": "測定単位", "type": "string", "enum": ["V"] } }, "required": ["value", "unit"], "additionalProperties": false }, "current": { "description": "DCリンクにおける太陽光アレイの瞬時DC電流（アレイ全体の集約値、電圧と同一時刻にサンプリング）", "type": "object", "properties": { "value": { "description": "DC電流（アンペア）", "type": "number", "minimum": 0 }, "unit": { "description": "測定単位", "type": "string", "enum": ["A"] } }, "required": ["value", "unit"], "additionalProperties": false } }, "required": ["voltage", "current"], "additionalProperties": false } }, "additionalProperties": true, "required": ["message_id", "measurement_ts", "measurement_value", "schema_version"] }, "examples": [ { "name": "太陽光DC電気測定例", "payload": { "schema_version": "2.8.0", "message_id": "msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "measurement_ts": "2024-01-04T12:30:00.000+09:00", "measurement_value": { "voltage": { "value": 812.4, "unit": "V" }, "current": { "value": 143.2, "unit": "A" } } } } ] }, "GridFrequency": { "name": "GridFrequency", "title": "系統周波数テレメトリ", "summary": "系統接続ポイントで測定した系統周波数（Hz）のテレメトリメッセージ。すべての一次調整力約定コマの期間中、1 Hzで必須。", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "measurement_ts": { "description": "ISO-8601準拠のタイムスタンプ。EMSによってテレメトリが測定された時刻。'instant' の測定ではサンプリングした時点そのもの。ウィンドウ測定（'average'）ではaggregation_windowの開始時刻を表し、終了時刻や中間時刻を設定してはいけません。", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:26:10.000+09:00"] }, "pre_qualification": { "description": "任意。EMSが一次調整力事前審査（プレクオリフィケーション）モードで送信するテレメトリにtrueを設定する。このモードはTensor CloudではなくEMS運用者が有効化する。瞬時電力および系統周波数のテレメトリにのみ適用される。通常運用時は省略する（またはfalse）。Tensor Cloudはこのフラグを用いて、該当期間を最適化および一次調整力アセスメントⅡの提出対象から除外する。", "type": "boolean", "default": false }, "measurement_value": { "description": "系統周波数の測定値", "type": "object", "properties": { "value": { "description": "系統周波数（Hz）。系統接続ポイントで実際のAC電圧波形から測定する。0.0001 Hz以上の分解能で報告し、公称値・スケジュール値・その他の導出値を公開しないこと。aggregationが 'instant' のときはmeasurement_tsにおける瞬時値、'average' のときはmeasurement_tsから始まるaggregation_windowにわたる平均値。一次調整力約定コマでは 'average' を1秒ウィンドウで1 Hzで公開する。", "type": "number", "minimum": 0 }, "unit": { "description": "測定単位", "type": "string", "enum": ["Hz"] }, "aggregation": { "description": "'value' がmeasurement_tsにおける瞬時点サンプル（'instant'、デフォルト）か、measurement_tsから始まる区間の平均（'average'）かを示す。一次調整力約定コマでは 'average' を1秒ウィンドウで公開する。", "type": "string", "enum": ["instant", "average"], "default": "instant" }, "aggregation_window": { "description": "'average' 値を算出した区間のISO-8601期間（例: 'PT1S'）。aggregationが 'average' のとき必須、'instant' のときは省略する。", "type": "string", "examples": ["PT1S"] } }, "required": ["value", "unit"], "additionalProperties": false, "if": { "properties": { "aggregation": { "const": "average" } }, "required": ["aggregation"] }, "then": { "required": ["aggregation_window"] } } }, "additionalProperties": true, "required": ["message_id", "measurement_ts", "measurement_value", "schema_version"] }, "examples": [ { "name": "系統周波数測定例（一次調整力約定コマ）", "payload": { "schema_version": "2.8.0", "message_id": "msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "measurement_ts": "2024-01-04T12:30:00.000+09:00", "measurement_value": { "value": 50.0123, "unit": "Hz", "aggregation": "average", "aggregation_window": "PT1S" } } }, { "name": "事前審査の系統周波数サンプル", "summary": "事前審査中の周波数は、EMSが蓄電池を動作させる模擬信号であり、同じ方法で発行するがpre_qualification: trueを付与する。", "payload": { "schema_version": "2.8.0", "message_id": "msg_b91ee208-58fb-45db-9a77-51e8c5e99388", "measurement_ts": "2024-01-04T12:30:00.000+09:00", "pre_qualification": true, "measurement_value": { "value": 49.812, "unit": "Hz", "aggregation": "average", "aggregation_window": "PT1S" } } } ] }, "PowerInstantBatch": { "name": "PowerInstantBatch", "title": "瞬時電力テレメトリ（バッチ）", "summary": "単一メトリックの多数の瞬時電力計測値を1つのメッセージにまとめたもの", "correlationId": { "description": "トレース用のmessage_idによる相関付け", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "このバッチメッセージのID（プレフィックス付きUUID形式）。送信の試行を識別するものであり、重複排除のキーではありません。再送時には同じ計測値を異なる大きさのバッチに組み直してもよく、重複排除は各計測値が持つ message_id に対して行われます。", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "unit": { "description": "計測単位。'measurements' のすべての要素に適用されます", "type": "string", "enum": ["kW"] }, "aggregation": { "description": "各 'value' が、その 'measurement_ts' 時点の瞬時サンプル（'instant'、既定値）か、その時刻から始まる区間の平均値（'average'）かを示します。'measurements' のすべての要素に適用されるため、値が変わる場合はバッチを分割してください。オフラインの一次調整力アセスメントⅡでは 'average' を1秒ウィンドウで公開します。", "type": "string", "enum": ["instant", "average"], "default": "instant" }, "aggregation_window": { "description": "各 'average' 値を算出した期間をISO-8601のdurationで表したもの（例: 'PT1S'）。aggregationが 'average' の場合は必須、'instant' の場合は省略します。'measurements' のすべての要素に適用されるため、値が変わる場合はバッチを分割してください。", "type": "string", "examples": ["PT1S"] }, "pre_qualification": { "description": "任意。EMSが一次調整力事前審査（プレクオリフィケーション）モードにある場合にtrueを設定します。このモードはTensor Cloudではなく、EMS運用者が有効化します。'measurements' のすべての要素に適用されるため、運用者がモードに入る／出る瞬間をバッチがまたいではならず、その時点で分割してください。通常運用時は省略（またはfalse）とします。", "type": "boolean", "default": false }, "measurements": { "description": "このバッチが運ぶ計測値。'measurement_ts' の昇順に厳密に並べ、同一のタイムスタンプおよび同一の message_id を含めてはなりません。信頼できる値が得られなかった秒は、単に存在しない状態とします。代わりに0やnullを送ってはいけません。バッチは全体が受理されるか、全体が拒否されるかのいずれかです。", "type": "array", "minItems": 1, "maxItems": 900, "items": { "type": "object", "properties": { "message_id": { "description": "この個別計測値のID（プレフィックス付きUUID形式）。これが重複排除のキーです。同一の計測値を再送する場合は、バッチ形式・単一メッセージ形式のいずれであっても元の値を再利用してください。", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_b91ee208-58fb-45db-9a77-51e8c5e99388"] }, "measurement_ts": { "description": "EMSがこの値を計測した時刻（ISO-8601準拠）。'instant' の場合はサンプルを取得した瞬間を表します。'average' の場合はaggregation_windowの開始時刻を必ず指定し、終了時刻や中間時刻を指定してはいけません。", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:00:00.000+09:00"] }, "value": { "description": "バッチの 'unit' による電力値。aggregationが 'instant' の場合は 'measurement_ts' 時点の瞬時値、'average' の場合はその時刻から始まる区間の平均値です。", "type": "number", "minimum": 0 } }, "required": ["message_id", "measurement_ts", "value"], "additionalProperties": false } } }, "additionalProperties": true, "required": ["schema_version", "message_id", "unit", "measurements"], "if": { "properties": { "aggregation": { "const": "average" } }, "required": ["aggregation"] }, "then": { "required": ["aggregation_window"] } }, "examples": [ { "name": "一次調整力アセスメントⅡの1秒平均電力（1分ぶん）", "summary": "60個の1秒平均値を1つのメッセージにまとめた例。03:00:02の秒は信頼できる値が得られなかったため存在しません", "payload": { "schema_version": "2.8.0", "message_id": "msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "unit": "kW", "aggregation": "average", "aggregation_window": "PT1S", "measurements": [ { "message_id": "msg_b91ee208-58fb-45db-9a77-51e8c5e99388", "measurement_ts": "2024-01-04T03:00:00.000+09:00", "value": 1480.5 }, { "message_id": "msg_c02ff319-69ac-46ec-ab88-62f9d6faa499", "measurement_ts": "2024-01-04T03:00:01.000+09:00", "value": 1481.2 }, { "message_id": "msg_d13aa420-7abd-4711-bc99-73fae7fbb500", "measurement_ts": "2024-01-04T03:00:03.000+09:00", "value": 1479.8 } ] } } ] }, "GridFrequencyBatch": { "name": "GridFrequencyBatch", "title": "系統周波数テレメトリ（バッチ）", "summary": "多数の系統周波数計測値を1つのメッセージにまとめたもの", "correlationId": { "description": "トレース用のmessage_idによる相関付け", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "このバッチメッセージのID（プレフィックス付きUUID形式）。送信の試行を識別するものであり、重複排除のキーではありません。再送時には同じ計測値を異なる大きさのバッチに組み直してもよく、重複排除は各計測値が持つ message_id に対して行われます。", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "unit": { "description": "計測単位。'measurements' のすべての要素に適用されます", "type": "string", "enum": ["Hz"] }, "aggregation": { "description": "各 'value' が、その 'measurement_ts' 時点の瞬時サンプル（'instant'、既定値）か、その時刻から始まる区間の平均値（'average'）かを示します。'measurements' のすべての要素に適用されるため、値が変わる場合はバッチを分割してください。一次調整力約定コマでは 'average' を1秒ウィンドウで公開します。", "type": "string", "enum": ["instant", "average"], "default": "instant" }, "aggregation_window": { "description": "各 'average' 値を算出した期間をISO-8601のdurationで表したもの（例: 'PT1S'）。aggregationが 'average' の場合は必須、'instant' の場合は省略します。'measurements' のすべての要素に適用されるため、値が変わる場合はバッチを分割してください。", "type": "string", "examples": ["PT1S"] }, "pre_qualification": { "description": "任意。EMSが一次調整力事前審査（プレクオリフィケーション）モードにある場合にtrueを設定します。このモードはTensor Cloudではなく、EMS運用者が有効化します。'measurements' のすべての要素に適用されるため、運用者がモードに入る／出る瞬間をバッチがまたいではならず、その時点で分割してください。通常運用時は省略（またはfalse）とします。", "type": "boolean", "default": false }, "measurements": { "description": "このバッチが運ぶ計測値。'measurement_ts' の昇順に厳密に並べ、同一のタイムスタンプおよび同一の message_id を含めてはなりません。信頼できる値が得られなかった秒は、単に存在しない状態とします。代わりに0やnullを送ってはいけません。バッチは全体が受理されるか、全体が拒否されるかのいずれかです。", "type": "array", "minItems": 1, "maxItems": 900, "items": { "type": "object", "properties": { "message_id": { "description": "この個別計測値のID（プレフィックス付きUUID形式）。これが重複排除のキーです。同一の計測値を再送する場合は、バッチ形式・単一メッセージ形式のいずれであっても元の値を再利用してください。", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_c02ff319-69ac-46ec-ab88-62f9d6faa499"] }, "measurement_ts": { "description": "EMSがこの値を計測した時刻（ISO-8601準拠）。'instant' の場合はサンプルを取得した瞬間を表します。'average' の場合はaggregation_windowの開始時刻を必ず指定し、終了時刻や中間時刻を指定してはいけません。", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:00:00.000+09:00"] }, "value": { "description": "系統周波数（Hz）。系統連系点で実際のAC電圧波形から計測し、少なくとも0.0001 Hzの分解能で報告してください。定格値、計画値、その他の導出値を送ってはいけません。", "type": "number", "minimum": 0 } }, "required": ["message_id", "measurement_ts", "value"], "additionalProperties": false } } }, "additionalProperties": true, "required": ["schema_version", "message_id", "unit", "measurements"], "if": { "properties": { "aggregation": { "const": "average" } }, "required": ["aggregation"] }, "then": { "required": ["aggregation_window"] } }, "examples": [ { "name": "1秒平均の系統周波数（バッチ）", "summary": "同じ秒の電力サンプルと時刻を揃えた周波数サンプル", "payload": { "schema_version": "2.8.0", "message_id": "msg_e24bb531-8bce-4822-adaa-840bc8fcc611", "unit": "Hz", "aggregation": "average", "aggregation_window": "PT1S", "measurements": [ { "message_id": "msg_f45cc642-90de-4933-bfbb-951ca7edd722", "measurement_ts": "2024-01-04T03:00:00.000+09:00", "value": 49.812 }, { "message_id": "msg_0561dd53-a1ef-4a44-cadd-a62bd9fdd833", "measurement_ts": "2024-01-04T03:00:01.000+09:00", "value": 49.987 } ] } } ] }, "BatteryStateValue": { "name": "BatteryStateValue", "title": "蓄電池状態テレメトリ", "summary": "単一の蓄電池状態測定値", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "measurement_ts": { "description": "ISO-8601準拠のタイムスタンプ。EMSによってテレメトリが測定された時刻。", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:26:10.000+09:00"] }, "measurement_value": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0 }, "unit": { "type": "string", "enum": ["kWh"] } }, "additionalProperties": false, "required": ["value", "unit"] } }, "additionalProperties": true, "required": ["message_id", "measurement_ts", "measurement_value", "schema_version"] } }, "BatteryPowerCommand": { "name": "BatteryPowerCommand", "title": "蓄電池電力設定値コマンド", "summary": "任意間隔のスケジュールで充放電を指示。", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "issue_ts": { "description": "ISO-8601準拠のタイムスタンプ。Tensor Cloudがコマンドを発行した時刻を示します。EMSが優先順位ポリシーを実行するために使用します。", "type": "string", "format": "date-time", "examples": ["2024-01-05T00:00:00.000+09:00"] }, "res_topic": { "description": "EMSがコマンド結果を送信するレスポンストピック。ack-cmd/{siteId}名前空間内である必要があります。res_topicがこの名前空間外の場合、MQTTブローカーによって拒否されます。", "type": "string", "pattern": "^ack-cmd/si_[a-z0-9]{6}$", "examples": ["ack-cmd/si_qcf9gn"] }, "control": { "description": "蓄電池電力設定値スケジュールのペイロード", "type": "object", "properties": { "priority": { "description": "制御コマンドの優先度。値が大きいほど優先度が高くなります。例: 値が50の場合は10よりも高い優先度を持ちます。", "type": "number", "minimum": 0, "maximum": 100 }, "schedule": { "description": "充放電スケジュール", "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "start_ts": { "description": "ISO-8601準拠のタイムスタンプ。スケジュールされた充放電イベントの開始時刻を示します。左側は含まれます。", "type": "string", "format": "date-time", "examples": ["2024-01-05T00:00:00.000+09:00"] }, "end_ts": { "description": "ISO-8601準拠のタイムスタンプ。スケジュールされた充放電イベントの終了時刻を示します。右側は含まれません。", "type": "string", "format": "date-time", "examples": ["2024-01-05T00:30:00.000+09:00"] }, "power_kw": { "description": "充放電に使用するキロワット単位の電力の量。正の値は充電を示し、負の値は放電を示します。0の値は待機を示します。この値がどの地点を指すかは、同じ区間の 'reference_point' で示され、サイトの構成から推測することはありません。", "type": "number", "examples": [10.123, -5.5, 0] }, "reference_point": { "description": "この区間の 'power_kw' をどの地点で計測するかを示します。'battery'（フィールドが存在しない場合の既定値）は、値が蓄電池そのものを指すことを意味します。EMSは蓄電池をその値に追従させ、併設の発電はそのまま通過させるため、0は蓄電池が待機することを意味します。'grid' は、値がサイトの計量地点（受電点）を指すことを意味します。これは 'meter_export_ac' および 'meter_import_ac' を計測する地点と同一であり、構内需要がある場合はインバータのAC出力とは一致しません。蓄電池はこの目標値と発電量との差分を埋めるため、0は蓄電池の停止ではなく受電点での正味の流れがゼロであることを意味します。蓄電池と太陽光がインバータを共有するDC連系のシステムでは、EMSは実測の太陽光出力に基づきAC設定値を補正することで 'battery' を実現します。Tensor Cloudは既定値に依存せず、すべてのコマンドでこのフィールドを明示します。また 'grid' は、EMSが schema_version 2.7.0 以降を報告するサイトに対してのみ送信します。EMSが要求された値に到達できない場合（'battery' でのインバータ制限、'grid' での蓄電量の制限など）は、物理的に到達可能な値にクランプしたうえで運転を継続し、SETPOINT_UNREACHABLE を発報します。", "type": "string", "enum": ["battery", "grid"], "default": "battery" } }, "additionalProperties": false, "required": ["start_ts", "end_ts", "power_kw"] } } }, "additionalProperties": false, "required": ["schedule", "priority"] } }, "additionalProperties": true, "required": ["message_id", "issue_ts", "res_topic", "control", "schema_version"] }, "examples": [ { "name": "蓄電池出力指令コマンド例", "summary": "2つの基準点が混在するスケジュール。最初の2区間は蓄電池を対象とし、充電したのち待機します。この間、併設の発電はそのまま送電されます。3区間目は出力制限の時間帯として受電点をゼロに保つため、蓄電池はその時点の発電量を吸収します", "payload": { "schema_version": "2.8.0", "message_id": "msg_7c1f0f4a-2f1a-4c3e-9a2b-6d5e4f3a2b1c", "issue_ts": "2024-01-04T23:45:00.000+09:00", "res_topic": "ack-cmd/si_qcf9gn", "control": { "priority": 2, "schedule": [ { "start_ts": "2024-01-05T09:00:00.000+09:00", "end_ts": "2024-01-05T09:30:00.000+09:00", "power_kw": 800.0, "reference_point": "battery" }, { "start_ts": "2024-01-05T09:30:00.000+09:00", "end_ts": "2024-01-05T10:00:00.000+09:00", "power_kw": 0, "reference_point": "battery" }, { "start_ts": "2024-01-05T10:00:00.000+09:00", "end_ts": "2024-01-05T10:30:00.000+09:00", "power_kw": 0, "reference_point": "grid" } ] } } }, { "name": "reference_pointを含まない蓄電池出力指令コマンド例", "summary": "reference_point を省略しているため、いずれの区間も既定値の 'battery' となります。これは2.7.0より前に送信されていた形式であり、従来どおりの意味を保ちます", "payload": { "schema_version": "2.8.0", "message_id": "msg_1b2c3d4e-5f60-4718-8293-a4b5c6d7e8f9", "issue_ts": "2024-01-04T23:45:00.000+09:00", "res_topic": "ack-cmd/si_qcf9gn", "control": { "priority": 2, "schedule": [ { "start_ts": "2024-01-05T18:00:00.000+09:00", "end_ts": "2024-01-05T18:30:00.000+09:00", "power_kw": -1500.0 }, { "start_ts": "2024-01-05T18:30:00.000+09:00", "end_ts": "2024-01-05T19:00:00.000+09:00", "power_kw": 0 } ] } } } ] }, "BatteryFcrCommand": { "name": "BatteryFcrCommand", "title": "一次需給調整市場（オフライン）のスケジュール", "summary": "Tensor CloudからEMSへ送信される一次需給調整市場（オフライン）の落札スケジュールが含まれるメッセージ", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "issue_ts": { "description": "ISO-8601準拠のタイムスタンプ。Tensor Cloudがコマンドを発行した時刻を示します。EMSが優先順位ポリシーを実行するために使用します。", "type": "string", "format": "date-time", "examples": ["2024-01-05T00:00:00.000+09:00"] }, "res_topic": { "description": "EMSがコマンド結果を送信するレスポンストピック。ack-cmd/{siteId}名前空間内である必要があります。res_topicがこの名前空間外の場合、MQTTブローカーによって拒否されます。", "type": "string", "pattern": "^ack-cmd/si_[a-z0-9]{6}$", "examples": ["ack-cmd/si_qcf9gn"] }, "control": { "description": "一次需給調整市場（オフライン）スケジュールのペイロード", "type": "object", "properties": { "priority": { "description": "制御コマンドの優先度。値が大きいほど優先度が高くなります。例: 値が50の場合は10よりも高い優先度を持ちます。", "type": "number", "minimum": 0, "maximum": 100 }, "action": { "description": "実行するアクション。'execute'（デフォルト）は一次需給調整市場（オフライン）の落札スケジュールを実行します。'cancel'は指定された時間範囲内に以前に送信されたコマンドをキャンセルし、優先度ルールを尊重します（同等または低い優先度のコマンドのみをキャンセルします）。", "type": "string", "enum": ["execute", "cancel"], "default": "execute" }, "schedule": { "description": "一次需給調整市場（オフライン）の制御スケジュール。action='execute'の場合、実行する落札が含まれます。action='cancel'の場合、キャンセルする時間範囲を指定します（capacity_kwは不要）。", "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "start_ts": { "description": "ISO-8601準拠のタイムスタンプ。一次需給調整市場（オフライン）の落札開始時刻を示します。左側は含まれます。", "type": "string", "format": "date-time", "examples": ["2024-01-05T00:00:00.000+09:00"] }, "end_ts": { "description": "ISO-8601準拠のタイムスタンプ。一次需給調整市場（オフライン）の落札終了時刻を示します。右側は含まれません。", "type": "string", "format": "date-time", "examples": ["2024-01-05T00:30:00.000+09:00"] }, "capacity_kw": { "description": "落札量（kW）。action='execute'の場合は必須、action='cancel'の場合は省略されます。", "type": "number", "minimum": 0, "examples": [10.5, 25.0, 50.0] } }, "additionalProperties": false, "required": ["start_ts", "end_ts"] } } }, "additionalProperties": false, "required": ["schedule", "priority"], "if": { "properties": { "action": { "const": "cancel" } }, "required": ["action"] }, "then": { "properties": { "schedule": { "items": { "not": { "required": ["capacity_kw"] } } } } }, "else": { "properties": { "schedule": { "items": { "required": ["capacity_kw"] } } } } } }, "additionalProperties": true, "required": ["message_id", "issue_ts", "res_topic", "control", "schema_version"] }, "examples": [ { "name": "一次需給調整市場（オフライン）コマンド例", "summary": "複数の30分コマの落札スケジュールを実行", "payload": { "schema_version": "2.8.0", "message_id": "msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "issue_ts": "2024-01-04T23:55:00.000+09:00", "res_topic": "ack-cmd/si_qcf9gn", "control": { "priority": 50, "action": "execute", "schedule": [ { "start_ts": "2024-01-05T06:00:00.000+09:00", "end_ts": "2024-01-05T06:30:00.000+09:00", "capacity_kw": 1200.0 }, { "start_ts": "2024-01-05T06:30:00.000+09:00", "end_ts": "2024-01-05T07:00:00.000+09:00", "capacity_kw": 1500.0 } ] } } }, { "name": "一次需給調整市場（オフライン）キャンセルコマンド例", "summary": "翌日のすべての落札をキャンセル", "payload": { "schema_version": "2.8.0", "message_id": "msg_c4ce10c4-1234-1234-1234-123456789012", "issue_ts": "2024-01-05T12:00:00.000+09:00", "res_topic": "ack-cmd/si_qcf9gn", "control": { "priority": 100, "action": "cancel", "schedule": [ { "start_ts": "2024-01-06T00:00:00.000+09:00", "end_ts": "2024-01-07T00:00:00.000+09:00" } ] } } }, { "name": "一次需給調整市場（オフライン）部分キャンセル例", "summary": "特定の30分コマの落札をキャンセル", "payload": { "schema_version": "2.8.0", "message_id": "msg_aabbccdd-3456-7890-abcd-ef1234567890", "issue_ts": "2024-01-05T10:30:00.000+09:00", "res_topic": "ack-cmd/si_qcf9gn", "control": { "priority": 75, "action": "cancel", "schedule": [ { "start_ts": "2024-01-05T12:00:00.000+09:00", "end_ts": "2024-01-05T12:30:00.000+09:00" }, { "start_ts": "2024-01-05T12:30:00.000+09:00", "end_ts": "2024-01-05T13:00:00.000+09:00" } ] } } } ] }, "CommandResponse": { "name": "CommandResponse", "title": "コマンドレスポンス", "summary": "コマンド実行結果。", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "このレスポンスの一意識別子", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "status": { "description": "コマンドを受信時点で検証・受理した結果（実行結果ではありません）。ACKはコマンドを受信・パースし、コミット（受理）した直後に送出され、実行時には送出されません。`ok` はコマンドが正しい形式で受理されたこと、`error` は検証に失敗したか、受信時点の処理で受理・コミットできなかったこと（`errors` を参照）を示します。実行時にのみ顕在化する失敗は、このACKでは報告できません。検証は全件一括（all-or-nothing）です。部分的な状態を表すステータスは存在しません。コマンドは全体が受理されて `ok` となるか、一切適用されずに拒否されて `error` となるかのいずれかであり、一部だけが適用されることはありません。`control.schedule` の項目が1件でも不正な場合、EMSはそのコマンドの項目をいずれも適用せず、直前まで有効だったスケジュールの実行を継続します。", "type": "string", "enum": ["ok", "error"] }, "command_id": { "description": "応答対象のコマンドメッセージのmessage_id。受信したコマンドを解析できず（MESSAGE_MALFORMED）、そのmessage_idを復元できない場合は、センチネル文字列 \"unknown\" を設定します。message_idが一部復元できる場合は、復元した値を設定します。このセンチネルのため、command_idはmsg_ UUIDパターンには意図的に制約されていません。", "type": "string", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "unknown"] }, "errors": { "description": "エラーの配列（status = 'error' の場合に必ず存在し、1件以上を含む必要があります。それ以外の場合は省略されます）。相関するメッセージで検出された各エラーについて、EMSは配列内に1件の項目を送信する必要があります。最初のエラーで打ち切らず、不正なスケジュール項目ごとに1件を含めてください。検証は全件一括であるため、この配列はコマンド全体が拒否された理由を示すものであり、一部の項目のみをスキップして残りを適用したことを示すものではありません。", "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "detail": { "description": "状況を説明する詳細なエラーメッセージ", "type": "string", "examples": [ "電力値がバッテリーの最大容量を超えています", "バッテリーへの接続が失われました" ] }, "field_path": { "description": "エラーを引き起こしたフィールドへのパス。すべてのエラーがコマンドスケジュールの内容に直接起因するわけではないため任意。", "type": "string", "examples": ["control.schedule[0].power_kw"] } }, "required": ["code", "detail"], "additionalProperties": false } } }, "additionalProperties": true, "required": ["message_id", "command_id", "status", "schema_version"], "if": { "properties": { "status": { "const": "error" } } }, "then": { "required": ["errors"] }, "else": { "not": { "required": ["errors"] } } }, "examples": [ { "name": "コマンドレスポンス正常例", "summary": "EMSがコマンドを正常に受け入れました", "payload": { "schema_version": "2.8.0", "message_id": "msg_a80dd191-47fa-44ca-3243-40d7b4d88277", "status": "ok", "command_id": "msg_a80dd197-47fa-44ca-8966-40d7b4d88277" } }, { "name": "コマンドレスポンスエラー例", "summary": "Tensor Cloudがバッテリーの最大出力容量を超える放電電力値を送信しました", "payload": { "schema_version": "2.8.0", "message_id": "msg_a80dd191-47fa-44ca-3243-40d7b4d88277", "status": "error", "command_id": "msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "errors": [ { "code": "FIELD_OUT_OF_RANGE", "detail": "Power value exceeds battery maximum capacity", "field_path": "control.schedule[0].power_kw" } ] } }, { "name": "コマンドレスポンス複数エラー例", "summary": "EMSがスケジュール内のいくつかの検証失敗によりコマンドを拒否しました。ここに挙げられていないスロットは妥当でしたが、検証は全件一括であるため、このコマンドのスロットはいずれも適用されず、直前まで有効だったスケジュールの実行が継続されます", "payload": { "schema_version": "2.8.0", "message_id": "msg_44444444-5555-6666-7777-888888888888", "status": "error", "command_id": "msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "errors": [ { "code": "FIELD_OUT_OF_RANGE", "detail": "Power value exceeds battery maximum capacity", "field_path": "control.schedule[0].power_kw" }, { "code": "TIME_WINDOW_INVALID", "detail": "End timestamp must be after start timestamp", "field_path": "control.schedule[1].end_ts" }, { "code": "MISSING_FIELD", "detail": "Priority field is required", "field_path": "control.priority" } ] } }, { "name": "コマンドレスポンス不正形式例", "summary": "コマンドをJSONとして解析できずmessage_idを復元できないため、command_idはセンチネル値 \"unknown\" にフォールバックします", "payload": { "schema_version": "2.8.0", "message_id": "msg_55555555-6666-7777-8888-999999999999", "status": "error", "command_id": "unknown", "errors": [ { "code": "MESSAGE_MALFORMED", "detail": "Command payload is not valid JSON" } ] } } ] }, "AlertEvent": { "name": "AlertEvent", "title": "アラートイベント", "summary": "アラートの状態変更イベント。", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "measurement_ts": { "description": "EMSがアラート状態の変化を測定した時点のISO-8601タイムスタンプ", "type": "string", "format": "date-time", "examples": ["2024-01-04T03:26:10.000+09:00"] }, "measurement_value": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/AlertCode", "description": "アラートタイプの識別子。" }, "status": { "description": "アラートが進行中（active）か、解決済み（cleared）か。", "type": "string", "enum": ["active", "cleared"] } }, "required": ["code", "status"], "additionalProperties": false } }, "required": ["message_id", "measurement_ts", "measurement_value", "schema_version"], "additionalProperties": true } }, "AlertState": { "name": "AlertState", "title": "アラートスナップショット", "summary": "現在アクティブなアラートのスナップショット。", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "メッセージのID（プレフィックス付きUUID形式）", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_99999999-8888-7777-6666-555555555555"] }, "measurement_ts": { "description": "EMSがスナップショットを取得した時点のISO-8601準拠タイムスタンプ", "type": "string", "format": "date-time", "examples": ["2025-09-10T11:20:00+09:00"] }, "measurement_value": { "description": "アラートとその現在の状態のリスト。空配列は有効であり、想定される状態です。スナップショットはアラートの発報有無にかかわらず所定の周期で送信し、空配列は「アクティブなアラートが存在しない」ことを積極的に示します。アクティブなアラートがないことを理由に送信を省略することは認められません。省略すると、Tensor Cloud側で正常なサイトと無応答のサイトを区別できなくなるためです。", "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/AlertCode", "description": "アラートタイプの識別子" }, "first_seen_ts": { "type": "string", "format": "date-time", "description": "このアラートが最初にアクティブとして確認された時点のISO-8601準拠タイムスタンプ。" }, "last_seen_ts": { "type": "string", "format": "date-time", "description": "このアラートが最後にアクティブとして確認された時点のISO-8601準拠タイムスタンプ。" } }, "required": ["code", "first_seen_ts", "last_seen_ts"], "additionalProperties": false }, "minItems": 0 } }, "required": ["message_id", "measurement_ts", "measurement_value", "schema_version"], "additionalProperties": true }, "examples": [ { "name": "FirstActiveAlert", "summary": "EMSが初めて低SOCアラートを発生", "payload": { "schema_version": "2.8.0", "message_id": "msg_11111111-2222-3333-4444-555555555555", "measurement_ts": "2025-09-15T10:00:00+09:00", "measurement_value": [ { "code": "BATT_SOC_LOW", "first_seen_ts": "2025-09-15T10:00:00+09:00", "last_seen_ts": "2025-09-15T10:00:00+09:00" } ] } }, { "name": "OngoingActiveAlert", "summary": "アラートが継続中のスナップショット", "payload": { "schema_version": "2.8.0", "message_id": "msg_22222222-3333-4444-5555-666666666666", "measurement_ts": "2025-09-15T10:05:00+09:00", "measurement_value": [ { "code": "BATT_SOC_LOW", "first_seen_ts": "2025-09-15T10:00:00+09:00", "last_seen_ts": "2025-09-15T10:05:00+09:00" } ] } }, { "name": "MultipleAlerts", "summary": "2つのアラートが同時にアクティブなスナップショット", "payload": { "schema_version": "2.8.0", "message_id": "msg_44444444-5555-6666-7777-888888888888", "measurement_ts": "2025-09-15T10:15:00+09:00", "measurement_value": [ { "code": "BATT_SOC_LOW", "first_seen_ts": "2025-09-15T10:00:00+09:00", "last_seen_ts": "2025-09-15T10:15:00+09:00" }, { "code": "PV_COMM_FAIL", "first_seen_ts": "2025-09-15T10:12:00+09:00", "last_seen_ts": "2025-09-15T10:15:00+09:00" } ] } } ] }, "TelemetryFeedback": { "name": "TelemetryFeedback", "title": "テレメトリフィードバック", "summary": "テレメッセージに対する開発者向けフィードバック。テスト環境のみで使用され、本番環境では無視されます。", "correlationId": { "description": "message_idに基づくトレース", "location": "$message.payload#/message_id" }, "contentType": "application/json", "payload": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "schema_version": { "description": "安全な進化と後方互換性のためのスキーマのバージョン", "type": "string", "default": "2.8.0", "pattern": "^\\d+\\.\\d+\\.\\d+$", "examples": ["2.8.0"] }, "message_id": { "description": "このレスポンスメッセージの一意なメッセージ識別子", "type": "string", "pattern": "^msg_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277"] }, "correlation_id": { "description": "このフィードバックをトリガーしたテレメトリメッセージの`message_id`。受信したテレメトリを一切解析できず（MESSAGE_MALFORMED）、そのmessage_idを復元できない場合は、センチネル文字列 \"unknown\" を設定します。message_idが一部復元できる場合は、復元した値を設定します。このセンチネルを許容するため、correlation_idには意図的にmsg_ UUIDパターンの制約を課していません。", "type": "string", "examples": ["msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "unknown"] }, "status": { "description": "検証ステータス", "type": "string", "enum": ["ok", "error"] }, "code": { "description": "statusがerrorの場合のエラーコード", "$ref": "#/components/schemas/ErrorCode" }, "field_path": { "description": "該当する場合、エラーを引き起こしたフィールドへのパス", "type": "string", "examples": ["measurement_value.value"] }, "topic": { "description": "問題となったテレメトリメッセージがパブリッシュされたトピック。任意であり、statusがerrorの場合にのみ含まれます。correlation_idがセンチネル \"unknown\" の場合、EMSがどのメッセージを拒否されたか特定できる唯一の情報となるため、必ず設定することを強く推奨します。", "type": "string", "examples": ["dt/site-123/gw-1/battery/state"] }, "detail": { "description": "詳細なエラーメッセージ", "type": "string", "examples": ["soe_kwh must be positive"] } }, "required": ["message_id", "correlation_id", "status", "schema_version"], "additionalProperties": true, "if": { "properties": { "status": { "const": "error" } } }, "then": { "required": ["code", "detail"] }, "else": { "not": { "anyOf": [ { "required": ["code"] }, { "required": ["detail"] }, { "required": ["topic"] } ] } } }, "examples": [ { "name": "テレメッセージが検証を通過", "payload": { "schema_version": "2.8.0", "message_id": "msg_11111111-2222-3333-4444-555555555555", "correlation_id": "msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "status": "ok" } }, { "name": "テレメッセージが検証を通過しなかった", "payload": { "schema_version": "2.8.0", "message_id": "msg_22222222-3333-4444-5555-666666666666", "correlation_id": "msg_a80dd197-47fa-44ca-8966-40d7b4d88277", "status": "error", "code": "FIELD_OUT_OF_RANGE", "field_path": "measurement_value.value", "topic": "dt/site-123/gw-1/battery/state", "detail": "soe_kwh must be positive" } }, { "name": "テレメトリメッセージが不正な形式", "summary": "テレメトリをJSONとして解析できずmessage_idを復元できないため、correlation_idはセンチネル \"unknown\" となり、topicが送信元チャネルを示します", "payload": { "schema_version": "2.8.0", "message_id": "msg_33333333-4444-5555-6666-777777777777", "correlation_id": "unknown", "status": "error", "code": "MESSAGE_MALFORMED", "topic": "dt/site-123/gw-1/battery/state", "detail": "Telemetry payload is not valid JSON" } } ] } }, "schemas": { "AlertCode": { "title": "アラートコード", "description": "標準化されたアラートコードです。しきい値とマッピングの指針は連携ガイドの「アラートコードリファレンス」節を参照してください。1つのサイト障害が複数のコードに該当する場合があります。DCリンクのシステムで、太陽光アレイと蓄電池が共有するハードウェア（ハイブリッドインバータ、共通のパワーコンディショニング設備、共通の制御・集約装置）に障害が発生した場合は、`PV_OTHER` と `BATT_OTHER` の両方で報告します。また、EMSが単一の集約装置を介して蓄電池と太陽光に接続しており、BMS単位・PVPCS単位の通信状態を把握できない場合、その集約装置との通信途絶を `BATT_COMM_FAIL` と `PV_COMM_FAIL` の同時発報として報告しても差し支えありません。", "type": "string", "enum": [ "BATT_SOC_LOW", "BATT_SOH_DEGRADED", "BATT_OVERTEMP", "BATT_COMM_FAIL", "BATT_OTHER", "PV_COMM_FAIL", "PV_OTHER", "CURT_COMM_FAIL", "GRID_OTHER", "SETPOINT_UNREACHABLE", "UNKNOWN_FAULT" ] }, "ErrorCode": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "エラーコード", "description": "標準化されたエラーコード。詳細な意味についてはプロトコル仕様の「エラーコード」セクションを参照してください。なお `INTERNAL_ERROR` は、形式は妥当なコマンドが、ACK送出前の受信時処理で受理・コミットできずに失敗した場合（例: 要求されたスケジュール変更のコミットに内部的に失敗した場合）も対象とします。", "type": "string", "enum": [ "MESSAGE_MALFORMED", "MISSING_FIELD", "TYPE_MISMATCH", "FIELD_OUT_OF_RANGE", "TIME_WINDOW_INVALID", "DUPLICATE", "EXPIRED", "RESOURCE_UNAVAILABLE", "INTERNAL_ERROR" ] } }, "securitySchemes": { "awsIotCore": { "type": "X509", "description": "AWS IoT CoreのX.509証明書認証。証明書はTensor Energyが発行。" } } } }