Génération d'une collection Postman à l'aide de la CLI

Vous pouvez utiliser la commande generate pour créer une collection Postman qui inclut des exemples de charge utile pour toutes les API de contrôleur de code chaîne.

Postman est un outil que vous pouvez utiliser pour utiliser et tester des API REST. La commande generate crée une collection Postman basée sur le code chaîne qui a été généré automatiquement à partir d'un fichier de spécification déclaratif. La collection Postman contient les charges utiles pour toutes les méthodes spécifiées dans le fichier de contrôleur de code chaîne. Vous pouvez modifier les valeurs de variable dans le fichier de collecte Postman pour effectuer des appels d'API REST.

La collection Postman générée inclut des valeurs par défaut pour toutes les API du contrôleur. Pour en savoir plus sur Postman, reportez-vous à https://www.postman.com/. Après avoir généré une collection Postman, vous pouvez l'importer directement et l'utiliser en modifiant les valeurs par défaut dans la charge utile et les variables.

Syntaxe :

generate [options]

my-mac:TsProject myname$ ochain generate -h 
Usage: generate [options]

Generates the postman collection for the chaincode. 

Options :
    -h, --help              output command usage information
    -D, --debug             enable debug logging
    -c, --collection        This option is mandatory to generate a Postman collection.
    -p, --project <path>    Path to the chaincode project to generate the Postman collection from. If not specified, it defaults to current directory.
    -o, --out <path>        Path to the generated Postman collection JSON file. If not specified, it defaults to current directory.

Pour générer une collection Postman, accédez au répertoire contenant le projet, puis entrez la commande suivante. Vous devez exécuter la commande generate à partir du répertoire de code chaîne, sinon une erreur se produira. Si la collection Postman spécifiée existe déjà, vous êtes invité à la remplacer.

ochain generate --collection --project path_to_chaincode_project --out path_to_postman_collection_to_generate

Structure de recouvrement Postman

La collection Postman générée comprend deux types de demandes, les demandes d'appel et les demandes de requête :

Les demandes d'appel incluent toutes les opérations d'écriture, qui utilisent l'adresse /transactions
Les demandes de requête incluent toutes les opérations get, qui utilisent l'adresse /chaincode-queries

Pour différencier les méthodes get et non get dans les API de contrôleur, un décorateur est utilisé dans les codes chaîne TypeScript et un commentaire est utilisé dans les codes chaîne Go. Si vous définissez une méthode get dans le contrôleur, vous devez utiliser le décorateur GetMethod pour TypeScript ou le commentaire GetMethod pour Go, comme indiqué dans le tableau suivant.

TypeScript Go

TypeScript	Go
Chaque méthode get dispose d'un décorateur `GetMethod` : `@GetMethod() @Validator() public async getAllTokenAdmins() { await this.Ctx.ERC1155Auth.checkAuthorization("ERC1155ADMIN.getAllAdmins", "TOKEN"); return await this.Ctx.ERC1155Admin.getAllAdmins(); }`	Chaque méthode get dispose d'un bloc de commentaires `GetMethod` : `/** * GetMethod / func (t Controller) GetAllTokenAdmins() (interface{}, error) { auth, err := t.Ctx.Auth.CheckAuthorization("Admin.GetAllAdmins", "TOKEN") if err != nil && !auth { return nil, fmt.Errorf("error in authorizing the caller %s", err.Error()) } return t.Ctx.Admin.GetAllTokenAdmins() }`

Chaque méthode get dispose d'un décorateur GetMethod :

@GetMethod()
@Validator()
public async getAllTokenAdmins() {
  await this.Ctx.ERC1155Auth.checkAuthorization("ERC1155ADMIN.getAllAdmins", "TOKEN");
  return await this.Ctx.ERC1155Admin.getAllAdmins();
}

Chaque méthode get dispose d'un bloc de commentaires GetMethod :

/**
 * GetMethod
 */
func (t *Controller) GetAllTokenAdmins() (interface{}, error) {
    auth, err := t.Ctx.Auth.CheckAuthorization("Admin.GetAllAdmins", "TOKEN")
    if err != nil && !auth {
        return nil, fmt.Errorf("error in authorizing the caller  %s", err.Error())
    }
    return t.Ctx.Admin.GetAllTokenAdmins()
}

Les collections Postman générées incluent des variables avec des valeurs par défaut, comme indiqué dans le tableau suivant.

Nom de variable	Description	Valeur par défaut	Contexte
`bc-url`	URL proxy REST de l'instance Oracle Blockchain Platform sur laquelle le code chaîne est déployé	`https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy`	tous les codes chaîne
`bc-channel`	Canal sur lequel le code chaîne est déployé	`default`	tous les codes chaîne
`bc-admin-user`	Nom de l'administrateur (utilisateur doté du rôle d'administrateur pouvant accéder à toutes les demandes POST). Par défaut, cet utilisateur est l'appelant de toutes les demandes POST dans le code chaîne	`bc-admin-user value`	tous les codes chaîne
`bc-admin-password`	Mot de passe de l'administrateur	`bc-admin-password value`	tous les codes chaîne
`bc-timeout`	Valeur de délai d'expiration dans le corps de chaque demande POST pour indiquer l'intervalle de délai d'expiration	`6000`	tous les codes chaîne
`bc-sync`	Valeur de synchronisation dans le corps de chaque demande POST pour indiquer si la demande est synchrone ou asynchrone	`true`	tous les codes chaîne
`bc-chaincode-name`	Le nom du code chaîne, qui est utilisé dans chaque demande POST	`chaincode name`	tous les codes chaîne
`bc-org-id`	Paramètre `orgId` par défaut pour toutes les demandes POST	`bc-org-id value`	codes chaîne de jeton uniquement
`bc-user-id`	Paramètre `userId` par défaut pour toutes les demandes POST	`bc-user-id value`	codes chaîne de jeton uniquement
`bc-token-id`	Paramètre `tokenId` par défaut pour toutes les demandes POST	`bc-token-id value`	codes chaîne de jeton uniquement

Dans chaque demande générée, tous les paramètres avec des valeurs par défaut sont générés. Les fonctions qui ont des paramètres struct/class auront un objet de réserve dans le corps de la demande, comme indiqué dans les exemples suivants.

API avec un paramètre struct/class

{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "CreateArtCollectionToken",
        "{\"TokenId\":\"{{bc-token-id}}\",\"TokenDesc\":\"TokenDesc value\",\"TokenUri\":\"TokenUri value\",\"TokenMetadata\":{\"Painting_name\":\"Painting_name value\",\"Description\":\"Description value\",\"Image\":\"Image value\",\"Painter_name\":\"Painter_name value\"},\"Price\":999,\"On_sale_flag\":true}",
        "quantity value"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}

API sans paramètre struct/class

{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "CreateAccount",
        "{{bc-org-id}}",
        "example_minter",
        "true",
        "true"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}

La valeur par défaut de la plupart des paramètres d'API est parameter_name value, à quelques exceptions près. Les exemples suivants présentent certaines exceptions.

Le paramètre de filtres dans GetAccountTransactionHistoryWithFilters :

"{\"PageSize\":20,\"Bookmark\":\"\",\"StartTime\":\"2022-01-16T15:16:36+00:00\",\"EndTime\":\"2022-01-17T15:16:36+00:00\"}"

Le paramètre de filtres dans GetSubTransactionsByIdWithFilters :
```
"{\"PageSize\":20,\"Bookmark\":\"\}"
```

Une structure ou une classe a des valeurs par défaut différentes, comme indiqué dans le tableau suivant :

Type de données	Valeur par défaut
`boolean/bool`	`true`
`int/number`	`999`
`date`	`2022-01-16T15:16:36+00:00`
`other`	`parameter_name value`

Projets de jetons ERC-1155

La norme ERC-1155 comprend des méthodes communes pour les jetons fongibles et non fongibles. La collection Postman générée pour un projet ERC-1155 qui utilise à la fois des jetons fongibles et non fongibles comprend deux demandes POST différentes, une pour chaque type de jeton, pour ces méthodes courantes. Si un projet ERC-1155 utilise uniquement des jetons fongibles ou non, mais pas les deux types, la collection Postman générée inclut une seule demande POST pour ces méthodes communes. Le tableau suivant illustre l'API générée pour la méthode AddRole.

Elément de demande Jetons fongibles Jetons non fongibles

Nom de la demande AddRole -For Fungible AddRole -For NonFungible

Corps de demande

Elément de demande	Jetons fongibles	Jetons non fongibles
Nom de la demande	`AddRole -For Fungible`	`AddRole -For NonFungible`
Corps de demande	`{ "chaincode": "{{bc-chaincode-name}}", "args": [ "AddRole", "{{bc-org-id}}", "{{bc-user-id}}", "role value (for example, minter / burner)", "{\"TokenId\":\"{{bc-token-id}}\"}" ], "timeout": {{bc-timeout}}, "sync": {{bc-sync}} }`	`{ "chaincode": "{{bc-chaincode-name}}", "args": [ "AddRole", "{{bc-org-id}}", "{{bc-user-id}}", "role value (for example, minter / burner)", "{\"TokenName\":\"TokenName value\"}" ], "timeout": {{bc-timeout}}, "sync": {{bc-sync}} }`

{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "AddRole",
        "{{bc-org-id}}",
        "{{bc-user-id}}",
        "role value (for example, minter / burner)",
        "{\"TokenId\":\"{{bc-token-id}}\"}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}

{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "AddRole",
        "{{bc-org-id}}",
        "{{bc-user-id}}",
        "role value (for example, minter / burner)",
        "{\"TokenName\":\"TokenName value\"}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}