Générer une collection Postman à l'aide de Visual Studio Code

Vous pouvez créer une collection Postman qui inclut des exemples de données utiles pour toutes vos API de contrôleur de code de chaîne.

Postman est un outil que vous pouvez utiliser pour travailler avec et tester des API REST. La commande generate crée une collection Postman basée sur le code de chaîne généré automatiquement à partir d'un fichier de spécification déclarative. La collection Postman contient les données utiles pour toutes les méthodes spécifiées dans le fichier de contrôleur de chaîne. Vous pouvez modifier les valeurs de variable dans le fichier de collection 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 à propos de Postman, consultez 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 les données utiles et les variables.

Pour générer une collection Postman pour un projet de code de chaîne dans Visual Studio Code, procédez comme suit.

  1. Sélectionnez le projet de code de chaîne dans le volet Codes de chaîne.
  2. Cliquez avec le bouton droit de la souris sur le nom du code de chaîne, puis sélectionnez Générer une collecte Postman.
  3. Sélectionnez un emplacement dans lequel enregistrer la collection Postman, puis cliquez sur Sélectionner un dossier de sortie.

Si la collection Postman spécifiée existe déjà, vous êtes invité à la remplacer.

Structure de collecte Postman

La collection Postman générée comprend deux types de demande, les demandes d'appel et les demandes d'interrogation :
  • Les demandes d'appel incluent toutes les opérations d'écriture, qui utilisent le point d'extrémité /transactions
  • Les demandes d'interrogation incluent toutes les opérations d'obtention, qui utilisent le point d'extrémité /chaincode-queries

Pour distinguer entre les méthodes getter et nongetter dans les API de contrôleur, un décorateur est utilisé dans les codes de chaîne TypeScript et un commentaire est utilisé dans les codes de chaîne Go. Si vous définissez une méthode getter 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
Chaque méthode getter a 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 getter comporte 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 mandataire REST de l'instance Oracle Blockchain Platform où le code de chaîne est déployé https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy tous les codes de chaîne
bc-channel Canal dans lequel le code de chaîne est déployé default tous les codes de chaîne
bc-admin-user Nom de l'administrateur (utilisateur doté du rôle admin qui peut accéder à toutes les demandes POST). Par défaut, cet utilisateur est l'appelant de toutes les demandes POST dans le code de chaîne bc-admin-user value tous les codes de chaîne
bc-admin-password Mot de passe de l'utilisateur administrateur bc-admin-password value tous les codes de chaîne
bc-timeout Valeur de temporisation dans le corps de chaque demande POST pour indiquer l'intervalle de temporisation 6000 tous les codes de 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 de chaîne
bc-chaincode-name Le nom du code de chaîne, qui est utilisé dans chaque demande POST chaincode name tous les codes de chaîne
bc-org-id Paramètre orgId par défaut pour toutes les demandes POST bc-org-id value codes de chaîne de jeton uniquement
bc-user-id Paramètre userId par défaut pour toutes les demandes POST bc-user-id value codes de chaîne de jeton uniquement
bc-token-id Paramètre tokenId par défaut pour toutes les demandes POST bc-token-id value codes de 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 de structure/classe auront un objet de paramètre fictif dans le corps de la demande, comme illustré dans les exemples suivants.

API avec un paramètre structure/classe 
{
    "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 structure/classe 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "CreateAccount",
        "{{bc-org-id}}",
        "example_minter",
        "true",
        "true"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}

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

  • 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\"}"
  • 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

ERC-1155 Projets de jeton

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 communes. Si un projet ERC-1155 utilise uniquement des jetons fongibles ou non fongibles, 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.
Élé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}}
}