Onshape REST API简介

本页面解释了如何使用 Onshape REST API 的基础知识。如果您是第一次使用 API，我们建议您花一些时间从这些免费资源中学习基础知识：

Onshape使用REST API与客户和第三方系统进行通信。Onshape存在于您的浏览器中，这意味着您可以像调用任何其他网页一样调用REST API。API调用返回信息而不是网页，并且响应以JSON（JavaScript对象表示）格式进行格式化。

您可以使用我们的REST API实时访问Onshape引擎和数据。我们目前支持三种REST API请求（遵循HTTP标准）：

GET: 从服务器检索（读取）信息（即您的 Onshape 文档）。URL 中包含的任何参数都会发送到服务器。
POST: 使用新信息更新（写入）服务器。必需数据包含在请求正文中。
DELETE: 从服务器删除信息。

在Onshape中，典型的REST API调用包括五个主要组件：

方法:
- GET、POST或DELETE
- 每个 Onshape API 端点都标有其方法类型。
URL:
- 指定 API 端点和 API 调用的文档部分
- 使用以下格式: {base_url}/{fixed_url}。
  - {base_url}: Onshape URL（例如，https://cad.onshape.com/api或企业账户的 https://companyName.onshape.com/api）。
  - {fixed_url}: API 端点的 URL（稍后会详细介绍）
查询参数:
- API 调用的可选参数
- 在 API Explorer 中每个端点的下拉内容中描述（您将在后面的部分了解如何使用我们的 API Explorer）
标头:
- 定义与元数据相关联，服务器用于处理请求
- 通常包含 Content-Type 和 Accept
  - Content-Type:
    - 通常为 application/json
    - 如果应用程序下载文件，则 Content-Type 将是 application/octet-stream
  - Accept: 在 API Explorer 中 API 响应部分的 Media type 下找到
负载主体:
- 仅适用于 POST 请求
- 对于某些 POST 请求是必需的；对于其他请求是可选的
- 负载模板在 API Explorer 中的 API 下拉菜单中可用
- 通常从相关 GET 请求的响应中获取并修改（而不是手动操作）

Onshape API 请求

由于Onshape是基于Web的解决方案，它使用URL来定义在浏览器中加载的内容。

Onshape网址示例：https://cad.onshape.com/api/``documents/e60c4803eaf2ac8be492c18e/``w/d2558da712764516cc9fec62/``e/6bed6b43463f6a46a37b4a22

https://cad.onshape.com/api 是文档的基本 URL。
- 每个企业账户都有自定义的基本 URL：https://companyName.onshape.com/api
documents/ 或 d/ 后面跟着一个 24 位字符的文档 ID。文档 ID 唯一标识 Onshape 文档。
接下来，w/ 后面跟着一个 24 位字符的工作区 ID。工作区 ID 唯一标识文档内的工作区。默认情况下，文档从主工作区开始。
- 要引用特定文档版本，请用 v/ 替换 w/，后跟 24 位字符的版本 ID。
- 每次在文档中进行编辑时，都会自动创建每个文档的微版本。要引用特定微版本，请用 m/ 替换 w/，后跟 24 位字符的微版本 ID。
- 注意：POST 请求始终发送到工作区，因为版本和微版本是不可变的。
e/ 后面跟着一个 24 位字符的元素 ID。元素 ID 唯一标识一个元素（例如，我们通过用户界面看到和访问的选项卡）。

在本文档中，我们经常将URL模板称为：{base_URL}/{endpoint}/d/{did}/{wvm}/{wvmid}/e/{eid}，有时简称为/{endpoint}/DWVME/。

当你的应用程序在文档中实例化时，会使用类似这样的 URL 进行调用：

https://your-server.your-domain.com?documentId=e60c4803eaf2ac8be492c18e&workspaceId=d2558da712764516cc9fec62&elementId=6bed6b43463f6a46a37b4a22&server=https%3A%2F%2Fcad.onshape.com&userId=53da35fbe4b0412c60b5e3b7&access=edit&debug=true

从Onshape传递到您的应用程序的查询参数为：

参数

描述

文档编号

当前文档 ID

workspaceId、versionId、microversionId

当前工作区ID或版本ID或微版本ID

elementId

当前（应用程序）元素ID

服务器

当前 Onshape 服务器的地址。服务器参数是信息性的；REST 请求应始终发送到 cad.onshape.com。企业账户应发送到 companyName.onshape.com。

用户ID

当前用户ID，可以通过调用/api/users/current并从id字段获取用户ID找到。

访问

如果文档应该具有编辑功能，则设置为edit。

Onshape API 响应

Onshape中的REST API以JSON格式通信数据。如果您对使用JSON不熟悉，我们建议参考以下资源：

下面的示例是调用getDocument API获取此公共文档的响应。返回了大量信息，因此我们在下面截断了响应的中间部分，但是如果我们查看JSON的最后部分，我们可以看到响应已正确返回Onshape API Guide作为文档的name。

 {
 "jsonType": "document",
 "documentThumbnailElementId": "",
 "isUpgradedToLatestVersion": true,
 "public": false,
 "permission": "FULL",
 "isOrphaned": false,
 "recentVersion": null,
 ...
 "isEnterpriseOwned": false,
 "resourceType": "document",
 "name": "Onshape API Guide",
 "id": "e60c4803eaf2ac8be492c18e",
 "href": "https://cad.onshape.com/api/v6/documents/e60c4803eaf2ac8be492c18e"
}

版本控制

所有端点调用都有版本。版本字符串直接插入在 /api/ 路径组件之后。例如，https://cad.onshape.com/api/v6/documents/e60c4803eaf2ac8be492c18e 表示对 Onshape getDocument 端点的 版本 6 请求。

版本内的调用彼此兼容；通常这意味着一个 GET 请求可以在同一版本中作为 POST 请求返回。每当 Onshape 引入一个不向后兼容的更改时，版本号会递增。Onshape 用户应始终在调用中引用最新版本。如果未指定版本，则将使用最旧版本（v0）。

API 约定

Onshape API通常使用以下约定：

Onshape通常仅支持3种方法：GET用于只读操作，POST用于写操作，DELETE用于删除。Onshape目前不支持其他方法，如PUT。
字符串应该采用UTF-8编码。
查询参数用于可选参数。所有必需参数都包含在路径中。为简洁起见，在本文档中的路径定义中使用以下大写字母：
- D 文档ID（24个字符）
- W 工作区ID（24个字符）
- V 版本ID（24个字符）
- M 微版本ID（24个字符）
- E 元素ID（24个字符）
路径的一般形式是/resource/context/subresource。当存在时，上下文标识文档（D）、工作区、版本或微版本（WVM）以及元素（E）。有关Onshape基本API结构的更多信息，请参阅Onshape架构页面。
我们的意图是为所有适当的GET操作提供Workspace、Version和Microversion形式。POST将始终针对Workspace，因为Versions和Microversions是不可变的。目前并非所有接口的所有形式都已实现。
截至目前，一些API调用返回的信息仅适用于Onshape客户端。您通常只应使用为外部使用而记录的字段。内部数据可能会在不通知的情况下更改或删除。

单位标识符

以下是有效的单位标识符:

长度测量：

米, 米, m
毫米, 毫米, mm
厘米, 厘米, cm
英寸, 英寸, in
英尺, 英尺, ft
码, 码, yd

对于角度测量：

度, 度, 度
弧度, 弧度, 弧度

现在怎么办？

继续前往我们的API Explorer页面，了解如何在我们的Glassworks API Explorer中浏览Onshape API。