[Hyperledger Fabric v1.0] 3. Tutorial(튜토리얼): Writing Your First Application(첫 번째 애플리케이션 작성)

해당 글은 Hyperledger Fabric 페이지의 게시글을 번역 및 정리한 자료입니다.

원본 사이트 : http://hyperledger-fabric.readthedocs.io/en/release/write_first_app.html

Writing Your First Application(첫 번째 애플리케이션 작성)

※ 참고: 패브릭 네트워크의 기본 아키텍처에 익숙하지 않은 경우 계속하기 전에 먼저 Introduction 및 Building Your First Network 설명서를 참조하십시오.

이 섹션에서는 Fabric 앱의 작동 방식을 보여주는 몇 가지 샘플 프로그램을 살펴 보겠습니다. fabcar라고 하는 이러한 앱(그리고 그들이 사용하는 스마트 계약)은 Fabric 기능에 대한 폭 넓은 시연을 제공합니다. 특히, 인증 기관과 상호 작용하고 등록(enrollment) 인증서를 생성하는 프로세스를 보여 주며, 생성된 ID(사용자 개체)를 활용하여 원장(ledger)을 쿼리하고 업데이트합니다.

우리는 세 가지 주요 단계를 거칩니다.

1. 개발 환경 설정하기. 우리의 응용 프로그램은 상호 작용할 네트워크가 필요하기 때문에 등록 / 등록 , 쿼리 및 업데이트에 필요한 구성 요소들만을 다운로드 합니다.

2. 앱에서 사용할 샘플 스마트 계약의 매개 변수를 학습합니다. 우리의 스마트 계약에는 다양한 방법으로 원장과 상호 작용할 수 있는 다양한 기능이 포함되어 있습니다. 우리는 응용 프로그램이 사용할 기능에 대해 배우기 위해 스마트 계약서를 조사할 것입니다.

3. 원장에서 자산을 쿼리하고 업데이트 할 수 있는 응용 프로그램 개발. 앱 코드 자체 (자바 스크립트로 작성된 앱)에 들어가서 변수를 수동으로 조작하여 다양한 종류의 쿼리와 업데이트를 실행합니다.

이 튜토리얼을 완료한 후에는 Fabric 네트워크에서 ledger(예: 피어)와 상호 작용할 수 있는 스마트 계약서와 함께 애플리케이션을 프로그래밍하는 방법에 대한 기본적인 이해가 필요합니다.

Setting up your Dev Environment(개발 환경 설정)

우선, 네트워크 및 응용 프로그램을 위해 패브릭 이미지와 관련 아티팩트를 다운로드하십시오 ...

Prerequisites(필수 구성 요소) 페이지를 방문하여 필요한 종속성이 컴퓨터에 설치되어 있는지 확인하십시오.

다음으로, Hyperledger Fabric Samples 페이지를 방문하여 제공된 지시 사항을 따르십시오. fabric-samples 저장소를 복제한 후에 최신의 안정된 Fabric 이미지와 사용 가능한 유틸리티를 다운로드한 후에 이 튜토리얼로 돌아가십시오.

git clone https://github.com/hyperledger/fabric-samples.git
cd fabric-samples/fabcar

이 시점에서 모든 것이 설치되어야합니다. fabric-samples 저장소 내의 fabcar 하위 디렉토리로 이동하여 내부 내용을 살펴보십시오.

cd fabric-samples/fabcar  && ls

다음을 보아야 합니다.

chaincode    invoke.js       network         package.json    query.js        startFabric.sh

시작하기 전에 우리는 또한 약간의 정리 작업이 필요합니다. 부실 또는 활성 컨테이너를 강제 종료하려면 다음 명령을 실행하십시오.

docker rm -f $(docker ps -aq)

캐시된 네트워크를 지우십시오.

# 명령 프롬프트에서 'y'를 누르십시오.
docker network prune

마지막으로 이 튜토리얼을 이미 실행한 경우 fabcar 스마트 계약의 기본 체인 코드 이미지를 삭제해야 합니다. 이 콘텐츠를 처음으로 사용하는 사용자는 시스템에 이 체인 코드 이미지가 없습니다.

docker rmi dev-peer0.org1.example.com-fabcar-1.0-5c906e402ed29f20260ae42283216aa75549c571e2e380f3615826365d8269ba

Install the clients & launch the network

※ 참고: 다음 지침에서는 fabric-samples repo의 로컬 복제본 내의 fabcar 하위 디렉토리에 있어야합니다. 이 튜토리얼의 나머지 부분에 대해서는 이 서브 디렉토리의 루트에 남아 있어야합니다.

다음 명령을 실행하여 응용 프로그램에 대한 Fabric 종속성을 설치하십시오. 우리는 우리의 앱(들)이 CA 서버와 통신하고 신원 자료를 검색 fabric-client할 수 있게 해주는 fabric-ca-client에 관심을 가지고 있으며, 신원 자료를 로드하고 peer 및 orderer 서비스 팀과 통화 할 수 있도록 허용 할 것입니다.

Getting a Test Network ( 테스트 네트워크 얻기 )

전제 조건 페이지를 방문 하여 시스템에 필요한 종속성이 설치되어 있는지 확인하십시오. 이제 fabric-samples repo를 복제 할 작업 디렉토리를 결정하십시오. clone 명령을 실행하고 fabcar서브 디렉토리 로 변경하십시오.

이 하위 디렉토리 fabcar에는 샘플 앱을 실행하기 위한 스크립트와 애플리케이션 코드가 들어 있습니다. 이 디렉토리에서 ls를 발행하십시오. 다음을 보아야합니다.

이제 startFabric.sh스크립트를 사용하여 네트워크를 시작하십시오.

[참고] 다음 명령은 Hyperledger Fabric Docker 이미지를 다운로드하고 추출하므로 완료하는 데 몇 분이 걸립니다.

./startFabric.sh

간결함을 위해 이 명령으로 어떤 일이 벌어지고 있는지 자세히 설명하지 않겠습니다. 다음은 간단한 개요입니다.

• 피어 노드, 주문 노드, 인증 기관 및 CLI 컨테이너 시작
• 채널을 만들고 피어를 채널에 연결합니다.
• 스마트 컨트랙트 (즉, 체인 코드)를 피어의 파일 시스템에 설치하고 상기 체인 코드를 채널에 인스턴스화합니다. 인스턴스화는 chaincode 컨테이너를 시작합니다.
• initLedger 함수를 호출하여 10 개의 고유한 자동차로 채널 원장을 채 웁니다.

[참고] 이러한 작업은 일반적으로 조직 또는 피어 관리자가 수행합니다. 스크립트는 CLI를 사용하여 이러한 명령을 실행하지만 SDK에서도 지원됩니다. 예제 스크립트는 Hyperledger Fabric Node SDK 레포 를 참조하십시오.

docker ps 명령을 실행하여 startFabric.sh 스크립트에 의해 시작된 프로세스를 표시하십시오. 첫 번째 네트워크 구축 섹션에서 이러한 작업의 세부 사항과 메커니즘에 대해 자세히 배울 수 있습니다. 여기서는 응용 프로그램에만 초점을 맞 춥니 다. 다음 그림은 응용 프로그램이 Hyperledger 패브릭 네트워크와 상호 작용하는 방식을 단순하게 보여줍니다.

자 이제 예제 네트워크와 코드가 생겼으니 다른 조각들이 어떻게 맞는지 살펴 보겠습니다.

How Applications Interact with the Network ( 응용 프로그램이 네트워크와 상호 작용하는 방법 )

응용 프로그램은 API를 사용하여 스마트 계약("체인 코드"라고 함)을 호출합니다. 이러한 현명한 계약은 네트워크에서 호스팅되며 이름과 버전으로 식별됩니다. 예를 들어, chaincode 컨테이너의 제목은 - dev-peer0.org1.example.com-fabcar-1.0입니다. 여기서 이름은 fabcar이고 버전은 1.0이며 실행되는 피어는 dev-peer0.org1.example.com입니다.

API는 SDK (소프트웨어 개발 키트)를 통해 액세스 할 수 있습니다. 이 연습에서는 응용 프로그램을 개발하는 데 사용할 수있는 Java SDK 및 CLI가 있지만 Hyperledger 패브릭 노드 SDK 를 사용할 것입니다.

Querying the Ledger

검색어는 원장에서 데이터를 읽는 방법입니다. 단일 키, 여러 키의 값을 쿼리 할 수 ​​있습니다. 또는 - 원장이 JSON과 같은 풍부한 데이터 저장소 형식으로 작성된 경우 복잡한 키워드 검색을 수행 할 수 있습니다 (예 : 특정 키워드가 포함 된 모든 애셋을 찾습니다).

앞에서 말했듯이 샘플 네트워크에는 활성 체인 코드 컨테이너와 10 개의 다른 자동차가 준비되어있는 원장이 있습니다. 또한 자동차의 세부 사항을 원장에 문의하는 데 사용할 수 있는 샘플 자바 스크립트 코드 - query.js가 fabcar디렉토리에 있습니다.

이 응용 프로그램의 작동 방식을 살펴보기 전에 프로그램이 작동하도록 SDK 노드 모듈을 설치해야합니다. 귀하의에서 fabcar디렉토리, 다음을 실행합니다.

npm install

[참고]fabcar디렉토리 에서 모든 후속 명령을 실행합니다.

이제 우리는 자바 스크립트 프로그램을 실행할 수 있습니다. 먼저 query.js 프로그램을 실행하여 원장의 모든 자동차 목록을 반환합시다. 모든 자동차 queryAllCars를 쿼리하는 함수는 앱에 미리로드되어 있으므로 간단히 프로그램을 실행할 수 있습니다.

node query.js

• 답 안나오는 에러

• 

다음과 같이 반환해야합니다.

Query result count =  1
Response is  [{"Key":"CAR0", "Record":{"colour":"blue","make":"Toyota","model":"Prius","owner":"Tomoko"}},
{"Key":"CAR1",   "Record":{"colour":"red","make":"Ford","model":"Mustang","owner":"Brad"}},
{"Key":"CAR2", "Record":{"colour":"green","make":"Hyundai","model":"Tucson","owner":"Jin Soo"}},
{"Key":"CAR3", "Record":{"colour":"yellow","make":"Volkswagen","model":"Passat","owner":"Max"}},
{"Key":"CAR4", "Record":{"colour":"black","make":"Tesla","model":"S","owner":"Adriana"}},
{"Key":"CAR5", "Record":{"colour":"purple","make":"Peugeot","model":"205","owner":"Michel"}},
{"Key":"CAR6", "Record":{"colour":"white","make":"Chery","model":"S22L","owner":"Aarav"}},
{"Key":"CAR7", "Record":{"colour":"violet","make":"Fiat","model":"Punto","owner":"Pari"}},
{"Key":"CAR8", "Record":{"colour":"indigo","make":"Tata","model":"Nano","owner":"Valeria"}},
{"Key":"CAR9", "Record":{"colour":"brown","make":"Holden","model":"Barina","owner":"Shotaro"}}]

이들은 10 대입니다. Adriana 소유의 검은 색 Tesla Model S, Brad 소유 빨간색 포드 머스탱, Pari라는 누군가 소유 한 보라색 Fiat Punto 등등. 원장은 키 / 값 기반이며 구현시 키는 CAR0에서 CAR9까지입니다. 이것은 특히 중요하게 될 것입니다. 이제는 두포에서 어떻게 보이는지 봅시다 (당신이 말장난을 용서한다면). 편집기 (예 : 원자 또는 시각 스튜디오)를 사용하고 query.js 프로그램을 엽니다. 응용 프로그램의 초기 섹션에서는 체인 코드 ID, 채널 이름 및 네트워크 종점과 같은 특정 변수를 정의합니다.

응용 프로그램의 초기 섹션에서는 체인 코드 ID, 채널 이름 및 네트워크 종점과 같은 특정 변수를 정의합니다.

var options = {
      wallet_path : path.join(__dirname, './network/creds'),
      user_id: 'PeerAdmin',
      channel_id: 'mychannel',
      chaincode_id: 'fabcar',
      network_url: 'grpc://localhost:7051',
}

이것은 쿼리를 구성하는 청크입니다.

// queryCar - requires 1 argument, ex: args: ['CAR4'],
// queryAllCars - requires no arguments , ex: args: [''],
const request = {
   chaincodeId: options.chaincode_id,
   txId: transaction_id,
   fcn: 'queryAllCars',
   args: ['']
}

chaincode_id 변수를 fabcar로 정의하여이 특정 체인 코드를 타겟팅 할 수있게 한 다음 해당 체인 코드 내에 정의 된 queryAllCars 함수를 호출합니다. 이전에 node.js 명령을 발행했을 때이 특정 함수가 호출되어 원장을 조회했습니다. 그러나 이것이 우리가 전달할 수있는 유일한 기능은 아닙니다.

다른 것들을 살펴 보려면 체인 코드 하위 디렉토리로 이동하여 편집기에서 fabcar.go를여십시오. initLedger, queryCar, queryAllCars, createCar 및 changeCarOwner와 같이 호출 할 수있는 다음 함수가 있음을 알 수 있습니다. queryAllCars 함수를 자세히 살펴보고 장부와 상호 작용하는 방법을 살펴 보겠습니다.

func (s *SmartContract) queryAllCars(APIstub shim.ChaincodeStubInterface) sc.Response {

     startKey := "CAR0"
     endKey := "CAR999"

     resultsIterator, err := APIstub.GetStateByRange(startKey, endKey)
}

이 함수는 shimm 인터페이스 함수인 GetStateByRange를 사용하여 startKey와 endKey의 args간에 원장 데이터를 반환합니다. 이러한 키는 각각 CAR0 및 CAR999로 정의됩니다. 따라서 우리는 이론적으로 1,000 개의 자동차를 만들 수 있습니다 (키에 태그가 올바르게 지정되었다고 가정). queryAllCars는 모든 자동차를 나타냅니다.

다음은 앱이 chaincode에서 다른 기능을 호출하는 방법을 나타낸 것입니다.

const request = {
      chaincodeId: options.chaincode_id,
      txId: transaction_id,
      fcn: 'queryCar',
      args: ['CAR4']
}

프로그램을 저장하고 fabcar디렉토리로 다시 이동하십시오 . 이제 프로그램을 다시 실행하십시오.

node query.js

다음을 보아야합니다.

{"colour":"black","make":"Tesla","model":"S","owner":"Adriana"}

Adriana의 검정색 Tesla Model S를 쿼리하는 것까지 모든 자동차를 쿼리하지 않았습니다. queryCar 함수를 사용하여 모든 키 (예 : CAR0)에 대해 쿼리하고 해당 자동차에 맞는 제조업체, 모델, 색 및 소유자를 얻습니다 . 좋습니다. 이제 체인 코드의 기본 쿼리 기능과 쿼리 프로그램의 소수의 매개 변수에 익숙해 져야합니다. 원장을 업데이트 할 시간 ...

Updating the Ledger ( 원장 업데이트 )

이제는 원장 쿼리를 수행하고 약간의 코드를 추가 했으므로 원장을 업데이트 할 준비가되었습니다. 우리가 할 수 있는 많은 잠재적인 업데이트가 있지만 우선 시동기를 위한 새로운 자동차를 만들어 보겠습니다.

원장 갱신은 트랜잭션 제안을 생성하는 응용 프로그램으로 시작됩니다. 쿼리와 마찬가지로 채널 ID, 함수 및 트랜잭션을 대상으로 하는 특정 스마트 계약을 식별하는 요청이 생성됩니다. 그런 다음 프로그램은 channel.SendTransactionProposalAPI를 호출하여 트랜잭션 제안서를 피어에게 보냅니다.

네트워크 (즉, 인증 피어)는 제안서 응답을 반환합니다.이 응답은 응용 프로그램이 트랜잭션 요청을 작성하고 서명하는 데 사용합니다. 이 요청은 channel.sendTransactionAPI 를 호출하여 주문 서비스로 전송됩니다. 주문 서비스는 트랜잭션을 블록으로 묶어 유효성 검사를 위해 채널의 모든 피어에게 블록을 전달합니다. (우리의 경우에는 단 하나의 지지자 만 있습니다.)

마지막으로 애플리케이션은 eh.setPeerAddrAPI를 사용하여 피어의 이벤트 리스너 포트에 eh.registerTxEvent연결하고 특정 트랜잭션 ID와 연관된 이벤트를 등록하도록 호출 합니다. 이 API를 사용하면 응용 프로그램이 트랜잭션의 운명 (즉, 성공적으로 커밋되었거나 실패한 트랜잭션)을 알 수 있습니다. 알림 메커니즘으로 생각하십시오.

[참고] 여기서는 트랜잭션의 수명주기에 대해 자세히 다루지 않습니다. 트랜잭션이 궁극적으로 장부에 커밋되는 방법에 대한 자세한 내용 은 트랜잭션 흐름 설명서를 참조하십시오.

처음 호출 할 때의 목표는 단순히 새 자산 (이 경우 자동차)을 만드는 것입니다. 우리는 별도의 자바 스크립트 프로그램인 invoke.js를 가지고 있습니다. 쿼리와 마찬가지로 편집기를 사용하여 프로그램을 열고 호출을 구성하는 코드 블록으로 이동합니다.

// createCar - requires 5 args, ex: args: ['CAR11', 'Honda', 'Accord', 'Black', 'Tom'],
// changeCarOwner - requires 2 args , ex: args: ['CAR10', 'Barry'],
// send proposal to endorser
var request = {
    targets: targets,
    chaincodeId: options.chaincode_id,
    fcn: '',
    args: [''],
    chainId: options.channel_id,
    txId: tx_id
}

- 당신은 우리가 두 가지 기능 중 하나를 호출 할 수있는 것을 볼 수 있습니다. createCar함수 또는 changeCarOwner함수로. 빨간 시보레 볼트를 만들어 닉이라는 소유자에게 주자. 우리는 CAR9 원장에 달려 있으므로 CAR10여기에서 식별 키로 사용하겠습니다. 업데이트 된 코드 블록은 다음과 같아야합니다.

var request = {
    targets: targets,
    chaincodeId: options.chaincode_id,
    fcn: 'createCar',
    args: ['CAR10', 'Chevy', 'Volt', 'Red', 'Nick'],
    chainId: options.channel_id,
    txId: tx_id
}

저장하고 프로그램을 실행하십시오.

node invoke.js

제안서 응답 및 거래 ID에 대한 일부 출력이 터미널에 있습니다. 그러나 우리가 신경 쓰는 것은 이 메시지입니다.

The transaction has been committed on peer localhost:7053

피어는 이 이벤트 알림을 내고 eh.registerTxEvent API 덕분에 애플리케이션이 이벤트 알림을받습니다. 이제 query.js 프로그램으로 돌아가서 CAR10의 arg에 대해 queryCar 함수를 호출하면 다음과 같이 표시됩니다.

node query.js

Response is  {"colour":"Red","make":"Chevy","model":"Volt","owner":"Nick"}

마지막으로 changeCarOwner 함수를 호출 해 보겠습니다. Nick은 기분이 좋고 Barry라는 남자에게 Chevy Volt를주고 싶다. 따라서 invoke.js를 편집하여 다음을 반영합니다

var request = {
   targets: targets,
   chaincodeId: options.chaincode_id,
   fcn: 'changeCarOwner',
   args: ['CAR10', 'Barry'],
   chainId: options.channel_id,
   txId: tx_id
}

프로그램을 다시 실행하여 노드 invoke.js를 실행 한 다음 마지막으로 쿼리 응용 프로그램을 실행하십시오. 우리는 여전히 CAR10에 대해 질의를하고 있으므로 다음을 확인해야합니다.

node invoke.js
node query.js

Response is  {"colour":"Red","make":"Chevy","model":"Volt","owner":"Barry"}

추가 리소스

Hyperledger 패브릭 노드 SDK의 환매 특약은 깊은 문서와 샘플 코드를위한 훌륭한 자원이다. Hyperledger Rocket Chat 의 Hyperledger Fabric 커뮤니티 및 구성 요소 전문가에게 문의 할 수도 있습니다.