Postman Collections의 향상된 기능

Oracle Blockchain Platform Digital Assets Edition은 블록체인 앱 빌더가 생성한 Postman 컬렉션에 보증 매개변수, 기밀 체인코드 및 OAuth 2.0에 대한 지원을 추가합니다.

Blockchain App Builder를 사용하면 모든 체인코드 컨트롤러 API에 대한 예제 페이로드를 포함하는 Postman 모음을 생성할 수 있습니다. 자세한 내용은 CLI를 사용하여 Postman Collection 생성 및 Visual Studio 코드를 사용하여 Postman Collection 생성을 참조하십시오.

Oracle Blockchain Platform Digital Assets Edition은 모든 세터 메소드에 대한 요청 페이로드에 추가 매개변수를 포함하여 해당 기능을 확장합니다. 일반(기밀 모드와 반대) 체인 코드의 경우 매개변수는 endorsers 또는 sameOrgEndorser입니다. sameOrgEndorser 매개변수(true인 경우)는 트랜잭션 보증이 요청자와 동일한 조직에서 온 것임을 나타냅니다. endorsers 매개변수는 트랜잭션을 보증해야 하는 피어 목록을 지정합니다.

체인 코드의 .ochain.json 파일에 있는 sameOrgEndorserOptionInWrapperAPI 매개변수는 sameOrgEndorser 값이 필요한 API를 지정합니다. sameOrgEndorserOptionInWrapperAPI 매개변수와 연관된 API의 페이로드에는 sameOrgEndorser 매개변수가 true로 설정되어 있습니다. 다른 모든 API에는 sameOrgEndorser 매개변수 대신 endorsers 매개변수가 포함됩니다.

다음 코드 조각은 도매 CBDC 체인코드 패키지의 .ochain.json 파일에 있는 sameOrgEndorserOptionInWrapperAPI 매개변수를 보여줍니다.

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

필요에 따라 이 매개변수를 사용자 정의할 수 있습니다. 래퍼 API가 생성되면 지정된 API의 페이로드에서 sameOrgEndorser 매개변수가 true로 설정됩니다.

다음 예제 페이로드는 이러한 배서 매개변수를 보여줍니다.

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
}

기밀 체인코드 지원

기밀 모드에서 생성된 체인코드는 일반 모드와는 다르게 매개변수를 처리합니다. 기밀 체인 코드에서 API 인수는 요청 페이로드의 임시 맵을 사용하여 전달됩니다. 이렇게 하면 인수가 기밀로 유지되고 로그에 노출되지 않습니다. 기밀 체인 코드에 대한 자세한 내용은 기밀 지급 개요를 참조하십시오.

모든 getter 메소드에는 peer 매개변수(일반 모드 체인 코드에는 없음)가 포함됩니다.

모든 setter 메소드에는 트랜잭션을 보증해야 하는 피어 목록을 지정하는 endorsers 매개변수가 포함됩니다. .ochain.json 파일의 sameOrgEndorserOptionInWrapperAPI 매개변수는 빈 배열로 설정됩니다.

"sameOrgEndorserOptionInWrapperAPI": []

세터 메소드에는 기밀 트랜잭션에 필요한 블라인딩 요소가 Oracle Blockchain Platform 인스턴스에서 검색됨을 나타내는 Confidential-Transaction 헤더가 필요합니다. 이 헤더는 기밀 거래에 대한 Postman 요청에서 필요합니다.

기밀 모드 체인 코드의 보안을 유지하려면 transientMap 객체에 인수를 전달합니다. activateAccount 메소드에 대한 다음 예제에 표시된 것처럼 임시 맵의 args 매개변수에서 직접 인수를 전달할 수 있습니다.

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

래퍼 API Postman 컬렉션의 경우(일반 Postman 컬렉션이 아님) transientMapArgsFlag 플래그를 사용할 수도 있습니다. true로 설정하면 activateAccount 메소드에 대한 다음 예제에 표시된 것처럼 모든 인수가 임시 맵에 자동으로 전달됩니다.

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

다음 예제 Postman 요청은 이러한 매개변수와 헤더를 보여줍니다.

createAccount(설정 메소드)

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 메소드)

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 지원

기본적으로 Blockchain App Builder에서 생성된 Postman 컬렉션은 OAuth 2.0 권한 부여를 위해 구성됩니다. OAuth 2.0을 사용으로 설정하려면 Postman 모음의 전역 변수에 다음 값을 제공해야 합니다.

client-id: Oracle Blockchain Platform 인스턴스의 클라이언트 ID입니다.
client-secret: Oracle Blockchain Platform 인스턴스의 클라이언트 암호입니다.
access-token-url: 액세스 토큰 URL에는 Oracle Blockchain Platform 인스턴스의 도메인 URL이 https://<domain-URL>/oauth2/v1/token 형식으로 포함되어 있습니다.

Oracle Blockchain Platform 인스턴스에 대한 클라이언트 ID, 클라이언트 암호 및 도메인 URL을 검색하려면 다음 단계를 완료하십시오.

Oracle Cloud Infrastructure(OCI) 계정에 사인인합니다. Oracle Blockchain Platform 인스턴스가 포함된 컴파트먼트를 선택합니다.
콘솔에서 탐색 메뉴를 누른 다음 ID 및 보안을 누릅니다.
ID에서 도메인을 선택합니다.
도메인 페이지에서 Oracle Identity Cloud Service를 누릅니다.
Oracle Identity Cloud Service 탐색 메뉴에서 Oracle Cloud Services를 선택합니다. Oracle Blockchain Platform 인스턴스를 찾아 해당 인스턴스의 세부정보 페이지를 엽니다.
표시되는 기본 페이지는 OAuth 구성 페이지입니다. Client ID(클라이언트 ID) 및 Client Secret(클라이언트 암호) 필드는 General Information(일반 정보) 섹션에 있습니다.
도메인 페이지로 돌아가서 Oracle Blockchain Platform 인스턴스에서 사용되는 도메인을 누릅니다.
도메인 URL이 도메인 세부정보에 표시됩니다.

이러한 전역 변수는 사전 요청 스크립트에서 access_token 위치 표시자를 생성하는 데 사용됩니다. 스크립트는 모든 요청이 bc-admin 권한 부여로 실행되도록 bc-admin 사용자에 대한 토큰을 생성합니다.

첫번째 요청은 지정된 인증서를 사용하여 bc-admin 토큰을 생성합니다. 토큰 및 만료 값은 Postman 컬렉션 변수에 저장됩니다. 누락되거나 만료된 토큰은 자동으로 재생성됩니다. 클라이언트 ID 또는 클라이언트 암호가 변경되면 스크립트는 자동으로 변경 사항을 감지하고, 이전 토큰을 무효화하고, 업데이트된 자격 증명이 있는 토큰을 생성합니다. access_token 값을 수동으로 수정하면 요청이 실패할 수 있습니다. access_token 값을 지우면 스크립트가 자동으로 다른 bc-admin 토큰을 생성합니다.

Postman 모음에서 Generate Access Token for User 요청을 사용하여 기본 bc-admin 토큰 이외의 토큰을 생성하고 사용할 수 있습니다. 사용자 정의 액세스 토큰을 생성하려면 다음 단계를 완료합니다.

사용자에 대한 액세스 토큰 생성 요청을 엽니다. 기본적으로 username 및 password 값은 bc-admin로 설정됩니다.
컬렉션 변수의 username 및 password 값을 갱신합니다.
새 액세스 토큰 생성을 누릅니다. 액세스 토큰 관리 창이 열립니다.
기본 이름을 업데이트하고 다른 세부정보를 검토한 후 저장을 누릅니다. 이제 토큰을 사용할 수 있으며 권한 부여 페이지의 사용 가능한 토큰 섹션에 표시됩니다.

생성된 Postman 컬렉션에는 다음 표와 같이 OAuth 2.0 지원에 필요한 변수가 포함됩니다.

변수	설명	기본값
`client-id`	Oracle Blockchain Platform 인스턴스의 클라이언트 ID입니다.	`client-id` 값
`client-secret`	Oracle Blockchain Platform 인스턴스의 클라이언트 암호입니다.	`client-secret` 값
`access-token-url`	OAuth Oracle Blockchain Platform 인스턴스 도메인의 2.0 토큰 끝점입니다.	`access-token-url` 값
`access_token`	`bc-admin` 또는 사용자정의 사용자에 대해 생성된 OAuth 2.0 액세스 토큰입니다.	처음에는 사용할 수 없음; 스크립트로 관리됨
`access_token_expiry`	생성된 액세스 토큰의 만료 시간입니다.	처음에는 사용할 수 없음; 스크립트로 관리됨
`admin_credentials_hash`	토큰 검증 및 재생성에 사용되는 인증서의 해시 값입니다.	처음에는 사용할 수 없음; 스크립트로 관리됨