如何使用 Matterport API

我们的开发人员社区集合了一群希望将 Matterport 集成到日常工作流程中的行业专业人士 — 为应对这一挑战,我们首先向建筑师、工程师和任何其他想要深入了解我们平台的专业人士开放我们的 API

目前我们可提供开发工具集,允许开发人员直接连接到 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 端点。 请记住,您最多可以生成五个密钥,供您在希望构建的不同应用程序中使用。 创建新密钥时,会显示以下信息: 

  1. 令牌密钥
    • 仅显示一次 — 请确保安全地复制和保存。
  2. 令牌 ID
    • 会显示在设置页面上

API 密钥是“管理员”或“完全访问”密钥。 用于向客户账户授予用户管理凭据。 如使用已生成 API 密钥的 API,则开发人员可以使用 API 执行所有管理功能,包括模型存档以及购买楼层平面图和 MatterPaks。 在共享 API 密钥时请务必记住这一点 — 我们强烈建议您不要与第三方公司或开发人员共享 API 密钥。

请注意,账户在默认情况下仅启用 Sandbox 模式。 有关 Sandbox 模式的更多信息,请参阅开发人员工具的可用性和定价

连接端点

  1. 访问 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”— 两者有何区别?

在 Matterport API 测试版之前,Matterport 开发人员主要使用 Showcase SDK(软件开发工具包)。 API 测试版是一个补充功能 — 我们一起来看看两者的差异。

Showcase SDK

“Showcase SDK”是一组编程命令,开发人员可用其来扩展 Showcase 的功能,即使 Showcase 直接嵌入到其他网站或平台上也可以。 您可以将其想象成一个看不见的薄层,位于 Showcase iFrame 的顶部, 仅存在于开发人员页面上。 因此,SDK 仅影响到一位开发人员每次使用时的页面体验感。 同样,只有在应用了 SDK 的开发人员页面上,在多个网站上共享的模型才会受到影响。

API

不同于 SDK,API  直接 与 Matterport 的后端连接。 这可让开发人员执行各种命令,如搜索、读取数据、更改数据和下订单。 Matterport API 可让开发人员以编程方式执行客户在我们网站上采取的行动。 

3. 模型 API 是什么?我们正在考虑的其他 API 有哪些?

API 的世界庞大无比 — 目前,Matterport 正致力于将提供给开发人员的不同命令进行分类: 

模型 API 命令

这些命令用于搜索、读取和/或更改模型数据。 模型数据由什么组成? 模型的详细信息(如空间的名称和地址)、共享 URL、图像、视频、位置数据、OBJ 网格文件、点云文件、全景图像、位置点和 Mattertags。 

插入 API 命令

这些命令将一组全景图像直接发送到 Matterport 视觉管道中 — 所有命令都是为了尝试进行 3D 重建。 除了全景图像,开发人员还可以发送其他元数据,如全景序列、楼层全景和其他位置数据。 从本质上讲,提供的元数据越多,成功进行 3D 重建的机会就越高。 

对于使用之前与我们的平台不兼容的不同 360° 摄像机采集全景图像的客户,随着此解决方案的成熟,我们希望能为他们提供支持。 

帐户 API 命令

这些命令用于管理用户和文件夹,包括预配和设置权限。 

服务 API 命令

这些命令可让开发人员以编程方式发现订单、下订单以及访问我们提供的增值服务和 Matterport 模型(如 MatterPaks 和平面图)。

发布 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 常见问题。 

还有其它问题?提交请求