Los métodos de escritura reciben tres opciones de cambio junto a sus parámetros, el mismo protocolo que describe Simular y después confirmar:
| Opción | TypeScript | Python | Se envía como |
|---|---|---|---|
| Motivo | reason | reason= | X-Change-Reason. Obligatorio en las escrituras de configuración (el tipo lo exige), de 1 a 500 caracteres. |
| Simulación | dryRun: true | dry_run=True | ?dry_run=1: la respuesta es el plan y no cambia nada. |
| Versión esperada | ifMatch | if_match= | If-Match: "<versión>". Una versión antigua falla con 412 version_conflict. Obligatoria en revertZone / revert_zone. |
Un método solo acepta las opciones que admite su operación: por ejemplo, purgeCache recibe motivo y dryRun, pero no ifMatch, porque las purgas no se versionan.
El patrón
- Llama al método con
dryRun. La respuesta es un planApplied:from_version,to_version,diff.changesywarnings. - Enseña o comprueba las diferencias.
- Llama al mismo método con los mismos argumentos, sin
dryRuny conifMatchigual alfrom_versiondel plan.
import { OpenWAF, type Applied } from "./openwaf.ts";
const owf = new OpenWAF();
const params = { zone: zoneId, body: { hsts: { max_age: 300 } } };
const reason = "Activar HSTS";
const plan = (await owf.updateZoneEdge(params, { reason, dryRun: true })) as Applied;
console.log(plan.diff?.changes);
await owf.updateZoneEdge(params, { reason, ifMatch: plan.from_version! });Un método que puede responder un plan o un resultado está tipado como su unión, por ejemplo Promise<ZoneEdgeSettings | Applied>; convierte la respuesta de la simulación a Applied.
from openwaf import OpenWAF
owf = OpenWAF()
patch = {"hsts": {"max_age": 300}}
reason = "Activar HSTS"
plan = owf.update_zone_edge(zone=zone_id, body=patch, reason=reason, dry_run=True)
print(plan["diff"]["changes"])
owf.update_zone_edge(zone=zone_id, body=patch, reason=reason, if_match=plan["from_version"])Si la zona cambia entre las dos llamadas, la segunda lanza version_conflict y no aplica nada: ver Gestión de errores.
La versión nueva
El SDK devuelve el cuerpo de la respuesta, no sus cabeceras, así que el número de la versión nueva (X-Config-Version) no forma parte del resultado en la mayoría de las escrituras. Léelo cuando lo necesites: getZone / get_zone devuelve la zona con su config_version, y el historial de la zona enumera todas las versiones. La respuesta de una vuelta atrás sí lleva version en el cuerpo.