curl (shell)

Un script de bash que usa la API con curl, y jq para crear y leer el JSON. Enumera las variables etiquetadas de una plantilla, mide el dibujo que genera con los valores dados y lo exporta como PDF.

Descárguelo: 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

Cómo funciona

1. Configuración. La clave se toma de PIQ_API_KEY, la dirección de PIQ_URL (el propio servicio si no está definida) y, opcionalmente, el nombre de un almacenamiento de PIQ_STORAGE. Sin clave, el script se detiene de inmediato. set -euo pipefail lo detiene en el primer comando que falla.
2. La plantilla. jq -n --arg crea el JSON, de modo que las comillas y los saltos de línea de la plantilla se escapan como es debido: el texto de la plantilla como template o, cuando PIQ_STORAGE está definida, dónde está guardada en su almacenamiento como source. request le añade los values. Los archivos de los que el script lee las respuestas se eliminan al terminar (trap … EXIT).
3. post envía un cuerpo a una operación, con la clave en el encabezado X-API-KEY. curl escribe la respuesta en un archivo, sus encabezados en headers.txt, e imprime solo el estado (-w '%{http_code}').
4. Errores. De una respuesta que no es correcta se imprime el estado y después la descripción del problema, extraída con jq: su title, su detail y cada entrada de errors, el campo y qué está mal en él. Un 401 no tiene cuerpo (-s comprueba si el archivo está vacío), así que no hay nada más que imprimir; un cuerpo que no es JSON se imprime tal cual. Se elimina el archivo y el script termina con 1.
5. Inputs. POST /inputs solo necesita la plantilla. Cada uno de sus inputs tiene un name, label, kind y value.
6. Measure. POST /measure con los valores da el width y el height del dibujo, y las longitudes de sus líneas por capa en layers; la longitud de corte es la longitud en la capa Cut.
7. Export. POST /export/pdf responde con el propio PDF, que curl escribe directamente en box.pdf. El encabezado X-PiQ-Warnings, que está en headers.txt, indica cuántas cosas no pudieron exportarse tal cual.
8. Save (opcional). Con un almacenamiento, POST /save/pdf exporta el mismo dibujo y lo guarda en su almacenamiento en destination; overwrite: true reemplaza un archivo que ya exista. Responde con dónde lo ha guardado y su tamaño.

Una sola solicitud no necesita script. Esto exporta el dibujo como 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

Cómo ejecutarlo

Guarde el script como box.sh. Necesita bash, curl y jq (en Debian y Ubuntu, apt install jq; en macOS, brew install jq). Después:

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

Imprime las variables etiquetadas de la plantilla, el tamaño del dibujo y su longitud de corte, y guarda 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)

Con un valor que la plantilla no puede usar (por ejemplo, "L": "long"), imprime el problema y se detiene:

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

Con una clave incorrecta, solo imprime Error 401: un 401 no tiene descripción del problema.

Para probar la parte del almacenamiento, registre un almacenamiento (consulte Registrar un almacenamiento), coloque en él una plantilla como templates/box.piq y establezca PIQ_STORAGE con el nombre del almacenamiento. La plantilla se lee entonces desde su almacenamiento, y el PDF también se guarda en él como drawings/box.pdf, reemplazando cualquier archivo que ya exista.

Consulte también: API, Inputs, Measure, Exportar un dibujo, Guardar en su almacenamiento, Registrar un almacenamiento, Clientes.