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

Last updated on July 14, 2026

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

Overview​

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

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

備考

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

Extend アプリでポートフォワーディングを使用する理由​

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

前提条件​

  • VS Code または Cursor（ポートフォワーディングをサポート）
  • ローカルで実行中の Extend アプリ
  • GitHub または Microsoft アカウント（VS Code トンネル認証用）
  • AGS Admin Portal へのアクセス（オプション。ローカルホスティングテスト用にフォワードされた 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 をコピーします。これは、テストに使用したり、Admin Portal に登録したりできるパブリック URL です。

フォワードされた URL の形式は通常次のようになります。

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

5. フォワードされた URL を Admin Portal に登録する​

備考

登録が必要なのは Extend Override アプリのみです。Extend Service Extension と Extend Event Handler では Admin Portal への登録は不要です。詳細は以下の各セクションを参照してください。

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

Extend Override:

  • Challenge Goals Assignment: Online > Challenges > Customization > Locally Hosted for Testing Purpose
  • Cloud Save Validator: Online > Cloud Save > Customization > Locally Hosted for Testing Purpose
  • Entitlement Revocation: Online > Store & Catalog > Customization > Revocation > Locally Hosted for Testing Purpose
  • Loot Box Roll: Online > Store & Catalog > 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: Online > Store & Catalog > 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 アプリでは、Admin Portal への登録は不要です。フォワードされた URL を、ブラウザや curl で直接使用したり、ゲームコードに組み込んでカスタム REST エンドポイントを呼び出すことができます。

Extend Event Handler

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

6. インテグレーションをテストする​

注記

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

フォワードされた Extend アプリをテストするには、以下の手順に従います。

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

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

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

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

考慮事項​

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

代替のトンネルサービス​

VS Code ポートフォワーディングが環境で動作しない場合、以下のような代替方法があります。

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

これらは同様のフォワーディング機能を提供します。フォワードされた URL の形式は同じです。Admin Portal への登録が必要な 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 に設定されていることを確認してください
  • Admin Portal 内のフォワードされた URL が正しいことを確認してください
  • VS Code が実行中で、ポートフォワーディングがアクティブであることを確認してください
  • ローカルアプリが実行中で応答可能であることを確認してください

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

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

ポートが既に使用されている場合:

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

パフォーマンスの問題:

  • localhost と比較して追加のレイテンシが発生することを想定してください（トンネルのオーバーヘッド）
  • トンネルの帯域幅使用量を監視してください
  • 本番環境に近いテストを行う場合は、ローカルホスティングの代わりに AGS にデプロイしてください
に最終更新
On this page