Googleは、Grounding with Google MapsのレスポンスSchemaを変更し、複数のFieldを削除した。また、Google MapsのWidget Context Tokenは、リクエストでwidget_token_enableを設定した場合に返る方式となった。

この変更はモデル品質より、表示層と監査層へ影響する。削除Fieldを直接参照しているアプリでは、レビュー帰属、通報リンク、説明文、Widget表示が空になるか、例外で停止する可能性がある。

何が変わったか

Vertex AI release notesでは、次のField削除が案内されている。

  • grounding_chunk.maps.text
  • grounding_chunk.maps.place_answer_sources.review_snippets.author_attribution
  • grounding_chunk.maps.place_answer_sources.review_snippets.flag_content_uri
  • grounding_chunk.maps.flag_content_uri

また、Widget Context Tokenは、widget_token_enableを明示したリクエストで返る。

変更前後の差

機能以前変更後
Maps説明テキストmaps.textを参照可能Field削除
Review著者帰属Response Fieldに依存旧Fieldは利用不可
通報URIReview/Maps Fieldに存在旧Field削除
Widget Token暗黙取得を期待する実装あり明示有効化が必要
UI実装Field固定参照Feature Detectionが必要

Schema変更は、SDKの型定義更新より先に本番レスポンスへ現れることがある。型安全なコードでも、Optional化やUnknown Field処理が必要である。

誰に影響するか

  • 場所検索・旅行・店舗推薦を提供する
  • レビュー抜粋と著者情報を表示する
  • Maps Widgetを埋め込む
  • Grounding Metadataを監査ログへ保存する
  • Response JSONをそのままDB schemaへ格納する
  • Field欠損をエラーとして扱う
  • 旧SDK型へ依存している
  • Attributionや利用条件をUIへ反映する

バックエンドが正常でも、フロントエンドの表示欠損として発見される可能性が高い。

必要な対応

レスポンスを「固定JSON」ではなく、バージョン変化する外部契約として扱う。UIが必要とする意味を抽象化する。

place_id
display_name
map_uri
source_attribution
review_excerpt
review_author
widget_context
reporting_action

各意味に対し、現在の公式FieldまたはWidgetから取得できるかを確認する。削除された情報を推測で補完しない。

実装・移行手順

1. Field参照を検索する

コード、型定義、JSONPath、ETL、ログ、BI、テストFixtureで削除Fieldを検索する。フロントだけでなく、データ基盤も確認する。

2. Optional処理へ変更する

存在しないFieldで例外を投げず、表示要素を安全に省略する。null、欠損、空配列を区別する。

3. Widget Tokenを明示する

Maps Widgetを表示するリクエストだけでwidget_token_enableを有効化する。不要な処理へ一律追加せず、Tokenの有効期限、再利用、ログ保存を公式仕様へ合わせる。

4. Attributionを再確認する

Google Mapsデータの表示には帰属・利用条件が関係する。旧Field削除後も、現在の公式UI要件とTermsへ従う。独自に著者名や通報リンクを生成しない。

5. Schema Contract Testを作る

実APIのサンプルレスポンスから、必須・任意Fieldを検査する。Unknown Fieldは許容し、必要Fieldの欠損はアラートにする。

6. 保存Schemaを分離する

外部Response JSONをそのまま永続DBの業務Schemaにしない。Raw Responseの短期保管と、正規化した内部Schemaを分ける。

失敗しやすい点

  • 削除Fieldを空文字で埋め、機能欠落を隠す
  • Widget TokenをURL、APM、分析ログへ残す
  • SDK更新だけで移行完了とする
  • 古い保存データと新データを同じSchema Versionで扱う
  • Attribution要件を独自解釈し、非公式データで補う

UI上は動いて見えても、著者帰属や通報導線が失われる。取得日時とSchema Versionを保存する。

評価方法

  • 削除Field参照の残存件数
  • GroundingレスポンスParse成功率
  • Widget表示成功率
  • Widget Token欠損率
  • Place Link・Citationのクリック可能率
  • Attribution UIの要件適合率
  • Schema別の保存件数
  • 欠損Fieldによるフロント例外件数
  • 旧Fixtureを使うテスト比率
  • 実API Contract Testの成功率

主要な場所種別、レビューあり・なし、複数候補、地域、言語、モバイルを含める。

ロールバック

新UIで問題が起きた場合、Maps Grounding機能をFeature Flagで非表示にし、通常のモデル回答または自社の場所検索へ戻す。削除Fieldへ依存する旧コードへ戻しても復旧しない。

  1. Widget表示を停止する
  2. Grounded回答に「地図情報を一時利用できない」状態を設ける
  3. Parseエラーを非致命化する
  4. Raw ResponseとSchema Versionを確認する
  5. 公式Fieldに合わせてAdapterを修正する
  6. Contract Test後に再開する

旧レスポンスを再現できると仮定しないことが重要である。

編集部分析

この変更は、外部AI APIのレスポンスを業務DBとして直接扱う危険を示している。生成AI関連APIは、モデルだけでなくGrounding MetadataやCitation Fieldも進化し、Field削除が発生する。

強い設計は、Provider Responseを境界Adapterで受け、内部の意味モデルへ変換する。UIや監査ログがProvider固有の深いJSONPathを直接参照しないようにする。

また、Widget Tokenの明示化は、機能利用の意図をコードで表す改善でもある。必要な画面だけで有効にし、地図表示と回答生成を分離すると、費用・監査・障害範囲を管理しやすい。

実務チェックリスト

  • [ ] 削除された4Fieldの参照を全リポジトリで検索した
  • [ ] 欠損・null・空配列を安全に処理する
  • [ ] Widget利用時だけwidget_token_enableを設定した
  • [ ] Tokenをログや分析基盤へ不用意に保存していない
  • [ ] Attributionと利用条件を最新公式仕様で確認した
  • [ ] Provider Responseを内部Schemaへ変換している
  • [ ] Raw Responseに取得日時とSchema Versionを付けた
  • [ ] 実APIを使うContract Testを追加した
  • [ ] Maps機能を停止できるFeature Flagがある
  • [ ] 旧Fieldを推測値で補完していない

一次情報