Extend アプリローカルホスティングでのポートフォワーディングの使用

Last updated on February 4, 2026

注釈：本資料はAI技術を用いて翻訳されています。

概要​

Extend アプリ（Override、Service Extension、Event Handler）は、開発マシン上でローカルに実行されます。AccelByte Gaming Services（AGS）でテストするには、ローカルアプリがインターネット経由でアクセス可能である必要があります。ポートフォワーディングは、ローカルサーバーへのトンネルとなるパブリック URL を作成します。

VS Code ポートフォワーディングは、Microsoft dev tunnels を介してローカル TCP ポートをパブリック HTTPS URL として公開する組み込み機能です。拡張機能やファイアウォールの変更は不要です。このガイドでは、Extend アプリのローカルホスティングテストでの使用方法を説明します。

備考

ngrok や pinggy などの他のトンネルサービスも使用できます。VS Code ポートフォワーディングは、すでに VS Code または Cursor を使用している開発者に推奨されます。追加のツールが不要です。

Extend アプリにポートフォワーディングが必要な理由​

Extend アプリをローカルで開発する場合、アプリは localhost 上で実行されるため、クラウド上の AGS から直接アクセスすることはできません。 ポートフォワーディングは、ローカルサーバーへのトンネルとなるパブリック URL を作成し、開発中に AGS やテストツールなどの外部サービスがアプリと通信できるようにします。 このフォワードされた URL は、AGS でのテスト、ローカルホスティングテスト用の管理ポータルへの登録、または他のツールやサービスからの直接アクセスに使用できます。

前提条件​

  • VS Code または Cursor（ポートフォワーディングサポート付き）
  • Extend アプリがローカルで実行中
  • GitHub または Microsoft アカウント（VS Code トンネル認証用）
  • AGS 管理ポータルへのアクセス（オプション。フォワードされた URL をローカルホスティングテスト用に登録する場合）

ステップバイステップガイド​

1. Extend アプリをローカルで起動​

Docker Compose（推奨）または直接実行して Extend アプリを実行します:

# Docker Compose を使用（最も一般的）
docker compose up --build

# または直接実行（言語によって異なる）
go run main.go
python main.py
dotnet run

アプリログまたは docker-compose.yaml を確認して、ポート番号を確認します。通常、ポート 6565、8000 です。

2. VS Code でアプリポートをフォワード​

  1. VS Code で Ports ビューを開きます:

    • パネルを開く（Ctrl+` / Cmd+`）→ Ports タブ
    • またはコマンドパレットを使用: Ports: Focus on Ports View

  2. Forward a Port をクリック

  3. アプリのポート番号を入力

  4. Enter を押す

  5. プロンプトが表示されたら GitHub または Microsoft アカウントでサインイン（トンネル作成に必要）

Ports ビューには以下が表示されます:

  • Local Address: localhost:<your-port>
  • Forwarded Address: パブリック HTTPS URL（例: https://xxxxx-xxxxx.tunnel.app.dev）
  • Visibility: Private または Public

3. AGS アクセス用のポート可視性を設定​

フォワードされた URL を AGS で使用または登録する場合、ポートの可視性を Public に設定します:

  • ポートを右クリック → Port Visibility > Public
  • AGS がフォワードされた URL にアクセスするには、Public 可視性が必要です
  • URL を持つ誰でもアクセスできます（サインイン不要）
警告

Public ポートは、URL を持つ誰でもアクセスできます。 Extend アプリに適切な認証が有効になっていることを確認してください（例: PLUGIN_GRPC_SERVER_AUTH_ENABLED=true）

4. フォワードされた URL をコピー​

Ports ビューから、Forwarded Address をコピーします。これは、テストに使用したり、管理ポータルに登録したりできるパブリック URL です。

フォワードされた URL の形式は通常次のとおりです:

  • https://xxxxx-xxxxx.tunnel.app.dev または類似
  • VS Code は、ローカルサービスへのトンネルとなる HTTPS URL を提供し、TCP と HTTP の両方のプロトコルを自動的に処理します

5. 管理ポータルにフォワードされた URL を登録​

備考

登録は Extend Override アプリにのみ必要です。Extend Service Extension と Extend Event Handler は管理ポータルへの登録を必要としません。以下のセクションを参照してください。

登録場所は Extend Override タイプによって異なります:

Extend Override:

  • Challenge Goals Assignment: Engagement > Challenges > Customization > Locally Hosted for Testing Purpose
  • Cloud Save Validator: Progression & Inventory > Cloud Save > Customization > Locally Hosted for Testing Purpose
  • Entitlement Revocation: Commerce > Customization > Revocation > Locally Hosted for Testing Purpose
  • Loot Box Roll: Commerce > Customization > Loot Box Roll > Locally Hosted for Testing Purpose
  • Matchmaking: Game Management > New Matchmaking > Custom Function > Register Function > Locally Hosted for Testing Purpose
  • Profanity Filter: Multiplayer > Chat > Configuration > Chat Filter Database > Custom > Locally Hosted for Testing Purpose
  • Rotating Shop Items: Commerce > Customization > Item Rotation > Locally Hosted for Testing Purpose
  • Session Dedicated Server: Multiplayer > Matchmaking > Session Configurations > Add Session Template > Server > DS - Custom > Custom URL
  • Session Manager: Multiplayer > Matchmaking > Session Configurations > Add Session Template > Main Configuration > Use Custom Session Function > Custom URL

Extend Override の一般的な手順:

  1. Configurations を見つける
  2. Custom を見つける
  3. Locally Hosted for Testing Purpose を選択（または類似のオプション、例: Custom URL）
  4. VS Code からフォワードされた URL を構成フィールドに貼り付ける
  5. Register、Save、または Create をクリック（サービスによって異なる）

Extend Service Extension

Extend Service Extension アプリには管理ポータルへの登録は必要ありません。フォワードされた URL をブラウザ、curl で直接使用したり、ゲームコードに統合してカスタム REST エンドポイントを呼び出したりできます。

Extend Event Handler

Extend Event Handler アプリには管理ポータルへの登録は適用されません。AGS がローカルイベントハンドラーを直接呼び出すことはできないためです。イベントハンドラーをローカルでテストするには、フォワードされた URL を使用して、受信イベントを自分でモックします（例: grpcurl を使用してイベントペイロードをシミュレートする）。

6. 統合をテスト​

注記

Extend Override アプリの場合、テスト前にステップ 5（管理ポータルへの登録）を完了してください。Extend Service Extension と Extend Event Handler の場合、フォワードされた URL を使用して直接テストできます。

フォワードされた Extend アプリをテストするには:

  1. リクエストまたはイベントをトリガー:

    • Extend Override: AGS を介して Extend オーバーライド関数をトリガー（例: /apidocs、curl、またはゲームコードから）
    • Extend Service Extension: フォワードされた URL を使用してカスタム REST エンドポイントを直接呼び出し（例: ブラウザ、curl、またはゲームコードから）
    • Extend Event Handler: フォワードされた URL にテストペイロードを送信して受信イベントをモック（例: grpcurl を使用）

  2. 受信リクエストまたはイベント通知のローカルアプリログを監視

  3. アプリがリクエスト/イベントを正しく処理することを確認

考慮事項​

  • プロトコルサポート: VS Code ポートフォワーディングは TCP と HTTP の両方のプロトコルを処理します。TCP ベースのサービス（例: gRPC）の場合、VS Code は HTTPS を介して TCP を自動的にトンネリングします。
  • ポート構成: docker-compose.yaml またはアプリ構成を確認して、アプリがリッスンしているポートを特定します。一般的なポートには 6565、8000 がありますが、アプリは別のポートを使用する場合があります。
  • Envoy プロキシ: grpc-plugin-dependencies と Envoy を使用している場合、アプリの直接ポートではなく、Envoy が公開するポート（通常は 10000）をフォワードします。
  • ベースパス: RESTful サービスの場合、アプリがベースパスを使用している場合（例: /guild）、フォワードされた URL が正しいベースパスを指していることを確認してください。
  • 接続の安定性: テスト中は VS Code とフォワードされたポートをアクティブに保ちます。VS Code を閉じるとトンネルが停止します。
  • 複数のポート: 一部の Extend アプリは複数のポートを公開します（例: メインサービスが 1 つのポート、メトリクスが別のポート）。外部サービスがアクセスする必要があるポートをフォワードします。

代替トンネルサービス​

VS Code ポートフォワーディングがセットアップで機能しない場合、代替手段には次のものがあります:

  • ngrok: ngrok tcp <your-port>（アカウントと認証トークンが必要）
  • pinggy: ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 -R0:127.0.0.1:<your-port> tcp@a.pinggy.io

これらは同様のフォワーディング機能を提供します。フォワードされた URL の形式は同じです。管理ポータルへの登録が必要な Extend Override アプリの場合、登録プロセスは同じです。

ベストプラクティス​

  • VS Code を実行し続ける: トンネルは、ポートがフォワードされた状態で VS Code が開いている間のみアクティブです
  • AGS で使用する場合は Public 可視性を使用
  • 完了したらフォワーディングを停止: ポートを右クリック → Stop Forwarding でリソースを解放
  • トンネル使用量を監視: VS Code には使用制限があります（以下の制限を参照）
  • アプリ認証を確認: プロダクションに近いテスト用にアプリに適切な認証が有効になっていることを確認（例: PLUGIN_GRPC_SERVER_AUTH_ENABLED=true）
  • アプリログを確認: リクエスト/呼び出しがローカルサーバーに到達していることを確認

制限事項​

VS Code トンネル使用制限​

VS Code ポートフォワーディングには使用制限があります（tunneling service usage limits を参照）:

  • トンネルトラフィックの帯域幅クォータ
  • アクティブマシンの数の制限
  • ユーザーあたり最大 10 トンネル（11 番目を作成すると、未使用のランダムなトンネルが削除される場合があります）

ヘビーテストの場合、より高い制限を持つ代替トンネルサービスを検討してください。

組織ポリシー​

組織は、ドメイン global.rel.tunnels.api.visualstudio.com をブロックするか、グループポリシーを構成することで、VS Code トンネルをブロックする場合があります。この場合、ngrok や pinggy などの代替トンネルサービスを使用してください。

リモート開発​

ポートフォワーディングはローカルで実行されているサービスに対してのみ機能します。SSH またはリモート開発の場合、VS Code Remote - Tunnels を使用して最初に接続し、次にリモート環境からポートをフォワードします。

トラブルシューティング​

ポートフォワーディングが開始しない:

  • GitHub/Microsoft アカウントでサインイン
  • アプリが予想されるポートでリッスンしていることを確認
  • ファイアウォールが Microsoft サービスへの発信接続を許可していることを確認
  • VS Code を再起動

AGS がフォワードされた URL に到達できない:

  • ポートの可視性が Public に設定されていることを確認
  • 管理ポータルでフォワードされた URL が正しいことを確認
  • VS Code が実行中で、ポートフォワーディングがアクティブであることを確認
  • ローカルアプリが実行中で応答していることを確認

リクエスト/呼び出しがアプリに到達しない:

  • ポート番号がアプリ構成と一致することを確認
  • 接続試行についてアプリログを確認
  • 認証設定がテストセットアップと一致することを確認（例: PLUGIN_GRPC_SERVER_AUTH_ENABLED）
  • RESTful サービスの場合、ベースパスが正しく構成されていることを確認
  • フォワーディングする前に、まずローカルでテスト（例: curl、grpcurl、または gRPC クライアント）

ポートがすでに使用中:

  • ポートを使用している他のプロセスを確認
  • VS Code で既存のポートフォワーディングを停止
  • アプリを別のポートを使用するように変更し、代わりにそのポートをフォワード

パフォーマンスの問題:

  • localhost と比較して追加のレイテンシを予想（トンネルオーバーヘッド）
  • トンネル帯域幅使用量を監視
  • プロダクションテストの場合、ローカルホスティングを使用する代わりに AGS にデプロイ
に最終更新
On this page