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é, qui inclut des outils pour faciliter le processus de développement du code de chaîne.

Dans le fichier de spécification, vous pouvez spécifier plusieurs définitions et comportements de ressource, déclaration de méthode CRUD et non CRUD, méthodes personnalisées, validation d'arguments, conversion automatique de paramètres/déconversion de paramètres, capacité de persistance transparente et possibilité de terminer des interrogations de données enrichies à l'aide d'énoncés SQL SELECT ou du langage d'interrogation CouchDB. Ces fonctionnalités sont générées pour vous.

Pour plus d'informations sur la spécification des ressources de jeton, voir les rubriques suivantes :
Le fichier de spécification peut être écrit au format 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

Note :

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

Structure du fichier de spécifications

En général, vous structurez un fichier de spécifications 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 3-2 : Descriptions 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 l'immobilisation. Vous pouvez définir plusieurs immobilisations.

  
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 ne spécifiez pas de paramètre type dans la section assets, la ressource est de type générique.

 
type:

type : intégré

Si cette propriété est réglée à embedded, la ressource est définie en tant que ressource intégrée. Les immobilisations intégrées n'ont pas de méthode CRUD et doivent faire partie d'une autre immobilisation à stocker dans le grand livre.

Dans l'exemple, la propriété address est intégrée et est 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.

Ressource : 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écrit toutes les propriétés d'une ressource.

  
name:

Nom de la propriété.

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

Indique l'identificateur 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és

Les types de propriété de base suivants sont pris en charge :
  • number
  • float
  • string
  • boolean
  • date
  • array
Pour les codes de chaîne Go, number est mappé à int et float est mappé à float64. Les autres types ne sont pas pris en charge actuellement, notamment les types 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é spécifie que la propriété id est dérivée d'autres clés. Les propriétés dépendantes doivent être du type de données string et non une ressource intégré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 listé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 est la valeur stub.timestamp de l'en-tête de canal.
  • Si vous devez utiliser le signe de pourcentage (%) dans la chaîne format, il doit être échappé avec un autre signe de pourcentage (%).
  • Le format final dans cet exemple 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 est la valeur stub.timestamp de l'en-tête de canal.
  • Si vous devez utiliser le signe de pourcentage (%) dans la chaîne format, il doit être échappé avec un autre signe de pourcentage (%).
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:
  • Vrai
  • false

La propriété correspondante est obligatoire et ne peut pas être ignorée lors de la création d'une ressource.

 
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:

Valeur par défaut de cette propriété.

  
validate:

La propriété indiquée est validée par rapport à certaines des validations prêtes à l'emploi fournies par Blockchain App Builder. Vous pouvez effectuer des validations de chaîne si vous assurez la validité de la chaîne.

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

 
validate:

type : numéro
  • positif()
  • négative()
  • minute()
  • maximum()

Ces validations peuvent être enchaînées, séparé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 l'expression rationnelle PHP

Pour les codes de chaîne Go, les expressions rationnelles qui contiennent certains caractères réservés ou des espaces doivent faire l'objet d'un échappement approprié.

 
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 : booléen
  • Vrai
  • false

Dans l'exemple, la validation de la propriété active est 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 signifie que le tableau est de type number.

Vous pouvez entrer des limites au tableau dans le format number[1:5], ce qui signifie que la longueur minimale est de 1 et que la longueur maximale est de 5. Vous pouvez omettre l'un ou l'autre. 

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 de fuseau horaire 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 la méthode CRUD (Create/Read/Update/Delete) ou d'autres méthodes à générer.

Par défaut, toutes les méthodes CRUD et autres sont générées.

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

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

Si le paramètre crud n'est pas spécifié, les quatre méthodes seront créées par défaut.

Le paramètre crud ne s'applique pas aux ressources token et embedded. 

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

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

getByRange retourne toutes les ressources d'un intervalle donné. Pour plus de renseignements, consultez la page " getByRange " (TypeScript) et " GetByRange " (Go).

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

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

Le paramètre others ne s'applique pas 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 appelables 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 contrôleur.

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

Une méthode personnalisée nommée executeQuery est fournie. Si vous ajoutez cette méthode au fichier de spécification, elle détaille comment les interrogations Berkeley DB SQL et CouchDB Rich peuvent être exécutées. Cette méthode ne peut être utilisé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)"