API de PiQ SaaS

PiQ SaaS es una API web en https://saas.parametriq.co.uk: solicitudes por HTTPS, respondidas con JSON (o con el archivo solicitado). Se describe mediante un documento OpenAPI, PiQ SaaS API, versión 1, en https://saas.parametriq.co.uk/openapi.json, a partir del cual pueden generarse clientes en la mayoría de los lenguajes: consulte OpenAPI.

Toda solicitud debe llevar su clave de API en el encabezado X-API-KEY: consulte Uso de la clave de API.

Plantillas y valores

Toda operación trabaja sobre una plantilla: el texto de un dibujo de ParametrIQ (un archivo .piq), enviado como template. El dibujo que produce depende de sus variables etiquetadas, las definidas con una etiqueta:

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

Envíe values para ellas por nombre (en mayúsculas o minúsculas): un número, un texto, o true o false; para una opción, su nombre ("E flute") o su posición en la lista (0). Las variables omitidas conservan los valores de la plantilla. Solo se pueden dar valores a las variables etiquetadas: un valor para cualquier otra variable se rechaza, al igual que un valor de tipo incorrecto. Elija las unidades con units: Millimeters (el valor predeterminado) o 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 }
}

En lugar de enviar la plantilla, puede guardar las plantillas en su propio almacenamiento compatible con S3 e indicar una como source: "source": { "storage": "main", "key": "templates/box.piq" } (consulte Sus almacenamientos, más abajo).

Cada solicitud ejecuta la plantilla desde cero: no se conserva nada entre solicitudes.

Operaciones

Cada operación tiene su propia página, con un ejemplo. Todas son POST con un cuerpo JSON como el anterior, salvo donde se indica otro método.

Dibujos

Cálculos

Almacenamientos

Sus almacenamientos

Las plantillas pueden guardarse en su propio almacenamiento compatible con S3 (AWS S3, Cloudflare R2, Backblaze B2, Wasabi, MinIO, DigitalOcean Spaces …), y los archivos exportados pueden guardarse en él. Registre un almacenamiento una sola vez, con el nombre que elija, y después indíquelo en las solicitudes.

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

• El almacenamiento se prueba al registrarlo: si no se puede acceder a él, no tiene ese bucket o rechaza las claves, no se registra, y la respuesta (502) indica el motivo. Registrar de nuevo el mismo nombre lo reemplaza.
• prefix convierte una carpeta del bucket en el almacenamiento: las claves están dentro de ella y no pueden llegar por encima.
• pathStyle (true si no se indica) direcciona los objetos como endpoint/bucket/clave, como requieren la mayoría de los servicios distintos de AWS.
• El endpoint debe ser https, en la Internet pública.
• Proporcione claves que solo puedan leer y escribir en ese bucket (o prefijo). El secreto se guarda cifrado y nunca se devuelve.
• Puede tener hasta 10 almacenamientos.

En cualquier solicitud de dibujo, indique source en lugar de template para leer la plantilla desde su almacenamiento:

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

Después, guarde en él los archivos exportados con /save/{format}. Las operaciones de almacenamiento se enumeran más arriba.

Errores

Una solicitud que no puede llevarse a cabo tal como se pide se responde con 400 Bad Request y una descripción del problema: qué está mal, según el valor al que se refiere.

{
  "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." ]
  }
}

Una plantilla cuyo script falla durante la ejecución (por ejemplo, un bucle que nunca termina) también se responde con 400, con el error bajo template.

Un almacenamiento que no es suyo o no existe, o una clave sin nada en ella, se responde con 404. Una clave que no puede usarse (que empieza por /, con carpetas . o .., o de más de 900 bytes) se responde con 400. Un archivo que ya existe se responde con 409. Un almacenamiento al que no se puede acceder, que ha perdido su bucket o que rechaza sus claves se responde con 502, y uno que no responde a tiempo, con 504.

Una clave de API ausente o desconocida se responde con 400 o 401.

Direcciones web en las plantillas

Una plantilla es un dibujo, y un dibujo puede traer contenido de fuera: imágenes, piezas de biblioteca y modelos 3D vinculados a sus archivos o direcciones web, e instrucciones IMPORT y MERGE que los nombran. El servicio no lee ningún archivo, y de forma predeterminada tampoco obtiene ninguna dirección web: una plantilla que vincula o importa una se rechaza (400, indicando cuál). Incruste lo que muestra una plantilla (Edición › Vínculos › Incrustar todo en ParametrIQ CAD) antes de enviarla, y no necesitará nada más.

Si ejecuta el servicio usted mismo, puede permitir direcciones web de hosts de confianza en su configuración:

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

*.example.com permite cualquier host por debajo de example.com. Incluso desde estos hosts, solo se obtienen direcciones http y https, y solo cuando todas las direcciones IP a las que se resuelve el nombre del host son públicas: nunca una dirección privada (10.x, 172.16–31.x, 192.168.x, fc00::/7), de bucle invertido (127.x, 1), de enlace local (169.254.x, como los servicios de metadatos en la nube, fe80/10), compartida o reservada. Esto se comprueba en cada redirección (se siguen como máximo cinco) y de nuevo al establecer la conexión, de modo que una plantilla no puede hacer que el servicio llegue a su propia red. Un origen debe llegar en SaaS:UrlFetch:TimeoutSeconds (20), ocupar como máximo 64 MB y ser del tipo adecuado (una imagen para una imagen, nunca una página web); lo que no se puede obtener hace que se rechace la plantilla, indicando el motivo. Lo que se obtiene se almacena en caché (con el ETag y el Last-Modified del servidor) en los datos de aplicación locales del servicio.

Límites

• Tiempo. Cada solicitud dispone de 20 segundos para ejecutar su plantilla y generar lo solicitado. Una plantilla que siga ejecutándose en ese momento se detiene, y la solicitud se responde con 422 Unprocessable Content: la misma plantilla con los mismos valores tardaría lo mismo otra vez, así que no tiene sentido volver a enviarla sin cambios. Un script también se detiene tras un millón de instrucciones, sea cual sea el tiempo.
• Simultaneidad. Solo se procesa a la vez un número limitado de solicitudes; el resto espera su turno. Cuando hay demasiadas en espera, las siguientes se rechazan con 429 Too Many Requests: vuelva a enviarla un poco más tarde.
• Tamaño. Una solicitud ocupa como máximo 8 MB, una plantilla como máximo 2 millones de caracteres (una leída desde su almacenamiento, como máximo 8 MB) y una imagen como máximo 8000 píxeles de ancho.

Si ejecuta el servicio usted mismo, los almacenamientos necesitan SaaS:Storage:EncryptionKey: 32 bytes aleatorios, en base64 (openssl rand -base64 32). Manténgala en secreto, en los secretos de usuario o en una variable de entorno (SaaS__Storage__EncryptionKey), no en appsettings.json. Cambiarla hace ilegibles los secretos guardados, por lo que entonces habrá que volver a registrar los almacenamientos. SaaS:Storage:AllowHttp y SaaS:Storage:AllowPrivateEndpoints (ambos false) permiten que los almacenamientos usen http y direcciones privadas, para pruebas con un MinIO local. SaaS:Storage:MaxPerLicense (10), SaaS:Storage:TimeoutSeconds (30) y SaaS:Storage:MaxReadBytes (8 MB, la plantilla más grande que se lee desde un almacenamiento) establecen los límites. Sin la clave de cifrado, registrar o usar un almacenamiento se responde con 503.

Si ejecuta el servicio usted mismo, estos valores se establecen en su configuración: SaaS:TimeLimitSeconds (20), SaaS:MaxConcurrent (el número de procesadores) y SaaS:QueueLimit (50).

Consulte también: Clientes (ejemplos en JavaScript, Python, C#, Go y más), Ejecutar paramétrico (las mismas plantillas, en ParametrIQ CAD).