Fichier de spécification d'entrée

La commande d'initialisation Blockchain App Builder lit le fichier de spécification d'entrée et génère le projet échafaudé avec plusieurs outils pour aider au processus de développement de code chaîne.

Avec le fichier de spécification, vous pouvez indiquer plusieurs définitions et comportements de ressource, la déclaration de méthode CRUD et non-CRUD, les méthodes personnalisées, la validation des arguments, la sérialisation/désérialisation automatique, la fonctionnalité de persistance transparente et l'appel de requêtes de données enrichies à l'aide de SQL SELECT ou du langage de requête CouchDB. Ces fonctionnalités seront générées pour vous.

Pour plus d'informations sur la spécification des ressources de jeton, reportez-vous aux rubriques suivantes :
Le fichier de spécification peut être écrit dans yaml ou json. Vous pouvez voir des exemples de fichiers de spécification dans les deux formats dans le téléchargement du package Blockchain App Builder :
  • Fabcar-Typescript.yml
  • Marbles-Go.yml

Remarques :

Conformément aux conventions Go, les noms exportés commencent par une majuscule. Par conséquent, toutes les propriétés et méthodes d'actif doivent avoir des noms commençant par des lettres majuscules dans le fichier de spécification.

Structure du fichier de spécification

Généralement, vous structurez un fichier de spécification de la manière suivante :

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

Blockchain App Builder prend en charge deux types de ressource spéciaux, les ressources intégrées et les ressources de jeton, en plus des ressources génériques sans type spécifié. Les ressources spéciales sont définies comme type: embedded ou type: token dans la section assets: du fichier de spécification.

Tableau 7-2 Description et exemples de paramètres de fichier de spécification

Entrée Description Exemples 
assets:

Cette propriété prend la définition et le comportement de la ressource. Vous pouvez indiquer plusieurs définitions d'immobilisation ici.

  
name:

Nom de la ressource.

Les noms suivants sont réservés. N'utilisez pas ces noms pour les ressources.
  • account
  • role
  • hold
  • token
  • authorization
  • tokenAdmin
  • Account
  • Role
  • Hold
  • Token
  • Authorization
  • TokenAdmin
 
name: owner # Information about the owner
type:

Types de ressource

Les types de ressource spéciale suivants sont pris en charge :
  • embedded
  • token

Si vous n'indiquez pas de paramètre type dans la section assets, la ressource est de type générique.

 
type:

type : incorporé

Si cette propriété est définie sur embedded, la ressource est définie en tant que ressource imbriquée. Les immobilisations incorporées ne disposent pas de méthodes CRUD et doivent faire partie d'une autre immobilisation à stocker dans le livre.

Dans l'exemple, la propriété address est imbriquée et définie dans une autre ressource.

Les ressources intégrées ne prennent pas en charge les références circulaires. Par exemple, dans l'exemple précédent, la ressource address ne peut pas contenir de référence à la ressource employee.

Equipement : 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
Ressource : address
name: address

type: embedded

properties:
   name: street
   type: string

   name: city
   type: string

   name: state
   type: string

   name: country
   type: string
properties:

Décrire toutes les propriétés d'une ressource.

  
name:

Nom de la propriété.

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

Indique l'identifiant de cette immobilisation. Cette propriété est obligatoire. 

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:

Types de propriété

Les types de propriété de base suivants sont pris en charge :
  • number
  • float
  • string
  • boolean
  • date
  • array
Pour les codes chaîne Go, number est mis en correspondance avec int et float est mis en correspondance avec float64. D'autres types ne sont pas pris en charge actuellement, notamment les suivants :
  • 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:

Cette propriété indique que la propriété id est dérivée d'autres clés. Les propriétés dépendantes doivent être de type de données string et non une ressource imbriquée.

Cette propriété comporte deux paramètres obligatoires :
  • strategy : prend les valeurs concat ou hash.
  • format : prend un tableau de chaînes de spécification et de valeurs à utiliser par la stratégie.
Exemple 1 :
  • La propriété employeeID dépend des propriétés firstName et lastName.
  • Cette propriété est une concaténation des valeurs répertoriées dans le tableau format.
  • IND%1#%2%tIND est le 0e index du tableau et décrit le format final.
  • %n est un spécificateur de position qui extrait ses valeurs des autres index du tableau.
  • %t indique que la valeur doit être stub.timestamp à partir de l'en-tête de canal.
  • Si vous devez utiliser le caractère % dans la chaîne format, vous devez l'échapper avec un autre %.
  • Dans cet exemple, le format final serait : INDfirstName#lastName1606885454916IND
Exemple 2 :
  • Lorsque vous utilisez hash, vous devez également utiliser le paramètre algorithm. La valeur par défaut est sha256 ; md5 est également pris en charge.
  • IND%1#%2%t est le 0e index du tableau et décrit le format final.
  • %n est un spécificateur de position qui extrait ses valeurs des autres index du tableau.
  • %t indique que la valeur doit être stub.timestamp à partir de l'en-tête de canal.
  • Si vous devez utiliser le caractère % dans la chaîne format, vous devez l'échapper avec un autre %.
Exemple 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)
Exemple 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 propriété correspondante est obligatoire et ne peut pas être ignorée lors de la création d'une immobilisation.

 
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:

Cela vous donne la valeur par défaut de cette propriété.

  
validate:

La propriété donnée est validée par rapport à certaines des validations prêtes à l'emploi fournies par Blockchain App Builder. Vous pouvez enchaîner les validations si vous assurez que la chaîne est valide.

Si la propriété validate n'est pas fournie, la validation est effectuée uniquement sur la propriété type.

 
validate:

type : nombre
  • positive()
  • négative()
  • min()
  • max()

Ces validations peuvent être enchaînées par des virgules. 

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

type : chaîne
  • min()
  • max()
  • email()
  • url()
  • /regex/ : prend en charge les expressions régulières PHP

Pour les codes chaîne Go, les expressions régulières contenant certains caractères réservés ou espaces doivent être correctement échappées.

 
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:

type : boolean
  • True
  • False

Dans l'exemple, la validation de la propriété active est effectuée par le type lui-même (boolean) 

name: active
type: boolean
validate:

type : tableau

Par type lui-même, sous la forme de type: number[], cela indique que le tableau est de type numérique.

Vous pouvez entrer des limites pour le tableau au format number[1:5], ce qui signifie que la longueur minimale est de 1, la longueur maximale est de 5. Si l'un des deux est évité, seul min/max est pris en compte. 

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

type : date
  • min()
  • max()
La date doit avoir l'un des formats suivants :
  • YYYY-MM-DD
  • YYYY-MM-DDTHH:MM:SSZ, où T sépare la date de l'heure, et Z indique UTC. Les décalages horaires peuvent remplacer Z comme dans -05:00 pour l'heure d'été centrale. 
name: expiryDate
type: date
validate: max('2020-06-26')
name: completionDate
type: date
validate: min('2020-06-26T02:30:55Z')
methods:

Utilisez cette option pour indiquer laquelle des méthodes CRUD (Créer/Lire/Mettre à jour/Supprimer) ou supplémentaires doit être générée.

Par défaut, si rien n'est saisi, toutes les méthodes CRUD et autres sont générées.

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

Si ce tableau reste vide, aucune méthode CRUD ne sera créée.

Si le paramètre crud n'est pas utilisé du tout, les quatre méthodes sont créées par défaut.

Le paramètre crud n'est pas applicable aux ressources token et embedded. 

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

getHistoryById renvoie l'historique de la ressource dans une liste.

getByRange renvoie toutes les ressources d'une plage donnée. Pour plus d'informations, reportez-vous à "getByRange" (TypeScript) et à "GetByRange" (OK).

Si ce tableau reste vide, aucune autre méthode ne sera créée.

Si le paramètre others n'est pas utilisé du tout, les deux méthodes sont créées par défaut.

Le paramètre others n'est pas applicable aux ressources token et embedded. 

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

Cette propriété crée des modèles de méthode personnalisée invocables dans le fichier de contrôleur principal. Il prend la signature de la méthode et crée la déclaration de fonction dans le fichier de contrôleur.

Vous pouvez fournir des déclarations de fonction spécifiques à la langue ici.

Nous fournissons une méthode personnalisée nommée executeQuery. S'il est ajouté au fichier de spécification, il détaille la façon dont les requêtes Berkeley DB SQL et CouchDB riches peuvent être exécutées. Cette méthode ne peut être appelée que lorsque vous êtes connecté à 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)"

Go

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