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 aider au processus de développement de code chaîne.

Dans 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 persistance transparente et la possibilité de terminer des requêtes de données enrichies à l'aide d'instructions SQL SELECT ou du langage de requête CouchDB. Ces fonctionnalités sont 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 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

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

En règle générale, 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 3-2 Description et exemples des paramètres du 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 l'immobilisation.

Les noms suivants sont réservés. N'utilisez pas ces noms pour les immobilisations.
  • 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éciaux 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 : intégré

Si cette propriété est définie sur embedded, la ressource est définie en tant que ressource incorporée. Les immobilisations incorporées n'ont pas de méthodes CRUD et doivent faire partie d'une autre immobilisation pour être stockées dans le livre.

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

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:
  • True

Indique l'identifiant de cette ressource. 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 avec 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é indique 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 incorporée.

Cette propriété comporte deux paramètres obligatoires :
  • strategy : prend les valeurs concat ou hash.
  • format : prend un tableau de chaînes et de valeurs de spécification à 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 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 (%).
  • Dans cet exemple, le format final est le suivant : 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:
  • 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:

Valeur par défaut d'une propriété.

  
validate:

La propriété indiquée est validée par rapport à certaines 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 chaî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 régulière PHP

Pour les codes chaîne Go, les expressions régulières contenant certains caractères réservés ou des caractères non imprimables 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 : booléen
  • True
  • 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 type: number[], cela signifie que le tableau est de type number.

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

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

type : date
  • min()
  • max()
La date doit être 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 laquelle des méthodes CRUD (Créer/Lire/Mettre à jour/Supprimer) ou supplémentaires à 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 indiqué, les quatre méthodes sont 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 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" (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 sont 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 invokables dans le fichier de contrôleur principal. Il prend la signature de la méthode et crée la déclaration de la fonction dans le fichier de contrôleur.

Vous pouvez fournir des déclarations de fonction propres à la 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 requêtes Berkeley DB SQL et enrichies CouchDB 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)"