Transaccions

Una transacció és una llista d’operacions que s’executen de manera atòmica. Aquesta referència descriu l’estructura JSON de les sol·licituds de confirmació. Utilitzeu-la juntament amb la referència d’operacions per construir càrregues útils correctes i reproduïbles.

Visió general

Tots els canvis d’estat flueixen a través de l’endpoint /v1/write/namespaces/{namespace_id}/commit com a transaccions. El daemon d’escriptura valida, executa i afegeix operacions al registre de compromisos abans de retornar una resposta d’èxit. Això significa que cada mutació és auditable i reproduïble per disseny.

Estructura

Sol·licitud de Compromís

{
  "actor_id": "lab-operator-17",
  "policy_id": null,
  "operations": [
    { "op": "OperationName", "args": { ... } },
    { "op": "AnotherOperation", "args": { ... } }
  ],
  "idempotency_key": "optional-unique-key",
  "metadata": {
    "custom_field": "optional user metadata"
  },
  "origin": {
    "client": "assetcore-sdk",
    "source": "batch-import"
  }
}

Operació Sobre.

Cada operació té la mateixa estructura d’envolupant. Aquesta uniformitat és el que fa que la validació i les eines siguin fiables a través de tots els dominis.

{
  "op": "OperationName",
  "args": {
    "field1": "value1",
    "field2": 123
  }
}

Campanyes

Camps de sol·licitud

Camp	Tipus	Requerit	Descripció
operations	array	Sí	Llista d’operacions a executar
actor_id	string	No	Identificador de l’actor per a les pistes d’auditoria
policy_id	string	No	Identificador de la política (ús futur)
idempotency_key	string	No	Clau única per a la deduplicació
metadata	objecte	No	Metadades definides per l’usuari reflectides en la resposta
origin	objecte	No	Metadades d’origen opcionals reflectides en la resposta

Camps d’Operació Envelope

Camp	Tipus	Requerit	Descripció
op	cadena	Sí	Identificador de l’operació
args	objecte	Sí	Arguments específics de l’operació

Camps de resposta

Camp	Tipus	Descripció
namespace	enter	Espai de noms en què s’executa la transacció
commit_id	cadena	Identificador opac del commit utilitzat per a commits inversos
outcome	cadena	Completat o Revertit
world_seq_start	enter	Primer número de seqüència mundial en el commit
world_seq_end	enter	Número de seqüència mundial final en el commit
event_count	enter	Nombre d’esdeveniments emesos
start_time_ms	enter	Hora d’inici de la transacció (mil·lisegons des de l’epoch)
commit_time_ms	enter	Hora de commit de la transacció (mil·lisegons des de l’epoch)
server_correlation_id	cadena	ID de correlació assignat pel servidor per al seguiment
client_correlation_id	cadena	ID de correlació proporcionat pel client quan s’ofereix
origin	objecte	Eco de la metadada d’origen proporcionada pel cridant
echo	objecte	Eco de la metadada de la sol·licitud que inclou idempotency_key
created_entities	objecte	Resum d’entitats creades durant el commit

Exemples

Transacció Mínima

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 1001,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    }
  ]
}

Transacció amb Idempotència

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 1002,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    }
  ],
  "idempotency_key": "create-container-2026-01-15-001"
}

Transacció Multi-Operació

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 2001,
        "kind": { "type": "slots", "count": 8 },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "RegisterClass",
      "args": {
        "request": {
          "class_id": 200,
          "flags": 2,
          "name": "SampleClass"
        }
      }
    },
    {
      "op": "AddInstance",
      "args": {
        "class_id": 200,
        "key": 1,
        "location": {
          "container_id": 2001,
          "kind": "slot",
          "slot_index": 1
        }
      }
    }
  ],
  "metadata": {
    "experiment_id": "exp-001",
    "operator": "system"
  }
}

Resposta:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 5,
  "world_seq_end": 5,
  "event_count": 3,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "echo": {
    "metadata": {
      "experiment_id": "exp-001",
      "operator": "system"
    }
  },
  "created_entities": {
    "classes": [200],
    "containers": [2001],
    "instances": [9001]
  }
}

Resposta de Reintents Idempotents

Quan la mateixa clau d’idempotència s’envia de nou:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 5,
  "world_seq_end": 5,
  "event_count": 3,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "echo": {
    "idempotency_key": "create-sample-2026-01-15-001",
    "metadata": {
      "experiment_id": "exp-001",
      "operator": "system"
    }
  },
  "created_entities": {
    "classes": [200],
    "containers": [2001],
    "instances": [9001]
  }
}

L’encapçalament x-asset-idempotency: hit indica una resposta emmagatzemada en caché.

Referències relacionades

• Acció de Referència - Referència completa de l’operació
• Receipts - Patrons comuns de múltiples operacions
• Model d’Error - Gestió de fallades en transaccions