Archivo de especificación de entrada

El comando de inicialización de Blockchain App Builder lee el archivo de especificación de entrada y genera el proyecto andamiaje, que incluye herramientas para ayudar en el proceso de desarrollo del código de cadenas.

En el archivo de especificación puede especificar varias definiciones y comportamientos de activos, declaraciones de métodos CRUD y no CRUD, métodos personalizados, validación de argumentos, canalización automática/anulación de canalización automática, capacidad de persistencia transparente y la capacidad de completar consultas de datos enriquecidos mediante sentencias SQL SELECT o el lenguaje de consulta CouchDB. Estas funciones se generan para usted.

Para obtener información sobre la especificación de activos de token, consulte los siguientes temas:
El archivo de especificación se puede escribir en formato YAML o JSON. Puede ver archivos de especificación de ejemplo en ambos formatos en la descarga del paquete Blockchain App Builder:
  • Fabcar-Typescript.yml
  • Marbles-Go.yml

Note:

De acuerdo con las convenciones de Go, los nombres exportados comienzan con una letra mayúscula. Por lo tanto, todas las propiedades y métodos del activo deben tener nombres que empiecen por letras mayúsculas en el archivo de especificación.

Estructura del archivo de especificación

Normalmente, un archivo de especificación se estructura de la siguiente manera:

assets: 
    name:
    type:
    properties:
        name:
        type:
        id:
        derived:
           strategy:
           algorithm:
           format:
        mandatory:
        default:
        validate:
    methods:
        crud:
        others:
customMethods:

Blockchain App Builder soporta dos tipos de activos especiales, activos embebidos y activos de token, además de activos genéricos sin ningún tipo especificado. Los activos especiales se definen como type: embedded o type: token en la sección assets: del archivo de especificación.

Tabla 3-2 Descripciones y ejemplos de parámetros del archivo de especificación

Entrada Descripción Ejemplos
assets:

Esta propiedad toma la definición y el comportamiento del activo. Puede definir varios activos.

  
name:

El nombre del activo.

Los siguientes nombres están reservados. No utilice estos nombres para los activos.
  • account
  • role
  • hold
  • token
  • authorization
  • tokenAdmin
  • Account
  • Role
  • Hold
  • Token
  • Authorization
  • TokenAdmin
 
name: owner # Information about the owner
type:

Tipos de activos

Se admiten los siguientes tipos de activos especiales:
  • embedded
  • token

Si no especifica un parámetro type en la sección assets, el activo es del tipo genérico.

 
type:

tipo: embebido

Si esta propiedad se define en embedded, el activo se define como un activo embebido. Los activos embebidos no tienen métodos CRUD y deben formar parte de otro activo que se almacenará en la contabilidad.

En el ejemplo, la propiedad address está embebida y se define en otro activo.

Los activos embebidos no soportan referencias circulares. Por ejemplo, en el ejemplo anterior, el activo address no puede contener una referencia al activo employee.

Activo: employee
name: employee
  properties:
     name: employeeId
     type: string
     mandatory: true
     id: true

     name: firstName
     type: string
     validate: max(30)
     mandatory: true

     name: lastName
     type: string
     validate: max(30)
     mandatory: true

     name: age
     type: number
     validate: positive(),min(18)

     name: address
     type: address
Activo: address
name: address

type: embedded

properties:
   name: street
   type: string

   name: city
   type: string

   name: state
   type: string

   name: country
   type: string
properties:

Describe todas las propiedades de un activo.

  
name:

Nombre de la propiedad.

 
name: ownerId # Unique ID for each owner
id:
  • true

Especifica el identificador de este activo. Esta propiedad es obligatoria.

 
name: owner            # Information about the owner
properties:
     name: ownerId    # Unique ID for each owner
     type: string
     mandatory: true
     id: true
     name: name        # Name of the owner
     type: string
     mandatory: true
type:

Tipos de propiedad

Se admiten los siguientes tipos de propiedades básicas:
  • number
  • float
  • string
  • boolean
  • date
  • array
Para los códigos de cadenas Go, number se asigna a int y float se asigna a float64. Actualmente no se admiten otros tipos, incluidos los siguientes:
  • complex
  • unsigned/signed int
  • 8/16/32/64 bits
 
name: year        # Model year
                    type: number
                    mandatory: true
                    validate: min(1910),max(2020)
                    name: color       # Color - no validation as color names are innumerable
                    type: string
                    mandatory: true
derived:

Esta propiedad especifica que la propiedad id se deriva de otras claves. Las propiedades dependientes deben ser del tipo de dato string y no un activo embebido.

Esta propiedad tiene dos parámetros obligatorios:
  • strategy: toma los valores concat o hash.
  • format: toma una matriz de cadenas y valores de especificación que utilizará la estrategia.
Ejemplo 1:
  • La propiedad employeeID depende de las propiedades firstName y lastName.
  • Esta propiedad es una concatenación de los valores mostrados en la matriz format.
  • IND%1#%2%tIND es el 0º índice de la matriz y describe el formato final.
  • %n es un especificador de posición que toma sus valores de los otros índices de la matriz.
  • %t indica que el valor es el valor stub.timestamp de la cabecera del canal.
  • Si necesita utilizar el signo de porcentaje (%) en la cadena format, debe identificarse con otro signo de porcentaje (%).
  • El formato final de este ejemplo sería: INDfirstName#lastName1606885454916IND
Ejemplo 2:
  • Al utilizar hash, también debe utilizar el parámetro algorithm. El valor por defecto es sha256; también se admite md5.
  • IND%1#%2%t es el 0º índice de la matriz y describe el formato final.
  • %n es un especificador de posición que toma sus valores de los otros índices de la matriz.
  • %t indica que el valor es el valor stub.timestamp de la cabecera del canal.
  • Si necesita utilizar el signo de porcentaje (%) en la cadena format, debe identificarse con otro signo de porcentaje (%).
Ejemplo 1
name: employee
  properties:
     name: employeeId
     type: string
     mandatory: true
     id: true
     derived:
         strategy: concat
         format: ["IND%1#%2%tIND","firstName","lastName"]

     name: firstName
     type: string
     validate: max(30)
     mandatory: true

     name: lastName
     type: string
     validate: max(30)
     mandatory: true

     name: age
     type: number
     validate: positive(),min(18)
Ejemplo 2
name: account
  properties:
     name: accountId
     type: string
     mandatory: true
     id: true
     derived:
         strategy: hash
         algorithm: 'sha256'
         format: ["IND%1#%2%t","bankName","ifsccode"]

     name: bankName
     type: string
     validate: max(30)
     mandatory: true

     name: ifsccode
     type: string
     mandatory: true
mandatory:
  • true
  • false

La propiedad correspondiente es obligatoria y no se puede omitir al crear un activo.

 
name: phone       # Phone number - validate as (ddd)-ddd-dddd where dashes could also be periods or spaces
type: string
mandatory: true
validate: /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/
name: cars        # The list of car VINs owned by this owner
type: string[]
mandatory: false
default:

El valor por defecto de esta propiedad.

  
validate:

La propiedad determinada se valida con respecto a algunas de las validaciones listas para usar proporcionadas por Blockchain App Builder. Puede encadenar validaciones si se asegura de que la cadena sea válida.

Si no se proporciona la propiedad validate, la validación se realiza solo con la propiedad type.

 
validate:

tipo: número
  • positivo()
  • negativo()
  • min()
  • max()

Estas validaciones se pueden encadenar, separadas por comas. 

name: offerApplied
type: number
validate: negative(),min(-4)
name: year  # Model year
type: number
mandatory: true
validate: min(1910),max(2020)
validate:

tipo: cadena
  • min()
  • max()
  • email()
  • url()
  • /regex/ soporta la expresión regular PHP

Para los códigos de cadenas Go, las expresiones regulares que contienen determinados caracteres reservados o espacios en blanco deben identificarse correctamente.

 
name: website 
type: string
mandatory: false
validate: url()
name: phone  # Phone number - validate as (ddd)-ddd-dddd where dashes could also be periods or spaces
type: string
mandatory: true
validate: /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/
name: Color #Color can be red, blue, or green
type: string
mandatory: true
validate: /^\\s*(red|blue|green)\\s*$/
validate:

tipo: booleano
  • true
  • false

En el ejemplo, la validación de la propiedad active se realiza por el propio tipo (boolean) 

name: active
type: boolean
validate:

tipo: matriz

Por tipo en sí, con el formato type: number[], esto transmite que la matriz es del tipo number.

Puede introducir límites para la matriz con el formato number[1:5], lo que significa que la longitud mínima es 1 y el máximo es 5. Puede omitir cualquiera de ellas. 

name: items
type: number[:5]
validate:

Tipo: fecha
  • min()
  • max()
La fecha debe tener uno de estos formatos:
  • YYYY-MM-DD
  • YYYY-MM-DDTHH:MM:SSZ, donde T separa la fecha de la hora, y Z indica UTC. Las compensaciones de zona horaria pueden sustituir a Z, como en -05:00 para el horario central de verano. 
name: expiryDate
type: date
validate: max('2020-06-26')
name: completionDate
type: date
validate: min('2020-06-26T02:30:55Z')
methods:

Utilice esta opción para indicar cuál de los métodos CRUD (Crear/Leer/Actualizar/Suprimir) o adicionales se van a generar.

Por defecto, se generan todos los métodos CRUD y otros.

 
methods:
    crud: [create, getById, update, delete]
    others: [getHistoryById, getByRange]
crud:
  • create
  • getByID (lectura)
  • update
  • delete

Si esta matriz se deja vacía, no se creará ningún método CRUD.

Si no se especifica el parámetro crud, se crearán los cuatro métodos por defecto.

El parámetro crud no se aplica a los activos token y embedded. 

methods:
    crud: [create, getById, delete]
    others: [] # no other methods will be created
others:
  • getHistoryById
  • getByRange

getHistoryById devuelve el historial del activo en una lista.

getByRange devuelve todos los activos de un rango determinado. Para obtener más información, consulte "getByRange" (TypeScript) y "GetByRange" (Go).

Si esta matriz se deja vacía, no se creará ningún otro método.

Si el parámetro others no se utiliza en absoluto, ambos métodos se crearán por defecto.

El parámetro others no se aplica a los activos token y embedded. 

methods:
    crud: [create, delete]
    others: [] # no other methods will be created
      methods:
        crud: [create, getById, update, delete]
        others: [getHistoryById, getByRange]
customMethods:

Esta propiedad crea plantillas de métodos personalizados invocables en el archivo del controlador principal. Toma la firma del método y crea la declaración de función en el archivo del controlador.

Puede proporcionar declaraciones de función específicas del idioma aquí.

Se proporciona un método personalizado denominado executeQuery. Si agrega este método al archivo de especificación, detalla cómo se pueden ejecutar las consultas enriquecidas de Berkeley DB SQL y CouchDB. Este método solo se puede llamar cuando está conectado a Oracle Blockchain Platform Cloud o Enterprise Edition.

TypeScript

customMethods:
    - executeQuery
    - "buyCar(vin: string, buyerId: string, sellerId: string, price: number, date: Date)"
    - "addCar(vin: string, dealerId: string, price: number, date: Date)"

Go

customMethods:
    - executeQuery
    - "BuyCar(vin string, buyerId string, sellerId string, price int)"
    - "AddCar(vin string, dealerId string, price int)"