はじめに

RealityConnect APIは、外部システムがPrevu3Dエコシステムと連携するための唯一の公開インターフェースです。RealityPlatformのコンテンツの読み書き、RealityTwinワークスペースの操作、組織の管理、ファイルやデータセットのアップロードなど、さまざまな用途に利用できます。

---

APIの構成

開発を始める前に知っておくべき設計上の選択がいくつかあります。

• リージョナルベースURL。 APIは複数のリージョン（US East、EU Central、Asia North、Canada Central）で稼働しています。組織はいずれか1つのリージョンにプロビジョニングされます。ベースURLはハードコーディングせず、必ずディスカバリーエンドポイントから取得してください。手順はセットアップガイドで説明しています。
• すべては組織のスコープに限定されます。 トークンは、サービスユーザーにアクセス権が付与されたノードのみを参照できます。組織間の呼び出しはできません。
• リソースはコンテンツ階層内に存在します。 ほとんどの操作はUUIDで識別されるノードを対象とします。ノードはツリー構造（組織 → ディビジョン → サイト → フォルダ → アセット）を形成し、/nodes/{id}/browseエンドポイントで参照できます。
• 3層のアクセス制御。 OAuthスコープ、コンテンツアクセス、ノードごとのロールのすべてを通過しないとリクエストは成功しません。各層の設定方法についてはセキュリティモデルを参照してください。
• HTTPS上のJSON。 すべてのエンドポイントはJSONを受け取って返し、Bearerトークン認証を使用し、標準的なHTTPステータスコードに従います。

OAuth認証

API認証は**OAuth2プロトコル**に基づいています。サポートされているフロー：

OAuthフロー	説明	ユースケースの例
Client Credentials	サインインユーザーなしのサーバー間アクセス。組織内にサービスユーザーが作成され、権限は別途設定します。	スクリプト、自動化、バックエンド統合、APIテスト
Native app	ユーザーがブラウザでサインインし、スコープを承認します。Authorization Code + Native Application、PKCE、http://localhostリダイレクト。クライアントシークレットなし。	デスクトップアプリ、CLIツール、CADプラグイン
Authorization Code + カスタムHTTPSリダイレクト	独自ドメインのコールバックURLを持つWebアプリケーション。PKCE付きAuthorization Codeと完全一致のHTTPSリダイレクトURI。	Webアプリ、SaaS連携

次のステップ

• セットアップ: 前提条件、ネットワークアクセス、セキュリティモデル、OAuthフローの選択。
• Client Credentialsフロー: OAuthアプリの作成から最初のAPI呼び出しまでのサーバー間セットアップ。
• ネイティブアプリケーションフロー: PKCEとlocalhostリダイレクトによるユーザーサインイン。
• Authorization Code + カスタムHTTPSリダイレクトフロー: PKCEと独自ドメインのHTTPSコールバックによるWebアプリのユーザーサインイン。
• インタラクティブAPIリファレンス: リクエスト／レスポンススキーマと組み込みのリクエストビルダーを備えた、エンドポイントの完全なカタログ。
• Data Bundle ワークフロー: Data Bundleの作成、データのアップロード、処理の開始、進捗のモニタリング、入力ファイルのダウンロード。