Miglioramenti alle raccolte postman

Oracle Blockchain Platform Digital Assets Edition aggiunge il supporto per i parametri di approvazione, i codici concatenati riservati e OAuth 2.0 alle raccolte Postman generate da Blockchain App Builder.

Blockchain App Builder ti consente di creare una raccolta Postman che include payload di esempio per tutte le API del controller di codice concatenato. Per ulteriori informazioni, vedere Generare una raccolta Postman utilizzando l'interfaccia CLI e Generare una raccolta Postman utilizzando Visual Studio Code.

Oracle Blockchain Platform Digital Assets Edition estende tale funzionalità includendo un parametro aggiuntivo nel payload della richiesta per tutti i metodi setter. Per il codice concatenato generico (anziché in modalità riservata), il parametro è endorsers o sameOrgEndorser. Il parametro sameOrgEndorser, se impostato su true, indica che le dichiarazioni a sostegno delle transazioni devono provenire dalla stessa organizzazione del richiedente. Il parametro endorsers specifica un elenco di peer che devono approvare la transazione.

Il parametro sameOrgEndorserOptionInWrapperAPI nel file .ochain.json nel codice concatenato specifica quali API richiedono un valore sameOrgEndorser. Le API associate al parametro sameOrgEndorserOptionInWrapperAPI hanno il parametro sameOrgEndorser impostato su true nei relativi payload. Tutte le altre API includono il parametro endorsers anziché il parametro sameOrgEndorser.

Lo snippet riportato di seguito mostra il parametro sameOrgEndorserOptionInWrapperAPI nel file .ochain.json nel package di codici concatenati CBDC all'ingrosso.
"sameOrgEndorserOptionInWrapperAPI": ["addConversionRate","addTokenAdmin","addTokenAuditor","approveBurn","approveMint","burnTokens","createExchangePoolAccounts","deleteHistoricalTransactions","initializeCBDCToken","initializeExchangePoolUser","issueTokens","mintWithFundingExchangePool","rejectBurn","rejectMint","removeTokenAdmin","removeTokenAuditor","requestBurn","requestMint","updateCBDCToken","updateConversionRate"]
È possibile personalizzare questo parametro in base alle esigenze. Quando viene generata l'API wrapper, il parametro sameOrgEndorser delle API specificate verrà impostato su true nei relativi payload.

I payload di esempio riportati di seguito mostrano questi parametri di approvazione.

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
}

Supporto Chaincode riservato

I codici concatenati generati in modalità riservata gestiscono i parametri in modo diverso dalla modalità generica. Nei codici concatenati riservati, gli argomenti API vengono passati utilizzando una mappa transitoria nel payload della richiesta. Ciò garantisce che gli argomenti rimangano riservati e non vengano esposti nei log. Per ulteriori informazioni sul codice concatenato riservato, vedere Panoramica sui pagamenti riservati.

Tutti i metodi getter includono un parametro peer (non presente nel codice concatenato in modalità generica).

Tutti i metodi setter includono il parametro endorsers, che specifica un elenco di peer che devono approvare la transazione. Il parametro sameOrgEndorserOptionInWrapperAPI nel file .ochain.json è impostato su un array vuoto:
"sameOrgEndorserOptionInWrapperAPI": []

I metodi Setter richiedono un'intestazione Confidential-Transaction, che indica che il fattore di associazione richiesto per le transazioni riservate viene recuperato dall'istanza di Oracle Blockchain Platform. Questa intestazione è obbligatoria nelle richieste postman per le transazioni riservate.

Per mantenere la sicurezza del codice concatenato in modalità riservata, passare gli argomenti in un oggetto transientMap. È possibile passare gli argomenti direttamente nel parametro args nella mappa transitoria, come mostrato nell'esempio seguente per il metodo activateAccount: 

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

Solo per la raccolta Postman API wrapper (non per la raccolta Postman generica), è inoltre possibile utilizzare il flag transientMapArgsFlag, che se impostato su true passa automaticamente tutti gli argomenti alla mappa transitoria, come mostrato nell'esempio seguente per il metodo activateAccount: 

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

Nell'esempio seguente le richieste Postman mostrano questi parametri e queste intestazioni.

createAccount (metodo set) 
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 (metodo 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\"]"
    }
}'

Supporto OAuth 2.0

Per impostazione predefinita, le raccolte Postman generate da Blockchain App Builder sono configurate per l'autorizzazione OAuth 2.0. Per abilitare OAuth 2.0, è necessario fornire i seguenti valori nelle variabili globali della raccolta Postman.

client-id
ID client dell'istanza di Oracle Blockchain Platform.
client-secret
Il segreto client dell'istanza di Oracle Blockchain Platform.
access-token-url
L'URL del token di accesso contiene l'URL del dominio dell'istanza di Oracle Blockchain Platform nel seguente formato: https://<domain-URL>/oauth2/v1/token

Completare i passi riportati di seguito per recuperare l'ID client, il segreto client e l'URL del dominio per un'istanza di Oracle Blockchain Platform.

  1. Accedi al tuo account Oracle Cloud Infrastructure (OCI). Selezionare il compartimento che contiene l'istanza di Oracle Blockchain Platform.
  2. Nella console fare clic sul menu Navigazione, quindi fare clic su Identità e sicurezza.
  3. In Identità selezionare Domini.
  4. Nella pagina Domini fare clic su Oracle Identity Cloud Service.
  5. Nel menu di navigazione di Oracle Identity Cloud Service selezionare Oracle Cloud Services. Individuare l'istanza di Oracle Blockchain Platform e aprire la pagina dei dettagli dell'istanza.
  6. La pagina predefinita visualizzata è la pagina OAuth Configuration. I campi ID client e Segreto client si trovano nella sezione Informazioni generali.
  7. Tornare alla pagina Domini, quindi fare clic sul dominio utilizzato dall'istanza di Oracle Blockchain Platform.
  8. L'URL del dominio viene visualizzato nei dettagli del dominio.

Queste variabili globali vengono utilizzate in uno script pre-richiesta per generare un segnaposto access_token. Lo script genera un token per l'utente bc-admin in modo che ogni richiesta venga eseguita con l'autorizzazione bc-admin.

La prima richiesta genera un token bc-admin utilizzando le credenziali specificate. Il token e il valore di scadenza sono memorizzati nelle variabili di raccolta Postman. I token mancanti o scaduti vengono rigenerati automaticamente. Se l'ID client o il segreto client cambia, lo script rileva automaticamente la modifica, invalida il token precedente e genera un token con credenziali aggiornate. Se si modifica manualmente il valore access_token, le richieste non riescono. Se si cancella il valore access_token, lo script genera automaticamente un altro token bc-admin.

È possibile utilizzare la richiesta Genera token di accesso per utente nella raccolta Postman per generare e utilizzare un token diverso dal token bc-admin predefinito. Per generare un token di accesso personalizzato, effettuare le operazioni riportate di seguito.

  1. Aprire la richiesta Genera token di accesso per utente. Per impostazione predefinita, i valori username e password sono impostati su bc-admin.
  2. Aggiornare i valori username e password nelle variabili di raccolta.
  3. Fare clic su Genera nuovo token di accesso. Viene visualizzata la finestra Gestisci token di accesso.
  4. Aggiornare il nome predefinito, rivedere gli altri dettagli, quindi fare clic su Salva. Il token è ora disponibile per l'uso e viene visualizzato nella sezione Token disponibili della pagina Autorizzazione.

Le raccolte Postman generate includono le variabili richieste per il supporto di OAuth 2.0, come mostrato nella tabella seguente.

Variabile Descrizione Valore predefinito
client-id ID client dell'istanza di Oracle Blockchain Platform. valore client-id
client-secret Segreto client dell'istanza di Oracle Blockchain Platform. valore client-secret
access-token-url Endpoint del token OAuth 2.0 del dominio dell'istanza di Oracle Blockchain Platform. valore access-token-url
access_token Token di accesso OAuth 2.0 generato per l'utente bc-admin o personalizzato. Non disponibile inizialmente; gestito da script
access_token_expiry Tempo di scadenza del token di accesso generato. Non disponibile inizialmente; gestito da script
admin_credentials_hash Valore hash delle credenziali utilizzate per la convalida e la rigenerazione del token. Non disponibile inizialmente; gestito da script