ネットワーク要件

RealityConnect APIを利用するには、以下に記載するホストへのアウトバウンドHTTPSアクセスが必要です。このページでは、ネットワーク経路全体(到達可能である必要があるもの、プロキシとTLSインスペクションが接続に与える影響、ネットワークの問題と認証の問題の区別方法)を扱います。

要件のまとめ

アウトバウンドのみ、HTTPS(ポート443)経由。 インバウンドのポート、ファイアウォールルール、NATは一切不要です。インバウンドアクセスを参照してください。
以下のホスト名へのアウトバウンドHTTPSを許可してください。
標準的な企業のフォワードプロキシは、認証が必要なものも含めて透過的に動作します。 フォワードプロキシを参照してください。
TLSインスペクションプロキシは接続を切断します。インテグレーションの実行環境がそのルート証明書を信頼していない場合は、TLSインスペクションプロキシを参照してください。

インバウンドアクセス

RealityConnect APIを利用するためにインバウンドで開放する必要があるものは何もありません。インテグレーションは常にPrevu3Dへアウトバウンドで接続を開始します。Prevu3Dがお客様のネットワークへ接続を開始することはありません。登録すべきWebhook、コールバックURL、リスナーは存在せず、作成すべきインバウンドのファイアウォールルールもありません。

アウトバウンドアクセス

インテグレーションは、アウトバウンドHTTPSで3種類のホストに到達できる必要があります。

OAuthおよびAPIディスカバリー: https://cloud-api.prevu3d.com
リージョンごとのRealityConnect APIホスト(次のうちいずれか1つ):
- https://api-ue1.prevu3d.com
- https://api-ec1.prevu3d.com
- https://api-an1.prevu3d.com
- https://api-cc1.prevu3d.com
ファイル転送: https://cdn.prevu3d.com (ダウンロード)、Amazon S3, *.amazonaws.com (署名付きアップロードURL)

自分のリージョンはどれか

組織はちょうど1つのリージョンにプロビジョニングされているため、4つすべてのホスト名を許可する必要はありません。推測したりサポートに問い合わせたりする代わりに、トークンを取得した後にインテグレーションからディスカバリーエンドポイント(GET /oauth/api-info、各OAuthフローガイドで説明)を呼び出してください。レスポンスのapiUrlフィールドが、組織が実際に使用しているリージョンのホストを示します。そのホスト名だけを許可すれば、残り3つは無視できます。

フォワードプロキシ

RealityConnect APIは標準的なHTTPS/JSON APIです。ネットワーク経路に特別な要件はなく、証明書ピニングのような、標準的な企業のフォワードプロキシ経由での動作を妨げる仕組みも一切採用していません。

インテグレーションが実際にプロキシを使用するかどうかは、RealityConnect APIではなく、インテグレーションが使用しているHTTPクライアントライブラリによって決まります。

ほとんどのHTTPクライアント(curl、Pythonのrequests、Nodeのundici/fetch、.NETのHttpClientなど)は、標準のHTTPS_PROXY/HTTP_PROXY環境変数、またはクライアント設定内の同等のプロキシ設定を尊重します。これを確認するには、お使いのクライアントライブラリのドキュメントを参照してください。
認証が必要なプロキシ(ユーザー名とパスワードを要求するもの)についても、HTTPクライアント層で処理されます。他のあらゆるHTTPS宛先に対してクライアントがすでにサポートしているのと同じプロキシ認証情報の仕組みが使われます。RealityConnect API側に特別な要件はありません。お使いのクライアントが認証付きプロキシ経由ですでに他のHTTPSサービスに到達できているなら、同じ方法でRealityConnect APIにも到達できます。

TLSインスペクションプロキシ

一部の企業ネットワークではTLSインスペクション(SSL復号)プロキシが稼働しています。これは接続の中間に位置し、Prevu3Dの証明書の代わりに独自の証明書をインテグレーションに提示し、実際の宛先へのトラフィックを再暗号化します。これはAPIインテグレーション全般でよく知られた接続障害の原因であり、RealityConnect APIも例外ではありません。

どのように現れるか: 正常なレスポンスの代わりに、インテグレーションのHTTPS呼び出しはTLSハンドシェイク中に証明書検証エラーで失敗します。正確な文言はHTTPクライアントとOSによって異なりますが、「unable to verify the first certificate」「certificate verify failed」「unknown certificate authority」といったメッセージや、HTTPステータスコードすら伴わない単純な接続リセット(リクエストがレスポンスを受け取れるところまで到達しなかったため)としてよく現れます。

これが意味すること: インテグレーションの実行環境が、インスペクションプロキシによって提示された証明書を認識できていません。これは、そのプロキシがトラフィックを再署名する際に使用する内部の認証局(CA)を、実行環境が信頼していないためです。

必要な対処(いずれか一方):

インテグレーションが実際に使用するトラストストアに、企業のルートCAを追加します。 これが最も一般的な対処法であり、最も見落とされがちな手順でもあります。多くの実行環境(Java、Node、Python)はOSのものではなく独自のCAバンドルを同梱・読み込みしているため、Windowsの証明書ストアに企業のルートCAをインストールしても、それらの環境は自動的にはカバーされません。お使いの言語/実行環境に固有の設定が必要かどうかを確認してください(たとえば環境変数NODE_EXTRA_CA_CERTS、JVMフラグ-Djavax.net.ssl.trustStore、あるいはPythonのrequests/certifiが使用するバンドルへの証明書追加など)。
プロキシが宛先ごとのバイパスルールをサポートしている場合は、RealityConnect APIのホスト名をTLSインスペクションの対象から除外します。 これは、実行環境ごとにトラストストアを個別に修正するより簡単なことが多い方法です。

どちらが適切かは、プロキシのベンダーとインテグレーションの実行環境によって異なります。

診断: ネットワークの問題か認証の問題か

次の4つの確認を順番に行ってください。それぞれ異なるレイヤーを切り分けるため、ネットワークの問題に対して認証コードをデバッグしてしまう(あるいはその逆)のではなく、問題が実際にどこにあるかを特定できます。

1. DNS

まずホスト名が名前解決できるかを確認します。

nslookup api-ue1.prevu3d.com

(必要に応じてcloud-api.prevu3d.comまたは組織のリージョンホストに置き換えてください。)これが失敗またはタイムアウトする場合、問題はDNS解決にあります。先に進む前に、マシンのDNS設定を確認してください。

2. TLSハンドシェイク

Prevu3D固有のリクエストとは無関係に、ホストへの安全な接続を確立できるかを確認します。

curl -v https://cloud-api.prevu3d.com

SSL certificate problem、unable to get local issuer certificate、またはHTTPレスポンスが返る前に接続がリセットされる場合に注目してください。これらはいずれも、インテグレーションのコードではなく、ネットワーク経路上のプロキシまたはファイアウォールの問題を示しています(上記のTLSインスペクションプロキシを参照)。401のようなエラーであってもHTTPステータスコードを伴うレスポンスが返れば、TLSは成功しており、問題はさらに上位のレイヤーにあることになります。

Windowsに付属するcurlはWindows証明書ストアを使用するため、独自のCAバンドルを持つ実行環境(Node、Python、Java)がTLSインスペクションプロキシの背後で失敗していても、このチェックは成功することがあります。チェックは成功するのにインテグレーションで証明書エラーが発生する場合は、TLSインスペクションプロキシを参照してください。

3. トークンリクエスト

OAuthアクセストークンを取得できるかを確認します。これにより、RealityConnect APIの呼び出しとは無関係に、認証情報とOAuthリクエストが正しく構成されているかを確認できます。

curl -v -X POST https://cloud-api.prevu3d.com/oauth/token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"

この段階で403 (シークレットが誤り)や404 (不明なクライアントID)が返る場合は、ネットワークの問題ではなく認証情報の問題です。ここまで到達しているということは、DNSとTLSはすでに成功しています。

4. 最初の認証済み呼び出し

トークンが実際にAPIに対して機能するかを確認します。

curl -H "Authorization: Bearer <access_token>" https://cloud-api.prevu3d.com/oauth/api-info

ここで成功のJSONレスポンスが返れば、DNS、TLS、認証を含む経路全体がエンドツーエンドで機能していることが確認できます。手順3が成功した後にこの段階で401/403が返る場合は、ネットワークや認証情報の問題ではなく、スコープや権限の問題を示しています。(/oauth/api-infoにはread:basicスコープが必要です。)

次のステップ

セットアップ: 前提条件、セキュリティモデル、OAuthフローの選択について。