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 scaffolded, que inclui ferramentas para auxiliar no processo de desenvolvimento de chaincode.

No 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/unmarshalling automático, capacidade de persistência transparente e a capacidade de concluir consultas de dados avançadas usando instruções SQL SELECT ou a linguagem de consulta CouchDB. Esses recursos são gerados para você.

Para obter informações sobre como especificar ativos de token, consulte os seguintes tópicos:
O arquivo de especificação pode ser gravado no formato 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 uma 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 oferece suporte a dois tipos de ativos especiais, 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 3-2 Descrições e Exemplos de Parâmetros do Arquivo de Especificação

Entrada Descrição Exemplos
assets:

Essa propriedade usa a definição e o comportamento do ativo. Você pode definir vários ativos.

  
name:

O nome do ativo.

Os nomes a seguir 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 do ativo

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 for definida como embedded, o ativo será definido como um ativo incorporado. Os ativos incorporados não têm métodos CRUD e devem fazer parte de outro ativo a ser armazenado 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:

Descreve 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 propriedade

Os seguintes tipos básicos de propriedade 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 no momento, 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: obtém valores de concat ou hash.
  • format: usa um array de strings e valores de especificação para serem usados pela estratégia.
Exemplo 1:
  • A propriedade employeeID depende das propriedades firstName e lastName.
  • Essa propriedade é uma concatenação dos valores listados no array format.
  • IND%1#%2%tIND é o 0º í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 é o valor stub.timestamp do cabeçalho do canal.
  • Se você precisar usar o sinal de porcentagem (%) na string format, ele deverá ter escape com outro sinal de porcentagem (%).
  • 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 0º í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 é o valor stub.timestamp do cabeçalho do canal.
  • Se você precisar usar o sinal de porcentagem (%) na string format, ele deverá ter escape com outro sinal de porcentagem (%).
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:

O valor padrão desta propriedade.

  
validate:

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

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

 
validate:

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

Essas validações podem ser encadeadas, 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 regex PHP

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

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

name: active
type: boolean
validate:

tipo: matriz

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

Você pode informar limites para o array no formato number[1:5], o que significa que o tamanho mínimo é 1 e o máximo é 5. Você pode omitir qualquer um deles. 

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 o 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 esta opção para indicar qual dos métodos CRUD (Criar/Ler/Atualizar/Excluir) ou adicionais serão gerados.

Por padrão, todos os métodos CRUD e outros são gerados.

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

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

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

O parâmetro crud não se aplica a 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" (Go).

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

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

O parâmetro others não se aplica a 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:

Esta propriedade cria modelos de método personalizados 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.

Um método personalizado chamado executeQuery é fornecido. Se você adicionar esse método ao arquivo de especificação, ele detalha como as consultas SQL do Berkeley DB e rich CouchDB podem ser executadas. Esse método só pode ser considerado quando você está conectado ao Oracle Blockchain Platform Cloud ou ao 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)"