BNB ChainまたはPolygonのSubgraphをSubgraph Studioのテスト用URLから直接呼び出していた場合、接続先の移行が必要です。The Graphの公式告知によると、両チェーンに対するStudioのステージングクエリは2026年10月8日に終了しました。ただし、Subgraph Studioそのものがなくなったわけではありません。
結論からいえば、対応の中心はSubgraphを分散型Networkへpublishし、Indexerの同期を確認してから、APIキー付きのGraph Gateway URLへアプリを切り替えることです。この記事では、影響判定、互換性確認、公開、課金設定、比較試験、切替後の監視を作業順に説明します。すでにNetworkへ公開済みでGatewayを利用しているチームも、接続先と監視設定を再確認できます。
料金、Gateway URL、対応機能は変更される可能性があるため、作業時には公式画面と文書も照合してください。なお、BNB ChainとPolygonで異なるのは主にmanifestのnetwork値、コントラクトアドレス、startBlockです。publish以降の操作は共通です。
BNB・PolygonのStudioクエリ終了で何が変わったのか
終了したのはStudioのステージングクエリ
終了対象は、BNB ChainまたはPolygonのSubgraphをStudioにdeployし、Studioが発行するステージング用エンドポイントへ照会していた構成です。ステージングは、開発中の版を試し、ログやクエリ結果を確認する場所です。本番アプリの恒久的なデータ取得先として使い続ける構成では、今回の終了によってクエリが失敗する可能性があります。
ここで「チェーンが終了した」「Subgraphのデータが削除された」と解釈しないでください。変更されたのは対象チェーンに対するStudio側のステージング照会です。BNB ChainやPolygon自体、GraphQLという問い合わせ方式、Networkに公開されたSubgraphのGateway照会は別のものです。
Subgraph Studioは版管理・公開・APIキー管理に残る
Studioは引き続き、Subgraphの作成、deployした版の管理、Networkへのpublish、APIキーや利用状況の管理に使います。「Studioを使わなくなる」のではなく、「Studio内のテスト用URLを本番の接続先にせず、公開後はGatewayから照会する」という役割分担に変わります。
対応が必要なケースと不要なケース
| 現在の状態 | 判断 | 次の行動 |
|---|---|---|
| Studioにdeployしただけで旧URLを利用 | 対応が必要 | 互換性確認後にNetworkへpublish |
| Network公開済みだが旧URLも残存 | 接続先ごとに対応 | コード・環境変数・監視を棚卸し |
| Network公開済みでGatewayのみ利用 | 原則として変更なし | URL、キー制限、同期状態を確認 |
まずアプリの実際の通信先を見て判断します。管理画面に公開済みと表示されていても、アプリが古いURLを参照していれば影響を受けます。反対に、Gatewayへ移行済みなら、同じ作業をやり直す必要はありません。
移行前に現状とNetwork互換性を確認する
この節では、旧URLの残存箇所とチェーン別設定を特定し、「どこを見て何なら合格か」を決めます。
deploy先とアプリの参照URLを棚卸しする
本番、ステージング、バッチ、管理画面、サーバーレス関数、CIのテストなど、Subgraphを呼ぶ場所を一覧にします。URLをコードへ直書きしている箇所だけでなく、環境変数、シークレット管理、ホスティング設定、プロキシ、GraphQLクライアントの設定も対象です。BNB版とPolygon版を別々に持つなら、どのサービスがどちらを参照するかも記録します。
棚卸し表には「利用サービス」「チェーン」「現在のURL」「Subgraph名」「公開版」「担当者」「切替方法」「戻し方」を残すと、移行漏れを発見しやすくなります。URLにStudioの識別子があるかだけで判断せず、実際にどの環境へ届くかを公式画面と照合してください。
ログとサンプルクエリで索引エラーを確認する
Studioのログで、Subgraphが対象チェーンのブロックを継続して処理できているか、決定的な索引エラーが出ていないかを確認します。さらに、アプリで重要なGraphQLクエリを数本選び、期待するエンティティと項目が返るか試します。単にHTTP応答が成功しただけでなく、値の欠落、古いブロック、GraphQLのerrors配列も見ます。
決定的な失敗は、同じ入力を処理すれば再び起きる種類の問題で、mappingなどの修正が必要になる場合があります。非決定的な失敗は再試行されることがありますが、放置してよいという意味ではありません。原因と再発状況を記録し、公開判断と切り分けます。
Network非対応機能と複数チェーン設定を点検する
まなぶ「クリプ先生、Studioで動いていれば、そのままNetworkでも動くんですよね？」
クリプ「同じとは限らないよ。高度機能にはNetworkで未対応のものもあるから、manifestとmappingを公開前に確かめよう。」
Studioでテストできる機能のすべてが、分散型Networkでも同じ条件で使えるとは限りません。公式の高度機能一覧と対応ネットワークを照合し、manifestのnetwork、dataSources、features、開始ブロック、テンプレートなどを点検します。未対応機能があれば、公開ボタンを押す前に設計を変更します。
同じコードでもチェーン別の値を混ぜてはいけません。次の表を公開前レビューに使います。network値は実際の公式対応ネットワーク一覧と既存manifestを照合し、推測で書き換えないでください。
| 項目 | BNB Chain版 | Polygon版 | 合格条件 |
|---|---|---|---|
| manifestのnetwork | BNB Chain用の公式network識別子 | Polygon用の公式network識別子 | Studioの対象チェーン表示と一致 |
| dataSources.address | BNB Chain上のコントラクト | Polygon上のコントラクト | チェーンエクスプローラーの実アドレスと一致 |
| startBlock | BNB版デプロイブロック以前 | Polygon版デプロイブロック以前 | 必要イベントを取りこぼさない値 |
| 版名・成果物 | BNBと識別できる名前 | Polygonと識別できる名前 | Studio上で取り違えない |
networks.jsonなどに差分を分離し、ビルド後のsubgraph.yamlも確認します。確認場所はリポジトリとStudioの対象版、見る値はnetwork・address・startBlock、合格条件は3点が対象チェーンの実値と一致することです。不一致ならpublishせず、チェーン別設定へ戻ります。
分散型Networkへのpublishを準備する
この節では、公開する1版を固定し、署名に必要なウォレットとArbitrum Oneのガスを揃えます。索引対象チェーンと公開操作のチェーンは別です。Arbitrum Oneの役割はEthereumのレイヤー2解説も参照してください。
deployとpublishの違いを理解する
manifestは索引対象と処理方法の設定、mappingはチェーン上のイベントをエンティティへ変換するコードです。移行は次の4段階です。
- deploy：開発版をStudioへ送り、ログとクエリを試す。
- publish：テスト済み版を分散型Networkへ登録する。
- Indexer同期：Indexerが対象チェーンのブロックを処理して追いつく。
- Gateway照会：APIキー付きURLから公開Subgraphへ本番クエリを送る。
したがって、deploy成功もpublish成功も単独では本番切替の合格条件になりません。
公開する対象は、テスト済みの特定バージョンです。作業中に別のdeployが入ると、意図しない版を公開しかねません。コミット、ビルド結果、Studio上のバージョンラベル、Subgraphの対象チェーンを作業記録に揃えてから進みます。
ウォレットとArbitrum Oneのガス用ETHを用意する
Networkへの公開はオンチェーン操作を伴い、Arbitrum Oneに対応する署名用ウォレットとガス代用のETHが必要です。これは、索引対象がBNB ChainやPolygonであっても同じです。「どのチェーンのデータを索引するか」と「The Graphの公開操作をどのネットワークで記録するか」は分けて考えます。
組織運用では、個人の普段使いウォレットだけに権限を依存させず、所有者、承認手順、復旧方法を決めます。必要残高は操作時の公式画面で確認し、秘密鍵やシードフレーズをチャット、リポジトリ、チケットへ貼り付けません。GRTによるシグナルは任意の役割を持ちますが、投資判断と公開作業を混同しないことも大切です。
公開するバージョンを確定する
候補版に対してビルド、Studioでの同期、代表クエリ、エラーログを再確認し、公開中は変更を凍結します。版名には意味の分かる番号を付け、変更点、対象チェーン、以前の版からのスキーマ差分を書き残します。ロールバックが必要になった場合に、どのDeploymentへ戻すかも先に決めます。
Subgraphを公開しIndexerの同期を確認する
StudioまたはGraph CLIからpublishする
Studio画面の経路：Subgraph Studioへログインし、対象Subgraphを開き、Versionsでテスト済み版を選び、Publishを押します。接続ウォレットを確認し、公開先とシグナル条件を画面で確認してからArbitrum One上のトランザクションへ署名します。完了表示からExplorerへのリンクを開き、対象Subgraphと版を再確認します。画面名称は更新される場合があるため、最終的には公式公開手順の表記を優先してください。
CLIの最小例：まずStudio画面に表示されるDeploy Keyで認証し、コード生成、ビルド、deployを行います。実際のslugと版ラベルへ置き換え、秘密値はシェル履歴やログへ残さないでください。
graph auth --studio <STUDIO_DEPLOY_KEY>
graph codegen && graph build
graph deploy --studio <SUBGRAPH_SLUG> --version-label <VERSION_LABEL>deploy後はStudioでその版を選び、画面のPublish経路でNetworkへ公開するのが確認しやすい方法です。利用中のGraph CLIが公式のpublishコマンドを案内する場合だけ、その表示と公式文書に従って実行してください。確認場所はStudioのVersionsと署名画面、合格条件は対象チェーン・版・ウォレット・Arbitrum Oneが意図どおりで、トランザクション識別子を取得できることです。
公開トランザクションが受理されたことは、移行完了ではありません。オンチェーン登録の後にIndexerがDeploymentを取得し、対象チェーンのデータを順に処理する段階があります。公開直後に本番トラフィックを全量切り替えないでください。
Graph Explorerで公開状態を確認する
公開後はStudioの完了画面からGraph Explorerを開き、所有者、Subgraph名、対象チェーン、公開版、Subgraph IDを確認します。合格条件は署名した版がExplorerに公開済みとして表示されることです。表示されない、所有者やチェーンが違う場合はURL切替へ進まず、Studioの対象版と公開トランザクションへ戻ります。Explorerの詳細画面は、後でQuery URLを取得する起点です。
最新ブロックと索引エラーから同期完了を判断する
まなぶ「クリプ先生、publishが成功したら、すぐURLを差し替えていいですか？」
クリプ「まだ早いよ。Indexerが十分に追いつき、重要なクエリが正しく返ることを確認してから切り替えよう。」
確認場所はExplorerの同期・ヘルス表示とクエリ結果です。索引済み最新ブロックをBNB ChainまたはPolygonの現在ブロックと比較し、チームが事前に定めた許容差以内、決定的な索引エラーなし、代表クエリが期待値どおりなら合格です。開始ブロックが古いほど初回同期量は増えます。一律の待ち時間はないため実測し、差が拡大する、エラーが出る、結果が欠ける場合はmanifest・mapping・Indexer状態の確認へ戻ります。外部データとオンチェーンデータの違いはオラクル問題の解説と混同しないでください。
同期途中でもクエリ応答が返る場合があります。しかし、最新データが揃っていない応答を本番で使えば、残高表示、取引履歴、集計などが欠ける可能性があります。切替条件を「応答した」ではなく、「許容するブロック差以内で、エラーがなく、検証クエリが一致した」と定義します。
APIキー・課金・利用制限を設定する
本番用APIキーを作成して安全に保管する
Network上のSubgraphへGatewayから照会するには、有効なAPIキーが必要です。本番、検証、開発でキーを分けると、利用量と漏えい時の影響範囲を切り分けやすくなります。キーを公開リポジトリへコミットせず、サーバー側のシークレット管理やホスティング環境の保護された変数へ保存します。
ブラウザから直接Gatewayを呼ぶ構成では、通信上キーが利用者から見える可能性を前提にします。キーを「見えないはず」と考えるのではなく、許可ドメインと許可Subgraphを設定し、支出上限と利用監視を組み合わせます。漏えいが疑われる場合の再生成手順も事前に試してください。
月次支出上限と利用量監視を設定する
上限は想定外の支出を抑える一方、低すぎれば正当なアクセスでも照会が止まる可能性があります。通常時の利用量、ピーク、再試行による増加、複数環境の合算を観測して決めます。入力調査にはNetwork上の無料クエリ枠についての公式説明もありますが、条件は更新され得るため、設定時の画面で必ず再確認します。
監視では、総クエリ数だけでなく、キー別、Subgraph別、環境別に変化を見ます。急増したときに、正規の利用増、クライアントの無限リトライ、第三者による不正利用を区別できるログを用意します。
許可ドメインと許可Subgraphを制限する
本番キーを特定のWebドメインと必要なSubgraphだけに制限すれば、キーが他所で使われる範囲を抑えられます。ワイルドカードを広く設定する前に、プレビュー環境やサブドメインを含む正規の呼び出し元を整理します。サーバー間通信ではドメイン制限だけに頼らず、ネットワーク構成、シークレット管理、定期的なローテーションを併用します。
アプリの接続先をGraph Gatewayへ変更する
Explorerから本番用Query URLを取得する
Graph Explorerで対象Subgraphの詳細を開き、Query欄またはAPIキーを使う案内からQuery URLをコピーします。所有者、チェーン、Subgraph IDを先に照合してください。ダミー値による通常経路の書式は次のとおりです。
https://gateway.thegraph.com/api/<GRAPH_API_KEY>/subgraphs/id/<SUBGRAPH_ID>特定版の比較試験でDeployment ID経路を使う場合は、Explorerまたは公式Serving Queries文書がその時点で示すURLをコピーし、通常経路と混ぜないでください。合格条件は、コピー元が目的のSubgraphで、有効なキーを入れた検証リクエストが成功することです。
APIキーを含むGateway URLへ差し替える
URLはコードへ直書きせず、たとえばサーバー側の環境変数へ分けます。フロントエンドへ埋め込む場合はキーが閲覧可能になる前提で、許可ドメインと許可Subgraph、支出上限を必ず設定します。
GRAPH_API_KEY=<GRAPH_API_KEY>
GRAPH_SUBGRAPH_ID=<SUBGRAPH_ID>
GRAPH_GATEWAY_URL=https://gateway.thegraph.com/api/<GRAPH_API_KEY>/subgraphs/id/<SUBGRAPH_ID>設定後はアプリを再デプロイし、実行時に旧Studio URLではなくGatewayへ送信されることをネットワークログで確認します。キー本体を例外ログ、分析サービス、サポートチケットへ出力しないでください。APIキーを狙う誘導や秘密情報の送信要求には、暗号資産詐欺の予防策と同様に応じないことが基本です。
キー入りURLを画面、例外ログ、分析サービス、サポートチケットへそのまま出力しないようにします。アプリ内でURLを組み立てる場合も、キー部分をマスクしたログ関数を使います。過去ログに旧キーが残っているなら、公開範囲を確認し、必要に応じて再生成します。
Subgraph IDとDeployment IDを使い分ける
まなぶ「クリプ先生、Subgraph IDとDeployment IDは同じものですか？」
クリプ「役割が違うよ。通常はSubgraph IDで公開中の版を参照し、特定版へ固定したい検証ではDeployment IDを使うんだ。」
Subgraph IDによる経路は、Subgraphとして公開されている版をたどる通常の利用に向きます。Deployment IDは特定の配置物を直接指定するため、比較試験や明示的な版固定に使えます。ただし、固定したままでは新しい公開版へ自動的に追従しません。
本番でどちらを採用するかは、更新運用と障害時の戻し方を含めて決めます。IDを取り違えると、古い版を参照し続けたり、意図しない最新版へ進んだりします。設定値にはIDの種類を示す変数名を使い、レビュー時にExplorerの表示と照合します。
本番切替前後の動作を比較検証する
Explorerで同一クエリを事前検証する
アプリで頻繁に使うもの、ページネーションを使うもの、絞り込みや並び替えがあるもの、空結果になりやすいものを検証セットにします。旧環境がまだ比較可能なら、変数と時点を揃えて同じGraphQLクエリを送り、レスポンスを保存します。旧環境が利用できない場合は、既知のトランザクションや過去に保存した期待値と比較します。
データ・最新ブロック・エラー・遅延を比較する
比較対象はレコード件数だけではありません。主要なIDと値、並び順、ページ境界、最新ブロック、GraphQLエラー、HTTP状態、応答時間を見ます。ブロックが進行中なら完全一致しないこともあるため、同じブロック範囲へ絞るなど、差の理由を説明できる条件に揃えます。
遅延は一度の測定で結論を出さず、通常時と負荷時に複数回観測します。自動キュレーションやIndexerの存在は、個々のアプリに必要な性能を保証しません。利用地域、クエリの複雑さ、返却量も含め、アプリ側の許容値で判断します。
リトライとフォールバック方針を決める
一時的な通信エラーには、間隔を広げるリトライと回数上限を設けます。即時の無限再試行は障害を増幅し、利用量も押し上げます。読み取り処理であっても、同じ重いクエリを大量に再送しないようにします。
Graph Clientには複数Indexer、タイムアウト、retry、fallbackに関する機能がありますが、導入すれば自動的に安全になるわけではありません。古いキャッシュを返すのか、機能を一時停止するのか、ユーザーへ更新遅延を表示するのかをサービス要件に沿って決めます。異なる版へのフォールバックはスキーマ互換性も確認します。
切替可否は、担当者の感覚ではなく、事前に決めた受け入れ条件で判定します。たとえば、必須クエリがすべて成功すること、許容する最新ブロックとの差を超えないこと、想定するエラー処理が動くこと、APIキーの制限で正規の呼び出しだけが通ることを確認項目にします。入力調査は具体的なしきい値を示していないため、秒数や件数を一律に置かず、各サービスの要件から決めてください。
異常が出た場合は、まず認証、公開状態、同期、クエリ、アプリ実装のどこに原因があるかを分けます。HTTPの認証エラーならキーとURLの組み立て、GraphQLエラーならスキーマと変数、古い結果なら同期ブロック、タイムアウトならクエリ量とクライアント設定を確認します。複数の変更を一度に戻すと原因が分からなくなるため、設定変更の履歴を残し、一項目ずつ検証します。
旧環境との結果差が出たときは、ただちに新環境の誤りと決めつけません。照会時点のブロック、並び順の指定、ページネーションのカーソル、同名フィールドの型、欠損値の扱いを揃えます。対象チェーンが進行している以上、時刻だけを合わせても参照ブロックが異なることがあります。再現用クエリには変数と期待値に加え、確認したブロック情報も保存します。
切替後の監視と旧版整理で移行を完了する
Gatewayへ切り替えて実測値を監視する
可能なら検証環境、社内利用、一部トラフィック、本番全量の順に切り替えます。各段階で成功率、GraphQLエラー、応答時間、データの最新性、Indexerの同期、Gateway利用量を確認します。切替時刻、設定変更、担当者を記録すると、異常との因果関係を追いやすくなります。
アラートには、単発の失敗だけでなく、一定期間のエラー増加、ブロック差の拡大、応答時間の悪化を使います。チェーン側の一時的な停止と、Subgraphのmappingエラー、Gateway認証エラーを同じ障害として扱わず、観測点を分けてください。
支出上限到達とAPIキー不正利用を検知する
利用量が通常範囲を超えたら通知し、キー別と呼び出し元別に追跡します。上限到達は費用を止める安全装置である一方、アプリのデータ取得停止にもつながり得ます。上限に近づいたときの連絡先、増額判断、キー停止、不正アクセス遮断を運用手順に含めます。
不正利用を疑う兆候には、通常使わない時間帯やドメインからの急増、廃止した画面だけが使うクエリの再出現、単一クエリの高頻度な反復などがあります。監視で兆候を見つけたら、まず影響範囲を把握し、制限の強化またはキー再生成を行います。その後、アプリの設定を更新し、古いキーがログ、配布物、ソース履歴に残っていないか調べます。
支出上限を変更するときは、アクセス増の理由を確認します。正常な利用増であれば、上限だけでなくクエリ効率やキャッシュも点検できます。再試行の不具合や第三者利用が原因なら、上限を引き上げるだけでは問題を長引かせます。費用の確認と可用性の判断を同じ担当者だけに集中させず、開発と運用で情報を共有します。
安定稼働を確認してから旧版を整理する
Gateway切替直後に旧版や旧設定を削除すると、問題発生時の比較材料と戻し先を失います。定めた観測期間に主要クエリ、同期、利用量が安定し、関係する全サービスの切替が完了したことを確認してから整理します。公開済みSubgraphの削除はExplorer上の表示や利用者に影響するため、対象を慎重に確認します。
最後に、旧Studio URLがコード、環境変数、ドキュメント、監視、サンプル、CIに残っていないか再検索します。APIキーの不要な権限を外し、一時的な検証キーを失効させ、手順書をGateway前提へ更新します。これで移行は「URLを変えた」状態から、継続運用できる状態になります。
運用メモ：安定確認後に一時キー、不要権限、旧分岐を整理します。一方、Subgraph ID、公開版、トランザクション識別子、比較結果、担当と確認日時は秘密値を除いて保存し、次回publishと障害対応に引き継ぎます。
移行完了チェックリスト
- 旧Studio URLの利用箇所と対象チェーンを棚卸しした
- ログ、代表クエリ、Network互換性を確認した
- 公開版を固定し、ウォレットとArbitrum Oneのガスを準備した
- Networkへpublishし、ExplorerとIndexer同期を確認した
- 本番APIキー、支出上限、ドメイン・Subgraph制限を設定した
- Gateway URLとIDの種類を確認して比較試験した
- 段階的に切り替え、エラー、遅延、最新性、利用量を監視した
- 安定確認後に旧版、旧URL、一時キーを整理した
最も重要なのは、publish成功と本番切替を同じ瞬間にしないことです。公開、同期確認、認証設定、比較検証、段階切替の順を守れば、データ欠損や誤った版の参照、想定外の利用量を発見しやすくなります。
完了証跡として、Explorerの公開版、最新ブロック差、代表クエリ結果、キー制限、利用量、アプリのリリース番号、確認日時を保存します。秘密値は含めません。対象外の環境にも「確認済み・変更不要」と理由を記録します。
核心はpublishと切替を分けることです。公開後に同期とクエリを判定し、APIキー制限を確かめ、段階的にGatewayへ切り替えて初めて移行完了です。
