Matterport API の使用方法

Matterport の開発者コミュニティには、Matterport を毎日のワークフローに統合したいという業界の専門家がたくさんいらっしゃいます。当社はこの課題に正面から取り組んでいます。手始めとして、建築家、エンジニア、その他当社のプラットフォームのさらなる活用を希望されている専門家の方々に、当社の API を開放します。

Matterport では、開発者が Matterport のバックエンドデータストアに直接接続できるようにする開発者ツールセットを提供するとともに、お客様にはモデルをプログラム的に処理するための方法を提供しています。 データへの直接的なアクセスから、コンテンツの変更、モデルのステータスの管理、付加価値サービスの購入まで、開発者の皆様にすべてコントロールしていただきたいと考えています。

ドキュメント

リファレンスガイドで最新の GraphQL API 機能について詳しく知ることができます。また、インタラクティブコンソールにアクセスし、GraphQL API の一部を体験できます。

インタラクティブコンソールにアクセスするには、管理者の資格情報を使用して Matterport Cloud (my.matterport.com) にログインする必要があります。

手順

API キーの生成

  1. Matterport Cloud (my.matterport.com) に移動します。
  2. 右側の [アカウント (Account)] ドロップダウンをクリックします。
  3. [開発者ツール (Developer Tools)] を選択します。 
  4. [API トークン管理 (API Token Management)] というセクションまでスクロールします。
    • ここで API キーをリクエストし、取り消すことができます。

API エンドポイントに接続できる API キーを生成する必要があります。 構築するさまざまなアプリケーションで使用するために、最大 5 つのキーを生成できます。 新しいキーを作成すると、次の情報が表示されます。

  1. トークンシークレット
    • これが表示されるのは一度だけです。必ずコピーして安全に保存してください。
  2. トークン ID
    • これは設定ページに表示されます。 

API キーは「管理者」または「オールアクセス」キーです。 つまり、API キーはユーザーに顧客アカウントに対する管理者資格情報を付与します。 生成された API キーで API を使用すると、開発者は、モデルのアーカイブ、フロアプランや MatterPak の購入など、API を使用してすべての管理機能を実行できます。 API キーを共有する場合は、API キーをサードパーティの企業や開発者に共有しないことを強く勧めます。

デフォルトでアカウントはサンドボックスモードのみが有効になっています。 サンドボックスモードの詳細については、開発者ツールの価格とご利用についてをご覧ください。

エンドポイントへの接続

  1. 次の URL で API エンドポイントにアクセスします。 https://api.matterport.com/api/models/graph 
  2. ユーザー名としてトークン ID を使用します。
  3. パスワードとしてトークンシークレットを使用します。
    • 例: Authorization: Basic <base64_encode(<Token ID>:<Token Secret) 

標準の http ライブラリはすべてこのプロセスをサポートしているはずですが、プリエンプティブ認証が「true」に設定されていることを確認してください。   

エラーコード

アプリケーションレベルのエラーはすべて、エラー拡張子に「コード」が付きます。以下のガイドを使用して、一般的なエラーコードを認識してトラブルシューティングを行ってください。

   1. request.unauthenticated 

認証トークンがないか、認証トークンの期限が切れています。

   2. request.unauthorized 

ユーザーが許可されていない操作またはフィールドにアクセスを試みました。

   3. request.invalid 

グラフクエリ―を処理できませんでした。

   4. error.internal 

サーバーがリクエストを処理できませんでした。

   5. not.found 

リクエストされたオブジェクトが存在しません。関連する操作で特定の ID フィールドを使用すると、このエラーが表示されます。

   6. not.unique 

セカンダリーインデックスから単一のレコードを取得しようとしましたが、送信されたクエリ―に複数のレコードが一致しました。 これは、複数のモデルが同じ内部 ID を持つ場合に頻繁に発生します。

   7. quota.exceeded 

リソース制限があるものの変更。たとえば、サブスクリプションの制限により、許可されたものより多くのモデルをアクティブ化しようとしています。

コードスニペットの例

始めるには、これらのコードスニペットの例を参照してください。

よくある質問

1. API とは何ですか?

API は「アプリケーションプログラミングインターフェイス」の略です。これは、コンピュータプログラムのさまざまなパーツ間の通信プロトコルです。 API の主な目的は、ソフトウェアの実装と保守を簡単にすることです。

Matterport API を使用すると、開発者 (またはお客様) は、プログラムによってシステムまたはアプリケーションを Matterport システムに直接接続して、データにアクセスし変更することができます。

2. Matterport は「SDK」も提供しています。API との違いは何ですか?

Matterport API ベータ版より前、Matterport の開発者は主に Showcase SDK (ソフトウェア開発キット) を利用していました。 API ベータ版は補足的な機能です。以下でその違いを見ていきましょう。

Showcase SDK 

Showcase SDK は、Showcase が他のサイトやプラットフォームに直接組み込まれている場合でも、Showcase 機能を拡張するために開発者が使用できるプログラミングコマンドのセットです。 これは、開発者ページの Showcase iFrame 上のみに位置する薄くて目に見えないレイヤーと考えてください。 このことを考慮すると、SDK は 1 回の使用につき 1 つの開発者ページの体験にのみ影響します。 そのため、複数のサイトで共有されているモデルは、SDK が適用された開発者ページでのみ影響を受けます。

API

SDK とは対照的に、API は Matterport バックエンドに直接接続します。 これにより、開発者は、検索、データの読み取り、データの変更、注文など、さまざまなコマンドを実行できます。 Matterport API を使用すると、開発者は、ユーザーが当社のサイトで実行するアクションをプログラムで実行できます。

3. モデル API とは何ですか? その他の API と見なされるものは?

API の世界は非常に広く、Matterport は開発者が利用できるさまざまなコマンドをサブカテゴリにグループ化しています。

モデル API コマンド

これらのコマンドは、モデルデータの検索、読み取り、変更を行います。 モデルデータを構成するものは何ですか? モデルの詳細 (空間の名前とアドレスなど)、共有 URL、画像、ビデオ、位置データ、OBJ メッシュファイル、点群ファイル、パノラマ画像、位置点と Mattertag で構成されています。

Ingest API コマンド

これらのコマンドは、3D の再構築を試みるために、パノラマ画像のコレクションを Matterport ビジョンパイプラインに直接送信します。 パノラマ画像とともに、開発者はパノラマシーケンス、フロアのパノラマ、他の位置データなど、追加のメタデータを送信できます。 基本的に、メタデータが多いほど、3D の再構成が成功する可能性は高くなります。

このソリューションの成熟とともに、これまではプラットフォームと互換性のなかった、さまざまな 360° カメラを使用してパノラマ画像を撮影していたお客様をサポートしたいと考えています。

アカウント API コマンド

これらのコマンドは、プロビジョニングやパーミッションの設定など、ユーザーとフォルダを管理します。

サービス API コマンド

これらのコマンドを使用すると、開発者は Matterport モデル (MatterPak やフロアプランなど) に加えて、付加価値サービスをプログラムで見つけ、注文し、アクセスできます。

パブリッシュ API コマンド

これらのコマンドを使用すると、開発者は、Matterport が現在サポートしているすべての公開プラットフォームをプログラムで検出して使用できます。 これには、Google ストリートビュー、Vrbo、realtor.com、および homes.com が含まれます。

4. API を使用してアクセスできるアカウントはどれですか?

API を使用して顧客のアカウントとモデルにアクセスすることをお勧めします。 API トークンは基本的に管理者の資格情報のセットであり、そのアカウントへのフルアクセス権を提供します (API を使用して購入も可能)。 

5. 始めるにはどうすればよいですか?

API トークンをリクエストする必要があります。下記の簡潔な手順に従ってください。

  1. Matterport Cloud (my.matterport.com) に移動します。
  2. 右側の [アカウント (Account)] ドロップダウンをクリックします。
  3. [開発者ツール (Developer Tools)] を選択します。 
  4. [API トークン管理 (API Token Management)] というセクションまでスクロールします。
    • ここで API キーをリクエストし、取り消すことができます。

6. 他にも質問はございますか?

より詳細なモデル API のよくある質問をご覧ください。 

他にご質問がございましたら、リクエストを送信してください