Verbesserungen für Postman Collections

Die Oracle Blockchain Platform Digital Assets Edition bietet Unterstützung für Bestätigungsparameter, vertrauliche Chaincodes und OAuth 2.0 zu den Postman-Sammlungen, die von Blockchain App Builder generiert werden.

Mit Blockchain App Builder können Sie eine Postman-Sammlung erstellen, die Beispiel-Payloads für alle Chaincode-Controller-APIs enthält. Weitere Informationen finden Sie unter Postman-Sammlung mit der CLI generieren und Postman-Sammlung mit Visual Studio-Code generieren.

Oracle Blockchain Platform Digital Assets Edition erweitert diese Funktionalität, indem ein zusätzlicher Parameter in die Anforderungs-Payload für alle Setter-Methoden aufgenommen wird. Bei generischem Chaincode (im Gegensatz zum vertraulichen Modus) lautet der Parameter entweder endorsers oder sameOrgEndorser. Der Parameter sameOrgEndorser, wenn true, gibt an, dass Transaktionsbestätigungen von derselben Organisation wie der Anforderer stammen müssen. Der Parameter endorsers gibt eine Liste von Peers an, die die Transaktion freigeben müssen.

Der Parameter sameOrgEndorserOptionInWrapperAPI in der Datei .ochain.json im Chaincode gibt an, für welche APIs ein sameOrgEndorser-Wert erforderlich ist. Für APIs, die mit dem Parameter sameOrgEndorserOptionInWrapperAPI verknüpft sind, ist der Parameter sameOrgEndorser in ihren Payloads auf true gesetzt. Alle anderen APIs enthalten den Parameter endorsers anstelle des Parameters sameOrgEndorser.

Das folgende Snippet zeigt den Parameter sameOrgEndorserOptionInWrapperAPI in der Datei .ochain.json im CBDC-Großhandelskettencodepackage.

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

Sie können diesen Parameter nach Bedarf anpassen. Wenn die Wrapper-API generiert wird, wird für die angegebenen APIs der Parameter sameOrgEndorser in den Payloads auf true gesetzt.

Die folgenden Beispiel-Payloads zeigen diese Freigabeparameter.

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
}

Confidential Chaincode-Support

Im vertraulichen Modus generierte Chaincodes verarbeiten Parameter anders als im generischen Modus. In vertraulichen Chaincodes werden API-Argumente über eine transiente Zuordnung in der Anforderungs-Payload übergeben. Dadurch wird sichergestellt, dass Argumente vertraulich bleiben und nicht in Logs angegeben werden. Weitere Informationen zum vertraulichen Chaincode finden Sie unter Überblick über vertrauliche Zahlungen.

Alle Getter-Methoden umfassen einen Parameter peer (nicht im generischen Modus-Chaincode vorhanden).

Alle Setter-Methoden umfassen den Parameter endorsers, der eine Liste von Peers angibt, die die Transaktion freigeben müssen. Der Parameter sameOrgEndorserOptionInWrapperAPI in der Datei .ochain.json ist auf ein leeres Array gesetzt:

"sameOrgEndorserOptionInWrapperAPI": []

Für Setter-Methoden ist ein Confidential-Transaction-Header erforderlich, der angibt, dass der für vertrauliche Transaktionen erforderliche Blinding-Faktor von der Oracle Blockchain Platform-Instanz abgerufen wird. Dieser Header ist in Postman-Anforderungen für vertrauliche Transaktionen erforderlich.

Um die Sicherheit des Chaincodes im vertraulichen Modus aufrechtzuerhalten, übergeben Sie Argumente in einem transientMap-Objekt. Sie können Argumente direkt im Parameter args in der transienten Zuordnung übergeben, wie im folgenden Beispiel für die Methode activateAccount gezeigt:

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

Nur für die Postman-Collection der Wrapper-API (nicht für die generische Postman-Collection) können Sie auch das Flag transientMapArgsFlag verwenden, das, wenn es auf true gesetzt ist, automatisch alle Argumente an die transiente Map übergibt, wie im folgenden Beispiel für die Methode activateAccount gezeigt:

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

Im folgenden Beispiel für Postman-Anforderungen werden diese Parameter und Header angezeigt.

createAccount (Setter-Methode)

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 (getter-Methode)

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

Unterstützung für OAuth 2.0

Standardmäßig sind die Postman-Collections, die von Blockchain App Builder generiert werden, für die Autorisierung OAuth 2.0 konfiguriert. Sie müssen die folgenden Werte in den globalen Variablen der Postman-Collection angeben, um OAuth 2.0 zu aktivieren.

client-id: Die Client-ID der Oracle Blockchain Platform-Instanz.
client-secret: Das Client Secret der Oracle Blockchain Platform-Instanz.
access-token-url: Die Zugriffstoken-URL enthält die Domain-URL der Oracle Blockchain Platform-Instanz im folgenden Format: https://<domain-URL>/oauth2/v1/token

Gehen Sie folgendermaßen vor, um die Client-ID, das Client Secret und die Domain-URL für eine Oracle Blockchain Platform-Instanz abzurufen:

melden Sie sich bei Ihrem Oracle Cloud Infrastructure-(OCI-)Account an. Wählen Sie das Compartment mit der Oracle Blockchain Platform-Instanz aus.
Klicken Sie in der Konsole auf das Menü Navigation und dann auf Identität & Sicherheit.
Wählen Sie unter Identität die Option Domains aus.
Klicken Sie auf der Seite Domains auf Oracle Identity Cloud Service.
Wählen Sie im Navigationsmenü von Oracle Identity Cloud Service die Option Oracle Cloud Services aus. Suchen Sie die Oracle Blockchain Platform-Instanz, und öffnen Sie die Detailseite dieser Instanz.
Die angezeigte Standardseite ist die Seite OAuth-Konfiguration. Die Felder "Client-ID" und "Client Secret" befinden sich im Abschnitt "Allgemeine Informationen".
Navigieren Sie zurück zur Seite Domains, und klicken Sie auf die Domain, die von Ihrer Oracle Blockchain Platform-Instanz verwendet wird.
Die Domain-URL wird in den Domaindetails angezeigt.

Diese globalen Variablen werden in einem Pre-Request-Skript verwendet, um einen access_token-Platzhalter zu generieren. Das Skript generiert ein Token für den Benutzer bc-admin, sodass jede Anforderung mit der Autorisierung bc-admin ausgeführt wird.

Die erste Anforderung generiert ein bc-admin-Token mit den angegebenen Zugangsdaten. Das Token und der Ablaufwert sind Speicher in Postman-Sammlungsvariablen. Fehlende oder abgelaufene Token werden automatisch neu generiert. Wenn sich die Client-ID oder das Client Secret ändert, erkennt das Skript die Änderung automatisch, invalidiert das vorherige Token und generiert ein Token mit aktualisierten Zugangsdaten. Wenn Sie den Wert access_token manuell ändern, kann dies dazu führen, dass Anforderungen nicht erfolgreich sind. Wenn Sie den Wert access_token löschen, generiert das Skript automatisch ein weiteres bc-admin-Token.

Mit der Anforderung Zugriffstoken für Benutzer generieren in der Postman-Collection können Sie ein anderes Token als das standardmäßige bc-admin-Token generieren und verwenden. Gehen Sie folgendermaßen vor, um ein benutzerdefiniertes Zugriffstoken zu generieren.

Öffnen Sie die Anforderung Zugriffstoken für Benutzer generieren. Standardmäßig sind die Werte username und password auf bc-admin gesetzt.
Aktualisieren Sie die Werte username und password in den Collection-Variablen.
Klicken Sie auf Neues Zugriffstoken generieren. Das Fenster Zugriffstoken verwalten wird geöffnet.
Aktualisieren Sie den Standardnamen, prüfen Sie die anderen Details, und klicken Sie auf Speichern. Das Token ist jetzt zur Verwendung verfügbar und wird im Abschnitt Verfügbare Token auf der Seite Autorisierung angezeigt.

Generierte Postman-Collections enthalten Variablen, die für die Unterstützung von OAuth 2.0 erforderlich sind, wie in der folgenden Tabelle dargestellt.

Variable	Beschreibung	Standardwert
`client-id`	Client-ID der Oracle Blockchain Platform-Instanz.	Wert `client-id`
`client-secret`	Client Secret der Oracle Blockchain Platform-Instanz.	`client-secret`-Wert
`access-token-url`	Tokenendpunkt OAuth 2.0 der Domain der Oracle Blockchain Platform-Instanz.	`access-token-url`-Wert
`access_token`	OAuth 2.0-Zugriffstoken, das für den `bc-admin`- oder benutzerdefinierten Benutzer generiert wurde.	Ursprünglich nicht verfügbar; von Skript verwaltet
`access_token_expiry`	Ablaufzeit des generierten Zugriffstokens.	Ursprünglich nicht verfügbar; von Skript verwaltet
`admin_credentials_hash`	Hashwert der Zugangsdaten, die für die Tokenvalidierung und -neugenerierung verwendet werden.	Ursprünglich nicht verfügbar; von Skript verwaltet