curl（shell）

一个 bash 脚本，使用 curl 调用 API，并使用 jq 生成和读取 JSON。它列出模板中带标签的变量，用给定的值测量所生成的图纸，并将其导出为 PDF。

下载：box.sh。

#!/usr/bin/env bash
# box.sh: list a template's inputs, measure it and export it as a PDF with the PiQ SaaS API.
# bash, curl and jq.
set -euo pipefail

: "${PIQ_API_KEY:?Set PIQ_API_KEY to your API key.}"
base="${PIQ_URL:-https://saas.parametriq.co.uk}"
base="${base%/}"
storage="${PIQ_STORAGE:-}" # optional: a registered storage's name

TEMPLATE='L=400,"Length"
W=300,"Width"
P1=[L,0]
P2=[L,W]
P3=[0,W]
POLYLINE @1,[P0,P1,P2,P3],TRUE,0'
# the template itself, or (optional) where it is kept in your storage
if [ -n "$storage" ]; then
  template=$(jq -n --arg s "$storage" '{source: {storage: $s, key: "templates/box.piq"}}')
else
  template=$(jq -n --arg t "$TEMPLATE" '{template: $t}')
fi
request=$(jq '. + {values: {L: 500, W: 250}}' <<<"$template")
trap 'rm -f inputs.json measure.json saved.json headers.txt' EXIT

# post PATH BODY OUTPUT: posts the JSON body, the response to the file OUTPUT, its headers to headers.txt
post() {
  local status
  status=$(curl -sS -o "$3" -D headers.txt -w '%{http_code}' -X POST "$base$1" \
    -H "X-API-KEY: $PIQ_API_KEY" -H 'Content-Type: application/json' --data-binary "$2")
  if [ "$status" -ge 300 ]; then
    echo "Error $status" >&2
    if [ -s "$3" ]; then # a 401 has no body
      jq -r '.title // empty, .detail // empty,
        (.errors // {} | to_entries[] | "  \(.key): \(.value | join(" "))")' "$3" >&2 || cat "$3" >&2
    fi
    rm -f "$3"
    exit 1
  fi
}

# 1. The template's labelled variables
post /inputs "$template" inputs.json
jq -r '.inputs[] | "\(.name): \(.label) (\(.kind), \(.value))"' inputs.json

# 2. The drawing measured, with the values given
post /measure "$request" measure.json
jq -r '"Size: \(.width) x \(.height), cut length: \(.layers | map(select(.layer == "Cut").length) | add // 0)"' measure.json

# 3. The drawing as a PDF
post /export/pdf "$request" box.pdf
warnings=$(grep -i '^x-piq-warnings:' headers.txt | cut -d' ' -f2 | tr -d '\r')
echo "Saved box.pdf ($warnings warnings)"

# 4. Optional: the PDF saved to your storage instead of downloaded
if [ -n "$storage" ]; then
  body=$(jq --arg s "$storage" '. + {destination: {storage: $s, key: "drawings/box.pdf"}, overwrite: true}' <<<"$request")
  post /save/pdf "$body" saved.json
  jq -r '"Saved \(.key) to \(.storage) (\(.size) bytes)"' saved.json
fi

工作原理

设置。 密钥来自 PIQ_API_KEY，地址来自 PIQ_URL（未设置时为服务本身的地址），还可以选择从 PIQ_STORAGE 读取存储名称。没有密钥时，脚本会立即停止。set -euo pipefail 使脚本在第一个失败的命令处停止。
模板。 由 jq -n --arg 生成 JSON，因此模板中的引号和换行符都会被正确转义：模板的文本作为 template，或者在设置了 PIQ_STORAGE 时，以 source 给出模板在您存储中的保存位置。request 向其中添加 values。脚本结束时会删除它用来读取响应的文件（trap … EXIT）。
post 将正文发送到某个操作，并在 X-API-KEY 标头中携带密钥。curl 将响应写入文件，将其标头写入 headers.txt，并只打印状态（-w '%{http_code}'）。
错误。 不成功的响应会先打印其状态，然后打印由 jq 提取的问题描述：其 title、detail，以及 errors 中的每一项，即字段及其问题。401 没有正文（-s 用于检测空文件），因此没有更多内容可打印；不是 JSON 的正文按原样打印。随后删除该文件，脚本以 1 退出。
Inputs。 POST /inputs 只需要模板。其每个 inputs 都有 name、label、kind 和 value。
Measure。 使用这些值调用 POST /measure，可得到图纸的 width 和 height，以及在 layers 中按图层统计的线长；切割长度即 Cut 图层上的长度。
Export。 POST /export/pdf 返回 PDF 本身，curl 将其直接写入 box.pdf。在 headers.txt 中找到的 X-PiQ-Warnings 标头表示有多少内容无法按原样导出。
Save（可选）。 指定了存储时，POST /save/pdf 会导出同一图纸，并将其保存到您存储中的 destination，overwrite: true 表示替换已存在的文件。响应会说明保存位置及文件大小。

单个请求无需脚本。以下命令将图纸导出为 PDF：

curl -sS -X POST https://saas.parametriq.co.uk/export/pdf \
  -H "X-API-KEY: $PIQ_API_KEY" -H 'Content-Type: application/json' \
  -d '{"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}}' \
  -o box.pdf

运行

将脚本保存为 box.sh。它需要 bash、curl 和 jq（在 Debian 和 Ubuntu 上使用 apt install jq；在 macOS 上使用 brew install jq）。然后：

chmod +x box.sh
export PIQ_API_KEY=XXXX-XXXX-XXXX-XXXXX
./box.sh

它会打印模板中带标签的变量、图纸的尺寸和切割长度，并保存 box.pdf：

L: Length (Number, 400)
W: Width (Number, 300)
D: Depth (Number, 300)
Size: 500 x 250, cut length: 1500
Saved box.pdf (0 warnings)

如果给出模板无法使用的值（例如 "L": "long"），它会打印问题并停止：

Error 400
One or more validation errors occurred.
Some of the values given can't be used.
  L: L is a number.

如果密钥不正确，它只会打印 Error 401：401 没有问题描述。

要试用存储部分，请注册一个存储（请参阅注册存储），将模板以 templates/box.piq 放入其中，并将 PIQ_STORAGE 设置为该存储的名称。这样，模板将从您的存储中读取， PDF 也会以 drawings/box.pdf 保存到其中，替换已存在的任何文件。

另请参阅：API、Inputs、Measure、导出图纸、保存到您的存储、注册存储、客户端。