Gerar uma Coleção Postman Usando o Visual Studio Code

Você pode criar uma coleção Postman que inclua payloads de exemplo para todas as APIs do controlador chaincode.

Postman é uma ferramenta que você pode usar para trabalhar e testar APIs REST. O comando generate cria uma coleção Postman que é baseada no chaincode que foi gerado automaticamente a partir de um arquivo de especificação declarativa. A coleção Postman contém as cargas úteis para todos os métodos que são especificados no arquivo controlador chaincode. Você pode alterar os valores das variáveis no arquivo de coleta Postman para fazer chamadas de API REST.

A coleção Postman gerada inclui valores padrão para todas as APIs no controlador. Para saber mais sobre o Postman, consulte https://www.postman.com/. Depois de gerar uma coleção Postman, você pode importá-la diretamente e usá-la alterando os valores padrão no payload e nas variáveis.

Para gerar uma coleção Postman para um projeto chaincode no Visual Studio Code, execute as etapas a seguir.

  1. Selecione o projeto chaincode no painel Chaincodes.
  2. Clique com o botão direito do mouse no nome do chaincode e selecione Gerar Coleção de Postman.
  3. Selecione um local para salvar a coleção Postman e clique em Selecionar Pasta de Saída.

Se a coleção Postman especificada já existir, será solicitado que você a substitua.

Estrutura de Cobrança do Postman

A coleção Postman gerada inclui dois tipos de solicitações, solicitações de chamada e solicitações de consulta:
  • As solicitações de chamada incluem todas as operações de gravação, que usam o ponto final /transactions
  • As solicitações de consulta incluem todas as operações get, que usam o ponto final /chaincode-queries

Para diferenciar entre os métodos getter e non-getter nas APIs do controlador, um decorador é usado em TypeScript chaincodes e um comentário é usado em Go chaincodes. Se você definir um método getter no controlador, deverá usar o decorador GetMethod para TypeScript ou o comentário GetMethod para Go, conforme mostrado na tabela a seguir.

TypeScript Ir
Cada método getter tem um decorador GetMethod:
@GetMethod()
@Validator()
public async getAllTokenAdmins() {
  await this.Ctx.ERC1155Auth.checkAuthorization("ERC1155ADMIN.getAllAdmins", "TOKEN");
  return await this.Ctx.ERC1155Admin.getAllAdmins();
}
 Cada método getter tem um bloco de comentários 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()
}

As coleções Postman geradas incluem variáveis com valores padrão, conforme mostrado na tabela a seguir.

Nome da Variável Descrição Valor padrão Contexto
bc-url O URL do proxy REST da instância do Oracle Blockchain Platform na qual o chaincode é implantado https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy todos os chaincodes
bc-channel O canal em que o chaincode é implantado default todos os chaincodes
bc-admin-user O nome do administrador (um usuário com a atribuição admin que pode acessar todas as solicitações POST). Por padrão, este usuário é o chamador de todas as solicitações POST no chaincode bc-admin-user value todos os chaincodes
bc-admin-password A senha do usuário administrador bc-admin-password value todos os chaincodes
bc-timeout O valor de timeout no corpo de cada solicitação POST para indicar o intervalo de timeout 6000 todos os chaincodes
bc-sync O valor de sincronização no corpo de cada solicitação POST para indicar se a solicitação é síncrona ou assíncrona true todos os chaincodes
bc-chaincode-name O nome do chaincode, que é usado em todas as solicitações POST chaincode name todos os chaincodes
bc-org-id O parâmetro orgId padrão para todas as solicitações POST bc-org-id value somente códigos de cadeia de token
bc-user-id O parâmetro userId padrão para todas as solicitações POST bc-user-id value somente códigos de cadeia de token
bc-token-id O parâmetro tokenId padrão para todas as solicitações POST bc-token-id value somente códigos de cadeia de token

Em cada solicitação gerada, todos os parâmetros com valores padrão são gerados. As funções que possuem parâmetros de estrutura/classe terão um objeto de espaço reservado no corpo da solicitação, conforme mostrado nos exemplos a seguir.

API com um parâmetro 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 sem um parâmetro struct/class 
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "CreateAccount",
        "{{bc-org-id}}",
        "example_minter",
        "true",
        "true"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}}
}

O valor padrão para a maioria dos parâmetros de API é parameter_name value, com algumas exceções. Os exemplos a seguir mostram algumas das exceções.

  • O parâmetro de filtros em GetAccountTransactionHistoryWithFilters: 
    "{\"PageSize\":20,\"Bookmark\":\"\",\"StartTime\":\"2022-01-16T15:16:36+00:00\",\"EndTime\":\"2022-01-17T15:16:36+00:00\"}"
  • O parâmetro de filtros em GetSubTransactionsByIdWithFilters:
    "{\"PageSize\":20,\"Bookmark\":\"\}"

Uma estrutura ou classe tem valores padrão diferentes, conforme mostrado na tabela a seguir:

Tipo de Dados Valor padrão
boolean/bool true
int/number 999
date 2022-01-16T15:16:36+00:00
other parameter_name value

ERC-1155 - Projetos de Token

O padrão ERC-1155 inclui métodos comuns para tokens fungíveis e não fungíveis. A coleção postman gerada para um projeto ERC-1155 que usa tokens fungíveis e não fungíveis inclui duas solicitações POST diferentes, uma para cada tipo de token, para esses métodos comuns. Se um projeto ERC-1155 usar apenas tokens fungíveis ou não fungíveis, mas não ambos os tipos, a coleção Postman gerada incluirá apenas uma solicitação POST para esses métodos comuns. A tabela a seguir ilustra a API gerada para o método AddRole.
Elemento de Solicitação Tokens Fungíveis Tokens Não Fungíveis
Nome da Solicitação AddRole -For Fungible AddRole -For NonFungible
Corpo da Solicitação 
{
    "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}}
}