Améliorations apportées aux collections Postman

L'édition Digital Assets d'Oracle Blockchain Platform ajoute la prise en charge des paramètres d'endossement, des codes de chaîne confidentiels et de OAuth 2.0 aux collections Postman générées par Blockchain App Builder.

Blockchain App Builder vous permet de 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. Pour plus d'informations, voir Générer une collection Postman à l'aide de l'interface de ligne de commande et Générer une collection Postman à l'aide de Visual Studio Code.

Digital Assets Edition d'Oracle Blockchain Platform étend cette fonctionnalité en incluant un paramètre supplémentaire dans les données utiles de la demande pour toutes les méthodes de réglage. Pour le code de chaîne générique (par opposition au mode confidentiel), le paramètre est endorsers ou sameOrgEndorser. Le paramètre sameOrgEndorser, si true, indique que les endossements de transaction doivent provenir de la même organisation que le demandeur. Le paramètre endorsers spécifie une liste de pairs qui doivent endosser la transaction.

Le paramètre sameOrgEndorserOptionInWrapperAPI dans le fichier .ochain.json du code de chaîne spécifie les API qui nécessitent une valeur sameOrgEndorser. Les API associées au paramètre sameOrgEndorserOptionInWrapperAPI ont le paramètre sameOrgEndorser réglé à true dans leurs données utiles. Toutes les autres API incluent le paramètre endorsers au lieu du paramètre sameOrgEndorser.

L'extrait de code suivant présente le paramètre sameOrgEndorserOptionInWrapperAPI dans le fichier .ochain.json de l'ensemble de chaîne de code CBDC de gros.

"sameOrgEndorserOptionInWrapperAPI": ["addConversionRate","addTokenAdmin","addTokenAuditor","approveBurn","approveMint","burnTokens","createExchangePoolAccounts","deleteHistoricalTransactions","initializeCBDCToken","initializeExchangePoolUser","issueTokens","mintWithFundingExchangePool","rejectBurn","rejectMint","removeTokenAdmin","removeTokenAuditor","requestBurn","requestMint","updateCBDCToken","updateConversionRate"]

Vous pouvez personnaliser ce paramètre au besoin. Lorsque l'API d'encapsulation est générée, le paramètre sameOrgEndorser est réglé à true dans les données utiles des API spécifiées.

Les exemples de données utiles suivants montrent ces paramètres d'endossement.

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
}

Prise en charge du code de chaîne confidentiel

Les codes de chaîne générés en mode confidentiel gèrent les paramètres différemment du mode générique. Dans les codes de chaîne confidentiels, les arguments d'API sont transmis à l'aide d'une carte transitoire dans les données utiles de la demande. Cela garantit que les arguments restent confidentiels et ne sont pas exposés dans les journaux. Pour plus d'informations sur le code de chaîne confidentiel, voir Aperçu des paiements confidentiels.

Toutes les méthodes get incluent un paramètre peer (non présent dans le code de chaîne de mode générique).

Toutes les méthodes de réglage incluent le paramètre endorsers, qui spécifie une liste de pairs qui doivent endosser la transaction. Le paramètre sameOrgEndorserOptionInWrapperAPI dans le fichier .ochain.json est réglé à un tableau vide :

"sameOrgEndorserOptionInWrapperAPI": []

Les méthodes Setter nécessitent un en-tête Confidential-Transaction, qui indique que le facteur d'aveuglement requis pour les transactions confidentielles est extrait de l'instance Oracle Blockchain Platform. Cet en-tête est requis dans les demandes Postman pour les transactions confidentielles.

Pour assurer la sécurité du code de chaîne en mode confidentiel, transmettez des arguments dans un objet transientMap. Vous pouvez transmettre des arguments directement dans le paramètre args dans le mappage transitoire, comme illustré dans l'exemple suivant pour la méthode activateAccount :

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

Pour la collection Postman d'API d'encapsuleur uniquement (et non la collection Postman générique), vous pouvez également utiliser l'indicateur transientMapArgsFlag, qui, s'il est réglé à true, transmet automatiquement tous les arguments à la carte transitoire, comme illustré dans l'exemple suivant pour la méthode activateAccount :

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

Les exemples de demandes Postman suivants montrent ces paramètres et en-têtes.

createAccount (méthode de saisie)

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éthode 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\"]"
    }
}'

OAuth 2.0 Soutien

Par défaut, les collections Postman générées par Blockchain App Builder sont configurées pour l'autorisation OAuth 2.0. Vous devez fournir les valeurs suivantes dans les variables globales de la collection Postman pour activer OAuth 2.0.

client-id: ID client de l'instance Oracle Blockchain Platform.
client-secret: Clé secrète client de l'instance Oracle Blockchain Platform.
access-token-url: L'URL du jeton d'accès contient l'URL du domaine de l'instance Oracle Blockchain Platform, dans le format suivant : https://<domain-URL>/oauth2/v1/token

Effectuez les étapes suivantes pour extraire l'ID client, la clé secrète client et l'URL du domaine pour une instance Oracle Blockchain Platform :

Connectez-vous à votre compte Oracle Cloud Infrastructure (OCI). Sélectionnez le compartiment contenant l'instance Oracle Blockchain Platform.
Dans la console, cliquez sur le menu Navigation, puis sur Identité et sécurité.
Sous Identité, sélectionnez Domaines.
Dans la page Domaines, cliquez sur Oracle Identity Cloud Service.
Dans le menu de navigation d'Oracle Identity Cloud Service, sélectionnez Oracle Cloud Services. Localisez votre instance Oracle Blockchain Platform et ouvrez la page de détails de cette instance.
La page par défaut affichée est la page Configuration OAuth. Les champs ID client et Clé secrète client se trouvent dans la section Informations générales.
Revenez à la page Domaines, puis cliquez sur le domaine utilisé par votre instance Oracle Blockchain Platform.
L'URL du domaine est affichée dans les détails du domaine.

Ces variables globales sont utilisées dans un script de pré-demande pour générer un paramètre fictif access_token. Le script génère un jeton pour l'utilisateur bc-admin, de sorte que chaque demande s'exécute avec l'autorisation bc-admin.

La première demande génère un jeton bc-admin à l'aide des données d'identification spécifiées. Le jeton et la valeur d'expiration sont stockés dans les variables de collecte Postman. Les jetons manquants ou expirés sont automatiquement régénérés. Si l'ID client ou la clé secrète client change, le script détecte automatiquement la modification, invalide le jeton précédent et génère un jeton avec des données d'identification mises à jour. Si vous modifiez manuellement la valeur access_token, cela peut entraîner l'échec des demandes. Si vous effacez la valeur access_token, le script génère un autre jeton bc-admin automatiquement.

Vous pouvez utiliser la demande Générer un jeton d'accès pour l'utilisateur dans la collection Postman pour générer et utiliser un jeton autre que le jeton bc-admin par défaut. Pour générer un jeton d'accès personnalisé, procédez comme suit.

Ouvrez la demande Générer un jeton d'accès pour l'utilisateur. Par défaut, les valeurs username et password sont réglées à bc-admin.
Mettez à jour les valeurs username et password dans les variables de collection.
Cliquez sur Générer un nouveau jeton d'accès. La fenêtre Gérer les jetons d'accès s'ouvre.
Mettez à jour le nom par défaut, vérifiez les autres détails, puis cliquez sur Enregistrer. Le jeton est maintenant disponible pour utilisation et affiché dans la section Jetons disponibles de la page Autorisation.

Les collections Postman générées incluent les variables requises pour la prise en charge de OAuth 2.0, comme indiqué dans le tableau suivant.

Variable	Description	Valeur par défaut
`client-id`	ID client de l'instance Oracle Blockchain Platform.	Valeur `client-id`
`client-secret`	Clé secrète client de l'instance Oracle Blockchain Platform.	Valeur `client-secret`
`access-token-url`	Point d'extrémité de jeton OAuth 2.0 du domaine de l'instance Oracle Blockchain Platform.	Valeur `access-token-url`
`access_token`	OAuth Jeton d'accès 2.0 généré pour l'utilisateur `bc-admin` ou personnalisé.	Non disponible initialement; géré par un script
`access_token_expiry`	Heure d'expiration du jeton d'accès généré.	Non disponible initialement; géré par un script
`admin_credentials_hash`	Valeur de hachage des données d'identification utilisées pour la validation et la régénération des jetons.	Non disponible initialement; géré par un script