Aprimoramentos no Postman Collections

A Edição de Ativos Digitais do Oracle Blockchain Platform adiciona suporte para parâmetros de endosso, códigos de cadeia confidenciais e OAuth 2.0 às coleções Postman geradas pelo Blockchain App Builder.

O Blockchain App Builder permite que você crie uma coleção Postman que inclua payloads de exemplo para todas as APIs do controlador chaincode. Para obter mais informações, consulte Gerar uma Coleção Postman Usando a CLI e Gerar uma Coleção Postman Usando o Visual Studio Code.

A Edição de Ativos Digitais do Oracle Blockchain Platform estende essa funcionalidade incluindo um parâmetro adicional no payload da solicitação para todos os métodos setter. Para chaincode genérico (em oposição ao modo confidencial), o parâmetro é endorsers ou sameOrgEndorser. O parâmetro sameOrgEndorser, se true, indica que os endossos da transação devem ser da mesma organização que o solicitante. O parâmetro endorsers especifica uma lista de pares que devem endossar a transação.

O parâmetro sameOrgEndorserOptionInWrapperAPI no arquivo .ochain.json no chaincode especifica quais APIs exigem um valor sameOrgEndorser. As APIs associadas ao parâmetro sameOrgEndorserOptionInWrapperAPI têm o parâmetro sameOrgEndorser definido como true em seus payloads. Todas as outras APIs incluem o parâmetro endorsers, em vez do parâmetro sameOrgEndorser.

O trecho de código a seguir mostra o parâmetro sameOrgEndorserOptionInWrapperAPI no arquivo .ochain.json no pacote chaincode CBDC de atacado.
"sameOrgEndorserOptionInWrapperAPI": ["addConversionRate","addTokenAdmin","addTokenAuditor","approveBurn","approveMint","burnTokens","createExchangePoolAccounts","deleteHistoricalTransactions","initializeCBDCToken","initializeExchangePoolUser","issueTokens","mintWithFundingExchangePool","rejectBurn","rejectMint","removeTokenAdmin","removeTokenAuditor","requestBurn","requestMint","updateCBDCToken","updateConversionRate"]
Você pode personalizar esse parâmetro conforme necessário. Quando a API do wrapper for gerada, as APIs especificadas terão o parâmetro sameOrgEndorser definido como true em seus payloads.

Os payloads de exemplo a seguir mostram esses parâmetros de endosso.

addOrgAdmin
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "addOrgAdmin",
        "{{bc-org-id}}",
        "{{bc-user-id}}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}},
    "endorsers": {{endorsers}}
}
addTokenAdmin
{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "addTokenAdmin",
        "{{bc-org-id}}",
        "{{bc-user-id}}"
    ],
    "timeout": {{bc-timeout}},
    "sync": {{bc-sync}},
    "sameOrgEndorser": true
}

Suporte a Chaincode confidencial

Os códigos de cadeia gerados no modo confidencial manipulam parâmetros de forma diferente do modo genérico. Em chaincodes confidenciais, os argumentos da API são passados usando um mapa transitório no payload da solicitação. Isso garante que os argumentos permaneçam confidenciais e não sejam expostos em logs. Para obter mais informações sobre chaincode confidencial, consulte Visão Geral de Pagamentos Confidenciais.

Todos os métodos getter incluem um parâmetro peer (não presente no chaincode de modo genérico).

Todos os métodos setter incluem o parâmetro endorsers, que especifica uma lista de pares que devem endossar a transação. O parâmetro sameOrgEndorserOptionInWrapperAPI no arquivo .ochain.json é definido como um array vazio:
"sameOrgEndorserOptionInWrapperAPI": []

Os métodos do setter exigem um cabeçalho Confidential-Transaction, que indica que o fator de ocultação necessário para transações confidenciais é recuperado da instância do Oracle Blockchain Platform. Este cabeçalho é obrigatório nas solicitações Postman para transações confidenciais.

Para manter a segurança do chaincode de modo confidencial, informe argumentos em um objeto transientMap. Você pode informar argumentos diretamente no parâmetro args no mapa transitório, conforme mostrado no exemplo a seguir para o método activateAccount: 

"transientMap": { "args": "[\"account_id value\"]" }

Para a coleção Postman da API wrapper somente (não a coleção Postman genérica), você também pode usar o flag transientMapArgsFlag, que, se definido como true, passará automaticamente todos os argumentos para o mapa transitório, conforme mostrado no exemplo a seguir para o método activateAccount: 

{
   "accountId": "account_id value",
   "transientMapArgsFlag": true
}

Os exemplos de solicitações Postman a seguir mostram esses parâmetros e cabeçalhos.

createAccount (método setter) 
curl --location 'https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy/api/v2/channels/default/transactions' \
--header 'Content-Type: application/json' \
--header 'Confidential-Transaction: true' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "activateAccount"
    ],
    "timeout": 6000,
    "sync": true,
    "endorsers": ["org1-xyz-abc.blockchain.ocp.oraclecloud.com:20009", "org2-xyz-abc.blockchain.ocp.oraclecloud.com:20009"],
    "transientMap": {
        "args": "[\"account_id value\"]"
    }
}'
getAllActiveAccounts (método getter) 
curl --location 'https://test-xyz-abc.blockchain.ocp.oraclecloud.com:7443/restproxy/api/v2/channels/default/chaincode-queries' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
    "chaincode": "{{bc-chaincode-name}}",
    "args": [
        "getAllActiveAccounts"
    ],
    "timeout": 6000,
    "sync": true,
    "peer": "org-xyz-abc.blockchain.ocp.oraclecloud.com:20009",
    "transientMap": {
        "args": "[\"bc-org-id value\",\"bc-token-id value\"]"
    }
}'

Suporte ao OAuth 2.0

Por padrão, as coleções Postman geradas pelo Blockchain App Builder são configuradas para autorização do OAuth 2.0. Você deve fornecer os valores a seguir nas variáveis globais da coleção Postman para ativar o OAuth 2.0.

client-id
O ID do cliente da instância do Oracle Blockchain Platform.
client-secret
O segredo do cliente da instância do Oracle Blockchain Platform.
access-token-url
O URL do token de acesso contém o URL do domínio da instância do Oracle Blockchain Platform, no seguinte formato: https://<domain-URL>/oauth2/v1/token

Execute as seguintes etapas para recuperar o ID do cliente, o segredo do cliente e o URL do domínio de uma instância do Oracle Blockchain Platform:

  1. Acesse a sua conta do Oracle Cloud Infrastructure (OCI). Selecione o compartimento que contém a instância do Oracle Blockchain Platform.
  2. No console, clique no menu Navegação e, em seguida, clique em Identidade & Segurança.
  3. Em Identidade, selecione Domínios.
  4. Na página Domínios, clique em Oracle Identity Cloud Service.
  5. No menu de navegação do Oracle Identity Cloud Service, selecione Oracle Cloud Services. Localize sua instância do Oracle Blockchain Platform e abra a página de detalhes dessa instância.
  6. A página padrão exibida é a página OAuth Configuração. Os campos ID do Cliente e Segredo do Cliente estão na seção Informações Gerais.
  7. Navegue de volta para a página Domínios e clique no domínio usado pela sua instância do Oracle Blockchain Platform.
  8. O URL do domínio é exibido nos detalhes do domínio.

Essas variáveis globais são usadas em um script de pré-solicitação para gerar um placeholder access_token. O script gera um token para o usuário bc-admin, para que cada solicitação seja executada com autorização bc-admin.

A primeira solicitação gera um token bc-admin usando as credenciais especificadas. O token e o valor de expiração são armazenados em variáveis de coleta Postman. Os tokens ausentes ou expirados são gerados novamente automaticamente. Se o ID do cliente ou o segredo do cliente for alterado, o script detectará automaticamente a alteração, invalidará o token anterior e gerará um token com credenciais atualizadas. Se você modificar o valor access_token manualmente, isso poderá causar falha nas solicitações. Se você limpar o valor access_token, o script gerará outro token bc-admin automaticamente.

Você pode usar a solicitação Gerar Token de Acesso para Usuário na coleção Postman para gerar e usar um token diferente do token bc-admin padrão. Para gerar um token de acesso personalizado, execute as etapas a seguir.

  1. Abra a solicitação Gerar Token de Acesso para Usuário. Por padrão, os valores username e password são definidos como bc-admin.
  2. Atualize os valores username e password nas variáveis de coleta.
  3. Clique em Gerar Novo Token de Acesso. A janela Gerenciar Tokens de Acesso é aberta.
  4. Atualize o nome padrão, revise os outros detalhes e clique em Salvar. O token agora está disponível para uso e é mostrado na seção Tokens Disponíveis na página Autorização.

As coletas do Postman geradas incluem variáveis necessárias para o suporte ao OAuth 2.0, conforme mostrado na tabela a seguir.

Variável Descrição Valor padrão
client-id ID do Cliente da instância do Oracle Blockchain Platform. Valor client-id
client-secret Segredo do Cliente da instância do Oracle Blockchain Platform. Valor client-secret
access-token-url Ponto final do token do OAuth 2.0 do domínio da instância do Oracle Blockchain Platform. Valor access-token-url
access_token Token de acesso do OAuth 2.0 gerado para o usuário bc-admin ou personalizado. Não disponível inicialmente; gerenciado por script
access_token_expiry Tempo de expiração do token de acesso gerado. Não disponível inicialmente; gerenciado por script
admin_credentials_hash Valor de hash das credenciais usadas para validação e regeneração de token. Não disponível inicialmente; gerenciado por script