Mejoras en Postman Collections

Oracle Blockchain Platform Digital Assets Edition agrega soporte para parámetros de endoso, códigos de cadena confidenciales y OAuth 2.0 a las recopilaciones Postman generadas por Blockchain App Builder.

Blockchain App Builder le permite crear una recopilación de Postman que incluye cargas útiles de ejemplo para todas sus API de controlador de código de cadenas. Para obtener más información, consulte Generar una recopilación Postman con la CLI y Generar una recopilación Postman con Visual Studio Code.

Oracle Blockchain Platform Digital Assets Edition amplía esa funcionalidad mediante la inclusión de un parámetro adicional en la carga útil de solicitud para todos los métodos setter. Para el código de cadena genérico (en lugar del modo confidencial), el parámetro es endorsers o sameOrgEndorser. El parámetro sameOrgEndorser, si es true, indica que los endosos de transacción deben ser de la misma organización que el solicitante. El parámetro endorsers especifica una lista de iguales que deben respaldar la transacción.

El parámetro sameOrgEndorserOptionInWrapperAPI del archivo .ochain.json en el código de cadena especifica qué API necesitan un valor sameOrgEndorser. Las API que están asociadas al parámetro sameOrgEndorserOptionInWrapperAPI tienen el parámetro sameOrgEndorser definido en true en sus cargas útiles. Todas las demás API incluyen el parámetro endorsers en lugar del parámetro sameOrgEndorser.

El siguiente fragmento muestra el parámetro sameOrgEndorserOptionInWrapperAPI en el archivo .ochain.json en el paquete de código de cadena CBDC al por mayor.
"sameOrgEndorserOptionInWrapperAPI": ["addConversionRate","addTokenAdmin","addTokenAuditor","approveBurn","approveMint","burnTokens","createExchangePoolAccounts","deleteHistoricalTransactions","initializeCBDCToken","initializeExchangePoolUser","issueTokens","mintWithFundingExchangePool","rejectBurn","rejectMint","removeTokenAdmin","removeTokenAuditor","requestBurn","requestMint","updateCBDCToken","updateConversionRate"]
Puede personalizar este parámetro según sea necesario. Cuando se genera la API de envoltorio, las API especificadas tendrán el parámetro sameOrgEndorser definido en true en sus cargas útiles.

En el siguiente ejemplo, las cargas útiles muestran estos parámetros de endoso.

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
}

Soporte de código de cadena confidencial

Los códigos de cadena generados en el modo confidencial manejan los parámetros de forma diferente al modo genérico. En los códigos de cadenas confidenciales, los argumentos de API se transfieren mediante una asignación transitoria en la carga útil de la solicitud. Esto garantiza que los argumentos sigan siendo confidenciales y no se expongan en los logs. Para obtener más información sobre el código de cadena confidencial, consulte Visión general de pagos confidenciales.

Todos los métodos getter incluyen un parámetro peer (no está presente en el código de cadena del modo genérico).

Todos los métodos setter incluyen el parámetro endorsers, que especifica una lista de iguales que deben respaldar la transacción. El parámetro sameOrgEndorserOptionInWrapperAPI del archivo .ochain.json se define en una matriz vacía:
"sameOrgEndorserOptionInWrapperAPI": []

Los métodos Setter requieren una cabecera Confidential-Transaction, que indica que el factor de cegamiento necesario para las transacciones confidenciales se recupera de la instancia de Oracle Blockchain Platform. Esta cabecera es necesaria en las solicitudes de Postman para transacciones confidenciales.

Para mantener la seguridad del código de cadena de modo confidencial, transfiera argumentos en un objeto transientMap. Puede transferir argumentos directamente en el parámetro args en la asignación transitoria, como se muestra en el siguiente ejemplo para el método activateAccount: 

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

Para la recopilación Postman de API de envoltorio solo (no para la recopilación Postman genérica), también puede utilizar el indicador transientMapArgsFlag, que si se define en true transfiere automáticamente todos los argumentos al mapa transitorio, como se muestra en el siguiente ejemplo para el método activateAccount: 

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

En el siguiente ejemplo, las solicitudes de Postman muestran estos parámetros y cabeceras.

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

Compatibilidad con OAuth 2.0

Por defecto, las recopilaciones de Postman generadas por Blockchain App Builder están configuradas para la autorización OAuth 2.0. Debe proporcionar los siguientes valores en las variables globales de la recopilación Postman para activar OAuth 2.0.

client-id
ID de cliente de la instancia de Oracle Blockchain Platform.
client-secret
Secreto de cliente de la instancia de Oracle Blockchain Platform.
access-token-url
La URL del token de acceso contiene la URL de dominio de la instancia de Oracle Blockchain Platform, con el siguiente formato: https://<domain-URL>/oauth2/v1/token

Complete los siguientes pasos para recuperar el ID de cliente, el secreto de cliente y la URL de dominio para una instancia de Oracle Blockchain Platform:

  1. Conéctese a su cuenta de Oracle Cloud Infrastructure (OCI). Seleccione el compartimento que contiene la instancia de Oracle Blockchain Platform.
  2. En la consola, haga clic en el menú Navegación y, a continuación, en Identidad y seguridad.
  3. En Identidad, seleccione Dominios.
  4. En la página Dominios, haga clic en Oracle Identity Cloud Service.
  5. En el menú de navegación de Oracle Identity Cloud Service, seleccione Oracle Cloud Services. Localice su instancia de Oracle Blockchain Platform y abra la página de detalles de esa instancia.
  6. La página por defecto que se muestra es la página OAuth Configuration. Los campos ID de cliente y Secreto de cliente se encuentran en la sección Información general.
  7. Vuelva a la página Dominios y, a continuación, haga clic en el dominio que utiliza la instancia de Oracle Blockchain Platform.
  8. La URL de dominio se muestra en los detalles del dominio.

Estas variables globales se utilizan en un script de solicitud previa para generar un marcador de posición access_token. El script genera un token para el usuario bc-admin, de modo que cada solicitud se ejecuta con autorización bc-admin.

La primera solicitud genera un token bc-admin con las credenciales especificadas. El token y el valor de caducidad son almacenes en las variables de recopilación de Postman. Los tokens que faltan o caducados se regeneran automáticamente. Si cambia el ID de cliente o el secreto de cliente, el script detecta automáticamente el cambio, invalida el token anterior y genera un token con credenciales actualizadas. Si modifica el valor access_token manualmente, puede provocar que las solicitudes fallen. Si borra el valor access_token, el script genera otro token bc-admin automáticamente.

Puede utilizar la solicitud Generar token de acceso para usuario en la recopilación Postman para generar y utilizar un token que no sea el token bc-admin por defecto. Para generar un token de acceso personalizado, complete los pasos siguientes.

  1. Abra la solicitud Generar token de acceso para usuario. Por defecto, los valores username y password se definen en bc-admin.
  2. Actualice los valores username y password en las variables de recopilación.
  3. Haga clic en Generar Nuevo Token de Acceso. Se abre la ventana Gestionar tokens de acceso.
  4. Actualice el nombre por defecto, revise los demás detalles y, a continuación, haga clic en Guardar. El token ahora está disponible para su uso y se muestra en la sección Tokens disponibles de la página Autorización.

Las recopilaciones generadas de Postman incluyen variables necesarias para el soporte de OAuth 2.0, como se muestra en la siguiente tabla.

Variable Descripción Valor por defecto
client-id ID de cliente de la instancia de Oracle Blockchain Platform. Valor client-id
client-secret Secreto de cliente de la instancia de Oracle Blockchain Platform. Valor client-secret
access-token-url Punto final de token OAuth 2.0 del dominio de la instancia de Oracle Blockchain Platform. Valor de access-token-url
access_token Token de acceso OAuth 2.0 generado para el usuario bc-admin o personalizado. No disponible inicialmente; gestionado por script
access_token_expiry Hora de caducidad del token de acceso generado. No disponible inicialmente; gestionado por script
admin_credentials_hash Valor hash de credenciales utilizadas para la validación y regeneración de tokens. No disponible inicialmente; gestionado por script