Arquivo de Especificação de Entrada

O comando de inicialização do Blockchain App Builder lê o arquivo de especificação de entrada e gera o projeto com andaimes com várias ferramentas para auxiliar no processo de desenvolvimento de chaincode.

Com o arquivo de especificação, você pode especificar várias definições e comportamentos de ativos, declaração de método CRUD e não CRUD, métodos personalizados, validação de argumentos, marshalling automático/unmarshalling, recurso de persistência transparente e chamada de consultas avançadas de dados usando SQL SELECTs ou CouchDB Query Language. Esses recursos serão gerados para você.

Para obter informações sobre como especificar ativos de token, consulte estes tópicos:
O arquivo de especificação pode ser gravado em yaml ou json. Você pode ver arquivos de especificação de amostra em ambos os formatos no download do pacote Blockchain App Builder:
  • Fabcar-Typescript.yml
  • Marbles-Go.yml

Observação:

De acordo com as convenções Go, os nomes exportados começam com letra maiúscula. Portanto, todas as propriedades e métodos do ativo devem ter nomes que comecem com letras maiúsculas no arquivo de especificação.

Estrutura do Arquivo de Especificação

Normalmente, você estrutura um arquivo de especificação da seguinte maneira:

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

O Blockchain App Builder suporta dois tipos especiais de ativos, ativos incorporados e ativos de token, além de ativos genéricos sem tipo especificado. Os ativos especiais são definidos como type: embedded ou type: token na seção assets: do arquivo de especificação.

Tabela 7-2 Descrições e Exemplos de Parâmetro do Arquivo de Especificação

Entrada Descrição Exemplos
assets:

Essa propriedade assume a definição e o comportamento do ativo. Você pode fornecer várias definições de ativo aqui.

  
name:

O nome do ativo.

Estes nomes são reservados. Não use esses nomes para ativos.
  • account
  • role
  • hold
  • token
  • authorization
  • tokenAdmin
  • Account
  • Role
  • Hold
  • Token
  • Authorization
  • TokenAdmin
 
name: owner # Information about the owner
type:

Tipos de ativos

Os seguintes tipos de ativos especiais são suportados:
  • embedded
  • token

Se você não especificar um parâmetro type na seção assets, o ativo será do tipo genérico.

 
type:

tipo: incorporado

Se essa propriedade estiver definida como embedded, o ativo será definido como um ativo incorporado. Os ativos incorporados não têm métodos CRUD e precisam fazer parte de outro ativo para serem armazenados no razão.

No exemplo, a propriedade address é incorporada e definida em outro ativo.

Os ativos incorporados não suportam referências circulares. Por exemplo, no exemplo anterior, o ativo address não pode conter uma referência ao ativo employee.

Ativo: 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
Ativo: address
name: address

type: embedded

properties:
   name: street
   type: string

   name: city
   type: string

   name: state
   type: string

   name: country
   type: string
properties:

Descreva todas as propriedades de um ativo.

  
name:

O nome da propriedade.

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

Especifica o identificador deste ativo. Esta propriedade é obrigatória.

 
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 propriedades

Os seguintes tipos de propriedade básica são suportados:
  • number
  • float
  • string
  • boolean
  • date
  • array
Para códigos de cadeia Go, number é mapeado para int e float é mapeado para float64. Outros tipos não são suportados atualmente, incluindo os seguintes tipos:
  • 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 propriedade especifica que a propriedade id é derivada de outras chaves. As propriedades dependentes devem ser do tipo de dados string e não um ativo incorporado.

Esta propriedade tem dois parâmetros obrigatórios:
  • strategy: usa valores de concat ou hash.
  • format: usa um array de strings de especificação e valores a serem usados pela estratégia.
Exemplo 1:
  • A propriedade employeeID depende das propriedades firstName e lastName.
  • Esta propriedade é uma concatenação dos valores listados no array format.
  • IND%1#%2%tIND é o 0o índice no array e descreve o formato final.
  • %n é um especificador de posição que extrai seus valores dos outros índices no array.
  • %t indica que o valor deve ser stub.timestamp no cabeçalho do canal.
  • Se você precisar usar o caractere % na string format, ele deverá ter escape com outro %.
  • O formato final neste exemplo seria: INDfirstName#lastName1606885454916IND
Exemplo 2:
  • Ao usar hash, você também deve usar o parâmetro algorithm. O padrão é sha256; md5 também é suportado.
  • IND%1#%2%t é o 0o índice no array e descreve o formato final.
  • %n é um especificador de posição que extrai seus valores dos outros índices no array.
  • %t indica que o valor deve ser stub.timestamp no cabeçalho do canal.
  • Se você precisar usar o caractere % na string format, ele deverá ter escape com outro %.
Exemplo 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)
Exemplo 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:
  • verdadeiro
  • falso

A propriedade correspondente é obrigatória e não pode ser ignorada durante a criação de um ativo.

 
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:

Isso fornece o valor padrão dessa propriedade.

  
validate:

A propriedade fornecida é validada em relação a algumas das validações prontas para uso fornecidas pelo Blockchain App Builder. Você poderá encadear validações se garantir que a cadeia seja válida.

Se a propriedade validate não for fornecida, a validação será feita somente em relação à propriedade type.

 
validate:

tipo: número
  • positivo()
  • negativo()
  • minuto()
  • máximo()

Essas validações podem ser encadeadas juntas separadas por vírgulas. 

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

tipo: string
  • min()
  • max()
  • email()
  • url()
  • /regex/ - suporta PHP regex

Para códigos de cadeia Go, as expressões regulares que contêm determinados caracteres reservados ou caracteres de espaço em branco devem ter escape adequado.

 
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
  • verdadeiro
  • falso

No exemplo, a validação da propriedade active é pelo próprio tipo (boolean) 

name: active
type: boolean
validate:

tipo: array

Por tipo próprio, na forma de type: number[], isso transmite que o array é do tipo número.

Você pode informar limites para o array no formato number[1:5], o que significa que o tamanho mínimo é 1, o máximo é 5. Se qualquer um deles for evitado, apenas mínimo/máximo será considerado. 

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

tipo: data
  • min()
  • max()
A data deve ser um destes formatos:
  • YYYY-MM-DD
  • YYYY-MM-DDTHH:MM:SSZ, em que T separa a data da hora, e Z indica UTC. As compensações de fuso horário podem substituir o Z como em -05:00 para Horário de Verão Central. 
name: expiryDate
type: date
validate: max('2020-06-26')
name: completionDate
type: date
validate: min('2020-06-26T02:30:55Z')
methods:

Use-o para informar quais métodos CRUD (Criar/Ler/Atualizar/Excluir) ou adicionais devem ser gerados.

Por padrão, se nada for inserido, todos os métodos CRUD e outros serão gerados.

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

Se essa matriz for deixada vazia, nenhum método CRUD será criado.

Se o parâmetro crud não for usado, todos os quatro métodos serão criados por padrão.

O parâmetro crud não é aplicável aos ativos token e embedded. 

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

getHistoryById retorna o histórico do ativo em uma lista.

getByRange retorna todos os ativos em um determinado intervalo. Para obter mais informações, consulte "getByRange" (TypeScript) e "GetByRange" (Ir).

Se esse array for deixado vazio, nenhum outro método será criado.

Se o parâmetro others não for usado, ambos os métodos serão criados por padrão.

O parâmetro others não é aplicável aos ativos token e embedded. 

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

Essa propriedade cria modelos de método personalizado invocáveis no arquivo do controlador principal. Ele pega a assinatura do método e cria a declaração de função no arquivo do controlador.

Você pode fornecer declarações de função específicas do idioma aqui.

Fornecemos um método personalizado chamado executeQuery. Se for adicionado ao arquivo de especificação, ele detalha como as consultas SQL e rich CouchDB do BD Berkeley podem ser executadas. Esse método só pode ser chamado quando você estiver conectado ao Oracle Blockchain Platform Cloud ou 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)"

Ir

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