メインコンテンツへ

プロトコルバージョン変更履歴

このページはTensor Cloud蓄電池最適化プロトコルの変更を記録します。ここに記載されたバージョンは AsyncAPI仕様 の info.version およびEMSが各メッセージに含める schema_version フィールドに反映されます。

バージョニングはsemver形式（MAJOR.MINOR.PATCH）に従います。

  • MAJOR - トピック構造、ペイロード形状、必須フィールドへの後方非互換変更。既存のインテグレーションがコード変更なしに対応できないもの。
  • MINOR - 追加的な変更（新規フィールド、新規条件付きバリデーション、新規挙動）で、保証は強化されるが旧バージョンのクライアントでも読み取り可能。Tensor Cloudは旧マイナーリビジョンで送信されたメッセージとの後方互換性を維持します。
  • PATCH - ドキュメントの明確化、例の修正、ペイロードに影響しない変更。PATCHリリースはペイロードに影響しないため、ワイヤ上の schema_version は変更されません。MINORまたはMAJORリリースでペイロードが変わるまで、連携は現行のMINORバージョン（例: 2.3.0）を送出し続けます。

2.8.0 - 2026-08-17​

瞬時電力および系統周波数のバッチテレメトリ。 追加的かつ任意であり、単一メッセージ形式のテレメトリは変更ありません。

  • 任意のトピック dt/{siteId}/{gatewayId}/{metric}/power/batch および dt/{siteId}/{gatewayId}/frequency/batch を追加し、PowerInstantBatch と GridFrequencyBatch を定義しました。他のチャネルにバッチ形式はありません。
  • バッチは unit、aggregation、aggregation_window、pre_qualification を一度だけ指定し、measurements の各要素が自身の message_id、measurement_ts、value を持ちます。指定したフィールドが変わる場合はバッチを分割します。
  • 要素は measurement_ts の昇順に厳密に並べ、タイムスタンプと要素の message_id はバッチ内で一意とします。要素の message_id がバッチ自身の message_id と一致してはなりません。minItems は1、maxItems は900、エンコード後のペイロードは最大122,880バイトです。
  • バッチは全体が受理されるか、全体が拒否されるかのいずれかです（2.7.0のコマンド検証と同様）。
  • 重複排除は各要素の message_id をキーとします。バッチ自身の message_id は送信の試行を識別するだけであり、元のIDのまま異なるバッチへ組み直すことも、単一メッセージ形式で再送することもできます。
  • バッチトピックではQoS 1が必須であり、MQTTのRETAINフラグを設定してはいけません。
  • DUPLICATE の定義を明確化しました。元の message_id のまま内容を変更せずに再送することは、重複ではなく冪等な成功です。単一メッセージ形式のテレメトリにも当てはまり、挙動の変更はありません。
  • バッチ送信はサイトごとに有効化し、既定ではバックフィルのみが対象です。詳細はインテグレーターガイドを参照してください。
  • インテグレーターチェックリストに項目 BA-1 から BA-6 を追加しました。
  • ワイヤ上の schema_version を 2.8.0 に更新しました。

2.7.0 - 2026-08-13​

GRID_OTHER アラートコードの追加と、コマンド検証の全件一括化。 追加的かつ後方互換です。

  • AlertCode に GRID_OTHER を追加しました。既存のコードでは表現できないAC側の系統障害、すなわち系統連系の喪失、保護リレーや系統連系用遮断器のトリップ、受電点における電圧・周波数の許容範囲逸脱、EMSがなお報告可能なサイト全体の停電などに使用します。従来はサブシステムの情報を持たない UNKNOWN_FAULT で報告するほかありませんでした。詳細はインテグレーターガイドの「アラートコードリファレンス」節を参照してください。
  • 1つの障害が複数のアラートコードに該当しうること、およびTensor Cloudがそれを重複排除せず想定される挙動として扱うことを明記しました。DCリンクのシステムで、太陽光アレイと蓄電池が共有するハードウェア（ハイブリッドインバータ、共通のパワーコンディショニング設備、共通の制御・集約装置）に障害が発生した場合は、PV_OTHER と BATT_OTHER の両方で報告します。EMSが単一の集約装置を介して両サブシステムに接続しており、BMS単位・PVPCS単位の通信状態を把握できない場合、当該集約装置との通信途絶時に BATT_COMM_FAIL と PV_COMM_FAIL を同時に発報して差し支えありません。インテグレーターチェックリストに項目 A-6 - 共有ハードウェア障害での全該当コードの発報 を追加しました（検証方法はインテグレーターテストのみ）。
  • コマンドの検証が**全件一括（all-or-nothing）**であることを明記しました。control.schedule の項目が1件でも検証に失敗した場合、EMSはそのコマンドの項目を、妥当だったものも含めていずれも適用せず、直前まで有効だったスケジュールの実行を継続します。これは BatteryPowerCommand と BatteryFcrCommand の双方、および一次調整力の action: "execute" と action: "cancel" の双方に適用されます。CommandResponse.status には部分適用を表す値がないため、部分的に適用されたコマンドを正確に応答することはできません。また、適用されなかったスロットはスロット単位の解決規則により古いコマンドにフォールバックし、置き換えるはずだったスケジュールを暗黙に復活させます。errors[] には、最初のエラーで打ち切らず不正な項目ごとに1件を含めてください。インテグレーターチェックリストに、電力設定値コマンド向けの AR-15 - 妥当な項目と不正な項目が混在するスケジュール と、一次調整力のexecute/cancel向けの FC-10 - 妥当な項目と不正な項目が混在するスケジュール（一次調整力） を追加しました（いずれも検証方法はインテグレーターテストのみ）。
  • alertState のスナップショットを、アラートの発報有無にかかわらず所定の周期で発行することを明記しました。アクティブなアラートがない場合は、発行を省略せず measurement_value を空配列として発行します。空配列は「サイトが正常である」ことを積極的に示すものであり、これがないとTensor Cloud側で正常なサイトと報告が止まったEMSを区別できません。チェックリストに項目 A-5 - アクティブなアラートがない場合のalertStateスナップショット を追加しました。
  • BatteryPowerCommand のスケジュール区間に、任意フィールド reference_point（"battery" または "grid"）を追加しました。その区間の power_kw がどの地点を指すかを示します。"battery" は値が蓄電池そのものを指し、併設の発電はそのまま通過することを意味するため、0 は蓄電池の待機となります。"grid" はサイトの計量地点（受電点。meter_export_ac および meter_import_ac を計測する地点であり、構内需要があるサイトではインバータのAC出力とは一致しません）を指すため、0 は受電点をゼロに保ち、蓄電池がその時点の発電量を吸収することを意味します。フィールドを省略した場合は "battery" となるため、2.7.0より前に発行されたコマンドは従来どおりの意味を保ちます。基準点をサイトの構成から推測することはありません。蓄電池と太陽光がインバータを共有するDC連系のシステムでは、EMSは実測の太陽光出力に基づきAC設定値を補正することで "battery" を実現し、太陽光の予測誤差が蓄電池に及ばないようにします。Tensor Cloudはすべてのコマンドでこのフィールドを明示し、"grid" はEMSが schema_version 2.7.0以降を報告するサイトにのみ送信します。チェックリストに項目 AR-16 - reference_pointの解釈 を追加し、仕様書に BatteryPowerCommand の実例を初めて掲載しました。
  • AlertCode に SETPOINT_UNREACHABLE を追加し、スケジュール解釈ルール9を新設しました。EMSが指令された設定値を実現できない場合（"battery" の区間でのインバータ制限、"grid" の区間での蓄電量の制限など）は、到達可能な最も近い値にクランプして実行を継続し、到達を妨げた制限を示すこのアラートを発報します。コマンドの拒否も蓄電池の停止も行いません。これは、確認応答が受信時点の検証のみを対象とするという2.3.1の規定と整合します。従来このケースの挙動は定義されていませんでした。チェックリストに項目 AR-17 - 到達できない設定値のクランプと発報 を追加しました（検証方法はインテグレーターテストのみ）。
  • 出力抑制テレメトリの要否に関する記述の矛盾を解消しました。Curtailment メッセージのサマリーは任意と記載し、しかも系統用蓄電池システムで特に有用であるとしていた一方、インテグレーターガイドは全構成で🔴必須としていました。出力抑制は系統用蓄電池を含むすべての構成で必須です。太陽光を併設しないサイトであってもTSOの出力抑制の対象となる場合があります。インテグレーターガイドの記載が正しく、変更していません。メッセージのサマリーと curtailment チャネルの説明をこれに合わせ、チェックリストの PT-S には、日射量が対象外となる一方で出力抑制は系統用蓄電池でも引き続き必須であることを明記しました。SO-3 は太陽光固有のケースを検証する項目であるため、従来の適用範囲のままです。ペイロードの変更はありません。チャネルおよびメッセージの構造は従来どおりです。
  • ワイヤ上の schema_version が 2.7.0 に更新されます。バージョニングポリシーに従い、MINORリリースではワイヤバージョンが更新されるため、連携は今後 schema_version: "2.7.0" を送出してください。Tensor Cloudは旧バージョンで送信されたメッセージとの後方互換性を維持します。

2.6.1 - 2026-07-28​

ウィンドウ測定における measurement_ts を明確化しました。 ドキュメントのみの変更で、ペイロードの変更はありません。

  • 一定の期間を対象とする測定では、measurement_ts が常にその期間の開始時刻を表し、終了時刻や中間時刻を表さないことを明記しました。これはウィンドウエネルギーテレメトリ（measurement_value.start_ts と一致します）、および aggregation: "average" で送信する電力・系統周波数テレメトリ（aggregation_window の開始時刻となります）に適用されます。瞬時値のテレメトリ（ライフタイム積算値、aggregation: "instant" の電力、日射量、太陽光のDC電圧・電流、蓄電池状態、アラート）では、従来どおり測定した時点そのものを表します。
  • EnergyWindowed、PowerInstant、GridFrequency の measurement_ts の説明、および仕様の info.description にこの規則を明記しました。詳細はインテグレーターガイドの「タイムスタンプ境界規則」節を参照してください。
  • Curtailment は測定値ではなくスケジュールであるため、その measurement_ts の扱いを明記しました。一般送配電事業者（TSO）のデータにスケジュールの作成時刻が含まれる場合はその作成時刻を、含まれない場合はEMSがTSOからスケジュールを受信した時刻を設定します。スケジュールが対象とする期間は従来どおり measurement_value[].start_ts および measurement_value[].end_ts で表します。
  • インテグレーターチェックリストに項目 E-7 - measurement_tsの整合 を追加しました（ページおよびダウンロード可能なExcelチェックリストの両方）。
  • インテグレーターガイドの「イベントとアラート」節に、アラートメッセージのフローを示すシーケンス図を追加しました。
  • バージョニングポリシーに従い、PATCHリリースではワイヤ上の schema_version は変更されません。連携は引き続き 2.6.0 を送出してください。

2.6.0 - 2026-07-13​

DCリンクシステム向けの太陽光DC電圧・電流テレメトリ。 追加的かつ後方互換です。

  • 新しい solarDcTelemetry チャネル（dt/{siteId}/{gatewayId}/solar）を、SolarDcElectrical メッセージおよび sendSolarDc オペレーションとともに追加しました。DCリンクの太陽光発電＋蓄電池サイトは、太陽光アレイのDC電圧（V）および電流（A）を、インバータより上流のDCリンクで、アレイ全体を集約した単一の値として公開します。電圧と電流は同一時刻にサンプリングし、一組の測定値として、1分間隔でまとめて送信します。measurement_value は voltage と current を含み、それぞれ {value, unit} オブジェクト（unit は V または A、値は0以上）です。DCリンクのサイトにのみ適用され、ACリンクおよびスタンドアロンのサイトでは送信しません。詳細はインテグレーターガイドの「DC連系テレメトリ」節を参照してください。
  • ワイヤ上の schema_version が 2.6.0 に更新されます。バージョニングポリシーに従い、MINORリリースではワイヤバージョンが更新されるため、連携は今後 schema_version: "2.6.0" を送出してください。Tensor Cloudは旧バージョンで送信されたメッセージとの後方互換性を維持します。

2.5.0 - 2026-07-10​

不正な形式のテレメトリにもACKを返せるようになりました。 追加的かつ後方互換です。

  • TelemetryFeedback.correlation_id から msg_ UUIDパターンの制約を撤廃しました。受信したテレメトリを解析できず（MESSAGE_MALFORMED）、その message_id を復元できない場合、Tensor Cloudは correlation_id にセンチネル文字列 "unknown" を設定します。従来はこのパターン制約のためフィードバックメッセージ自体を構成できず、ACKがまったく送出されないため、インテグレーターはメッセージが拒否されたことを知る手段がありませんでした。message_id が一部復元できる場合は、復元した値を設定します。これは CommandResponse.command_id で既に使用されている "unknown" センチネルと同じ方式です。
  • TelemetryFeedback に任意の topic フィールドを追加しました。問題となったメッセージがパブリッシュされたトピックを示します。status が error の場合にのみ含まれ、correlation_id が "unknown" の場合に拒否されたメッセージを特定する唯一の手段となります。status: "ok" の場合に topic を含めてはならないことは、既に code と detail を制御している if/then/else ブロックで強制されます。
  • 日本語版の TelemetryFeedback 定義を修正しました。schema_version が必須として列挙されているにもかかわらずプロパティが定義されておらず、例が自身のスキーマに対して不正な状態でした。
  • ワイヤ上の schema_version が 2.5.0 に更新されます。バージョニングポリシーに従い、MINORリリースではワイヤバージョンが更新されるため、連携は今後 schema_version: "2.5.0" を送出してください。Tensor Cloudは旧バージョンで送信されたメッセージとの後方互換性を維持します。

2.4.0 - 2026-07-06​

一次調整力向けの系統周波数テレメトリと、事前審査フラグ。 いずれも追加的かつ後方互換です。

  • 新しい gridFrequencyTelemetry チャネル（dt/{siteId}/{gatewayId}/frequency）を、GridFrequency メッセージおよび sendGridFrequency オペレーションとともに追加しました。一次調整力に約定したリソースは、すべての一次調整力約定コマの全期間にわたり、系統周波数を各1秒ウィンドウの平均として1 Hzで公開する必要があります。周波数は系統接続ポイントで実際のAC電圧波形から測定し、0.0001 Hz以上の分解能で報告します。これらの測定値は一次調整力アセスメントⅡで用いる1 Hzの供出電力テレメトリと時刻が揃えられます。詳細はインテグレーターガイドの「アセスメントⅡ報告」節を参照してください。
  • PowerInstant と GridFrequency に任意の pre_qualification ブール値を追加しました。EMSは、一次調整力の事前審査（プレクオリフィケーション）モードで送信する瞬時電力および系統周波数のテレメトリに true を設定します。このモードはTensor CloudではなくEMS運用者が有効化します。Tensor Cloudはこのフラグを用いて、該当期間を最適化および一次調整力アセスメントⅡの提出対象から除外します。任意かつ後方互換であり、省略した場合は通常運用時の意味のままです。
  • ワイヤ上の schema_version が 2.4.0 に更新されます。バージョニングポリシーに従い、MINORリリースではワイヤバージョンが更新されるため、連携は今後 schema_version: "2.4.0" を送出してください。Tensor Cloudは旧バージョンで送信されたメッセージとの後方互換性を維持します。

2.3.1 - 2026-06-29​

ACKと INTERNAL_ERROR の意味を明確化。 ドキュメントのみの変更で、ペイロードへの影響はありません。

  • CommandResponse.status フィールドが、実行結果ではなく受信時点の検証・受理結果を表すことを明確化しました。ACKはコマンドを受信・パースし、コミット（受理）した直後に送出され、実行時には送出されず、実行時にのみ顕在化する失敗は報告できません。
  • INTERNAL_ERROR が、形式は妥当なコマンドがACK送出前の受信時処理で受理・コミットできずに失敗した場合（例: 要求されたスケジュール変更のコミットに内部的に失敗した場合）も対象とすることを明確化しました。detail に内容を記載したうえで INTERNAL_ERROR を使用してください。実行時にのみ顕在化する失敗は、ACKではなくアラート／テレメトリで報告します。
  • PATCHリリースではワイヤ上の schema_version が変更されないことを明記しました（上記のバージョニング注記を参照）。

2.3.0 - 2026-06-16​

アセスメントⅡ用テレメトリ:

  • 瞬時電力トピック（dt/{siteId}/{gatewayId}/{metric}/power）が、オフラインの一次調整力アセスメントⅡデータの送信チャネルとして文書化されました。一次調整力を提供するリソースは、すべての一次調整力約定コマについて、meter_export_ac/meter_import_ac（受電点参入）または battery_discharge_ac/battery_charge_ac（機器点参入）で1秒解像度の供出電力を公開する必要があります。Tensor CloudはこのデータからTSOのアセスメントⅡ様式（様式35）を作成し、アグリゲーターに代わって提出します。詳細はインテグレーターガイドの「アセスメントⅡ用テレメトリ」を参照してください。
  • AsyncAPI仕様の powerTelemetry チャネルの説明を、このアセスメントⅡ用途を示すように更新しました。
  • PowerInstant.measurement_value に2つの任意フィールドを追加しました: aggregation（デフォルト instant、または average）と aggregation_window（ISO-8601期間、例: PT1S）。aggregation が average のとき aggregation_window が条件付き必須になります（JSON Schemaの if/then で強制）。これにより電力サンプルが瞬時点の値か区間平均かを宣言できます。一次調整力アセスメントⅡでは average を PT1S で使用します。追加的かつ後方互換: 両フィールドを省略すると従来の瞬時値の意味のままであり、旧バージョンのメッセージも引き続き受け入れられます。

2.2.0 - 2026-05-28​

アラート、確認応答、コマンドの強化:

  • AlertEvent と AlertState のペイロードで schema_version が必須になりました。以前はフィールドは定義されていましたが、どちらのアラートメッセージの required リストにも含まれていませんでした。Tensor Cloudは schema_version を省略する旧バージョンで送信されたアラートペイロードも引き続き受け入れます。EMS実装は今後アラートペイロードにこのフィールドを追加してください。
  • CommandResponse.errors がスキーマで条件付き必須になりました: status: "error" のとき存在（≥ 1件）、status: "ok" のとき不在。JSON Schemaの if/then/else で強制されます。以前は散文のみで規定されていました。既に散文ルールに従っていたEMS実装には送信側の変更は不要です。
  • TelemetryFeedback.code と TelemetryFeedback.detail がスキーマで条件付き必須になりました: status: "error" のとき両方存在、status: "ok" のとき両方不在。JSON Schemaの if/then/else で強制されます。テスト専用のテレメトリフィードバックチャネルに影響します。Tensor Cloudが送信側であり、EMS実装は受信のみを行います。
  • BatteryFcrCommand.control.schedule[*].capacity_kw がスキーマで条件付きになりました: control.action が execute（デフォルト）のとき必須、cancel のとき禁止。JSON Schemaの if/then/else で強制されます。
  • BatteryPowerCommand.control.schedule と BatteryFcrCommand.control.schedule に minItems: 1 を宣言しました。空のスケジュールはスキーマ層で拒否されます。
  • 埋め込みスキーマ例を修正: CommandResponse の例に必須の schema_version を追加。一次調整力 キャンセル例の message_id 値を文書化された ^msg_[0-9a-f]{8}-…$ パターンに合致する値に修正。
  • すべてのメッセージファミリーのトップレベル additionalProperties を true に統一しました（BatteryPowerCommand と BatteryFcrCommand を含む）。以前はコマンドが厳密で他のファミリーが寛容という非対称性がありましたが、これを解消してプロトコル全体で前方互換性を統一しました。

2.1.0 - 以前のベースライン​

変更履歴ページ以前のベースライン。インテグレーションガイドおよびAsyncAPI仕様に記載されたテレメトリ、コマンド、アラート、レスポンスの全チャネル一式を含みます。