PiQ SaaS API

PiQ SaaS 是位于 https://saas.parametriq.co.uk 的 Web API：通过 HTTPS 发送请求，以 JSON（或所请求的文件）作为响应。它由一份 OpenAPI 文档 PiQ SaaS API（版本 1）描述，地址为 https://saas.parametriq.co.uk/openapi.json，可据此为大多数语言生成客户端：请参阅 OpenAPI。

每个请求都必须在 X-API-KEY 标头中携带您的 API 密钥：请参阅使用 API 密钥。

模板和值

每个操作都基于一个模板：即 ParametrIQ 图纸的文本（一个 .piq 文件），作为 template 发送。它生成的图纸取决于其带标签的变量，即定义时带有标签的变量：

L=400,"Length (inside)"
W=300,"Width (inside)"
T={"E flute":1.5,"B flute":3}["B flute"],"Material"
HANDHOLES=FALSE,"Hand holes"

按名称（不区分大小写）为它们发送 values：可以是数字、文本，或 true、false；对于选项，可以是其名称（"E flute"）或其在列表中的位置（0）。未给出的变量保留模板中的值。只有带标签的变量才能被赋值：为任何其他变量提供的值都会被拒绝，类型错误的值也会被拒绝。使用 units 选择单位： Millimeters（默认）或 Inches。

{
  "template": "L=400,\"Length\"\nW=300,\"Width\"\nP1=[L,0]\nP2=[L,W]\nP3=[0,W]\nPOLYLINE @1,[P0,P1,P2,P3],TRUE,0",
  "values": { "L": 500, "W": 250 }
}

除了发送模板本身，您还可以把模板保存在您自己的 S3 兼容存储中，并通过 source 指定其中一个："source": { "storage": "main", "key": "templates/box.piq" }（请参阅下文的您的存储）。

每个请求都会重新运行模板：请求之间不保留任何内容。

操作

每个操作都有自己的页面，并附有示例。除另有说明的方法外，所有操作均为 POST，并使用上述 JSON 正文。

图纸

操作	返回
`POST /inputs`	模板中带标签的变量：可以给出哪些值，以及值的类型。
`POST /drawing`	使用给定值生成的完整图纸，格式为 ParametrIQ 图纸文本。
`POST /export/{format}`	以文件形式返回图纸：PDF、SVG、EPS、AI、PNG、JPEG、WebP、G-code、HP-GL、CF2、DDES3、DXF 或 `.piq`，或者某种特定机器或行业的格式（刀模线 PDF、打印切割、GP-GL、LightBurn、激光机和 Cricut 用 SVG、DSTV NC、AAMA/ASTM DXF、分块打印、投影仪 PDF、卡纸切割机）。
`POST /save/{format}`	同一文件，保存到您的存储中而不是直接返回。
`POST /preview`	图纸的 PNG 图片，便于快速查看。
`GET /formats`	导出格式及其媒体类型和扩展名。

计算

操作	返回
`POST /variables`	图纸的变量及其值，包括给定的值和计算得出的值。
`POST /evaluate`	在图纸中计算的表达式（`L*2`、`AREAOF(@1)` …）。
`POST /points`	图纸的点：每个点的位置及其定义方式。
`POST /measure`	图纸的范围、按图层统计的线长，以及展开料的面积和周长。
`POST /die`	所需的刀模及其成本估算。
`POST /fold`	3D 折叠后的图纸：可绘制的网格，涵盖从平展到折叠完成的各个步骤。
`GET /appearances`	`/fold` 可赋予图纸的外观：金属、纸板、织物、塑料、木材 …
`POST /pack-first`	为产品规划包装：产品在箱内的各种排列，每种配上库中的内衬和外箱，计算成本并适配托盘；并可返回其中一种的图纸。

存储

操作	作用
`GET /storages`	列出您的存储。
`GET /storages/{name}`	获取其中一个存储。
`PUT /storages/{name}`	注册一个存储，或替换它。
`DELETE /storages/{name}`	移除一个存储。
`POST /storages/{name}/test`	使用为其保存的密钥测试一个存储。
`GET /storages/{name}/objects`	列出一个存储中的内容。

您的存储

模板可以保存在您自己的 S3 兼容存储（AWS S3、Cloudflare R2、Backblaze B2、Wasabi、MinIO、 DigitalOcean Spaces …）中，导出的文件也可以保存到其中。只需用您自选的名称注册一次存储，之后即可在请求中指定它。

PUT /storages/main
{
  "serviceUrl": "https://ACCOUNT.r2.cloudflarestorage.com",
  "region": "auto",
  "bucket": "my-bucket",
  "prefix": "piq/",
  "accessKeyId": "…",
  "secretAccessKey": "…"
}

注册时会对存储进行测试：如果无法访问、不存在该存储桶或拒绝了密钥，则不会注册，并在响应（502）中说明原因。再次注册同一名称会替换原有存储。
prefix 将存储桶中的一个文件夹作为存储：键都位于其中，且无法访问其上级。
pathStyle（未给出时为 true）以 endpoint/bucket/key 的形式寻址对象，这是 AWS 以外的大多数服务所要求的方式。
端点必须使用 https，且位于公共互联网上。
请提供只能读写该存储桶（或前缀）的密钥。密钥会加密保存，且绝不会返回。
您最多可以拥有 10 个存储。

在任何图纸请求中，给出 source 而不是 template，即可从您的存储中读取模板：

{
  "source": { "storage": "main", "key": "templates/box.piq" },
  "values": { "L": 500 }
}

然后使用 /save/{format} 将导出的文件保存到其中。存储操作已在上文列出。

错误

无法按要求执行的请求会返回 400 Bad Request 以及问题描述：按相关的值说明哪里有问题。

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "Some of the values given can't be used.",
  "errors": {
    "gt": [ "gt isn't one of the template's labelled variables: only those can be given values." ],
    "l": [ "L is a number." ]
  }
}

模板的脚本在运行时出错（例如永不结束的循环）也会返回 400，错误位于 template 下。

不属于您或不存在的存储，或者其中没有任何内容的键，会返回 404。无法使用的键（以 / 开头、含有 . 或 .. 文件夹，或超过 900 字节）会返回 400。文件已经存在时返回 409。存储无法访问、其存储桶已丢失或拒绝其密钥时返回 502，未及时响应则返回 504。

缺少 API 密钥或 API 密钥未知时返回 400 或 401。

模板中的网址

模板就是一张图纸，而图纸可以从外部引入内容：链接到其文件或网址的图片、库零件和 3D 模型，以及引用它们的 IMPORT 和 MERGE 语句。该服务完全不读取文件，默认情况下也不获取网址：链接或导入了网址的模板会被拒绝（400，并说明是哪一个）。发送模板之前，请先嵌入其显示的内容（在 ParametrIQ CAD 中使用编辑 › 链接 › 全部嵌入），这样它就不需要其他任何内容。

自行运行该服务时，可以在其配置中允许来自您信任的主机的网址：

"SaaS": {
  "UrlFetch": {
    "AllowedHosts": [ "cdn.example.com", "*.assets.example.com" ],
    "TimeoutSeconds": 20
  }
}

*.example.com 允许 example.com 下的任何主机。即使来自这些主机，也只获取 http 和 https 地址，并且仅当主机名解析到的每个 IP 地址都是公共地址时才获取：绝不获取私有地址（10.x、172.16–31.x、192.168.x、fc00::/7）、环回地址（127.x、1）、链路本地地址（169.254.x，例如云元数据服务，fe80/10）、共享地址或保留地址。每次重定向（最多跟随五次）都会检查这一点，建立连接时还会再次检查，因此模板无法让服务访问其自身所在的网络。来源必须在 SaaS:UrlFetch:TimeoutSeconds（20）秒内到达，大小不超过 64 MB，并且类型正确（图片必须是图像，绝不能是网页）；无法获取的内容会导致模板被拒绝，并说明原因。获取的内容会缓存（连同服务器的 ETag 和 Last-Modified）在服务的本地应用程序数据中。

限制

时间。 每个请求有 20 秒时间来运行其模板并生成所请求的内容。届时仍在运行的模板会被停止，请求返回 422 Unprocessable Content：相同的模板和相同的值还会花费同样长的时间，因此原样再次发送毫无意义。无论用时多少，脚本在执行一百万条语句后也会被停止。
并发。 同一时间只能处理一定数量的请求；其余请求会排队等候。等候的请求过多时，后续请求会被拒绝，返回 429 Too Many Requests：请稍后再发送。
大小。 请求最大 8 MB，模板最多 200 万个字符（从您的存储中读取的模板最大 8 MB），图片宽度最多 8000 像素。

自行运行该服务时，存储需要 SaaS:Storage:EncryptionKey：32 个随机字节，采用 base64 编码（openssl rand -base64 32）。请将其保密，存放在用户机密或环境变量（SaaS__Storage__EncryptionKey）中，而不是 appsettings.json 中。更改它会使已保存的机密无法读取，因此之后必须重新注册存储。SaaS:Storage:AllowHttp 和 SaaS:Storage:AllowPrivateEndpoints（均为 false）允许存储使用 http 和私有地址，以便针对本地 MinIO 进行测试。SaaS:Storage:MaxPerLicense（10）、 SaaS:Storage:TimeoutSeconds（30）和 SaaS:Storage:MaxReadBytes（8 MB，即从存储读取模板的最大大小）用于设置限制。没有加密密钥时，注册或使用存储会返回 503。

自行运行该服务时，以下各项在其配置中设置：SaaS:TimeLimitSeconds（20）、 SaaS:MaxConcurrent（处理器数量）和 SaaS:QueueLimit（50）。

另请参阅：客户端（JavaScript、Python、C#、Go 等语言的示例）、运行参数化（在 ParametrIQ CAD 中使用相同的模板）。