이 가이드에서는 Universal Ledger API 클라이언트를 빌드하는 개발자를 위한 아키텍처 및 구현 가이드라인을 제공합니다. 학습 내용:
- 고가용성을 위해 네트워크 토폴로지를 활용합니다.
- 트랜잭션을 제출하고 실행 결과를 이해합니다.
- 폴링, 제한 시간, 재시도 전략을 구현합니다.
Universal Ledger API 엔드포인트에 연결
요청은 Universal Ledger API를 통해 특정 네트워크 엔드포인트로 라우팅됩니다. 네트워크 엔드포인트는 해당 리전 내의 검사자에게 요청을 배포하는 리전별 클라우드 리소스입니다. 네트워크 엔드포인트에 도달하려면 클라이언트가 해당 네트워크 엔드포인트가 있는 Cloud 리전과 일치하는 리전 API 엔드포인트(REP)에 연결해야 합니다.
리전 엔드포인트 이름은 다음 형식을 따릅니다.
universalledger.REGION.rep.googleapis.com
REGION을 네트워크 엔드포인트가 있는 지원되는 리전으로 바꿉니다.
네트워크 토폴로지 및 고가용성
Universal Ledger 네트워크는 여러 영역과 리전에 분산된 여러 검사자로 구성되므로 전체 네트워크의 고가용성을 보장합니다.
영역 장애: Cloud 영역 내에서 단일 검사기에 장애가 발생하면 동일한 리전 내의 다른 검사기가 요청을 원활하게 계속 처리합니다.
리전 중단: 전체 리전을 사용할 수 없게 되면 다른 리전의 검사기는 계속 작동합니다. 트랜잭션을 계속 제출하려면 클라이언트가 대체하여 다른 엔드포인트를 통해 트랜잭션을 다시 제출하는 것이 안전합니다.
트랜잭션 실행 특성
원자적 실행: 트랜잭션은 완전히 성공하거나 완전히 실패합니다. 잔액 부족으로 인해 요청된 자금의 일부만 이체하는 것과 같은 부분 트랜잭션 실행은 발생하지 않습니다. 여기에는 트랜잭션 체인이 포함되어 여러 임의 트랜잭션을 단일 원자 시퀀스로 결합할 수 있습니다.
자동 재시도 없음: 네트워크는 제출된 트랜잭션을 정확히 한 번 실행하려고 시도합니다. 실행이 실패하면 원장은 트랜잭션을 자동으로 큐에 추가하거나 재시도하지 않습니다.
멱등 재제출: 제출된 모든 거래는 정확한 직렬화된 페이로드(시퀀스 넘버 및 발신자 포함)를 기반으로 고유한 거래 ID를 생성합니다. 정확히 동일한 페이로드를 여러 번 제출하면 동일한 거래 ID가 생성됩니다. 원장은 트랜잭션이 최대 한 번 실행되도록 보장하므로, 엔드포인트 중 하나를 사용할 수 없는 경우 동일한 트랜잭션 페이로드를 다른 엔드포인트에 다시 제출해도 안전합니다.
자세한 내용은
SubmitTransactionRequest참조 페이지를 확인하세요.
지연 시간, 폴링, 재시도 전략
트랜잭션을 제출하면 검사자가 먼저 서명과 시퀀스 넘버가 유효한지 빠르게 확인합니다. 성공하면 Universal Ledger API는 할당된 거래 ID를 포함하여 SubmitTransactionResponse로 즉시 응답합니다.
대부분의 거래는 3초 이내에 완료됩니다. 트랜잭션 상태를 확인하려면 제공된 거래 ID를 사용하여 QueryTransactionState 메서드를 폴링합니다.
트랜잭션 상태가 여전히
PENDING이면 지수 백오프 전략을 사용하여 상태를 다시 가져옵니다. 예를 들어 3초, 9초, 27초, 60초 간격으로 쿼리합니다.QueryTransactionState가NOT_FOUND를 반환하면 트랜잭션을 다시 제출합니다.
거래 시도가 FINALIZED되면 응답에는 다음과 같은 다양한 세부정보가 포함된 TransactionCertificate도 포함됩니다.
- 트랜잭션이 완료된 라운드 ID입니다.
- 실행 상태(OK 또는 실패)
- 트랜잭션 출력과 같은 트랜잭션 이벤트입니다.
시간 초과 프로토콜
60초 후에도 트랜잭션이 PENDING 또는 NOT_FOUND 상태로 유지되는 경우 요청을 처리하는 검사기가 네트워크의 다른 검사기를 따라잡지 못하는 것으로 간주합니다. 다음 단계를 완료하세요.
- 다른 네트워크 리전에서 다른 엔드포인트를 선택합니다.
- 서명된 동일한 거래 페이로드를 다시 제출합니다.
- Universal Ledger팀에서 조사할 수 있도록 이 페이지 상단의 '의견 보내기' 버튼을 사용하여 문제를 신고하세요.
트랜잭션 상태를 확인할 때 동일한 페이로드를 여러 번 제출한 경우 응답에 여러 TransactionAttempt 메시지가 포함될 수 있습니다. 최대 한 번의 시도가 OK 트랜잭션 상태로 완료되며, 이는 TransactionEffects에서 확인할 수 있습니다. 다른 시도는 대기 중이거나 실패 상태입니다. 이는 예상된 동작입니다. 원장이 트랜잭션 제출 중 하나를 성공적으로 실행하고 중복된 재제출을 올바르게 거부했거나 결국 거부할 것입니다.
네트워크 일관성
완료된 트랜잭션: 한 검사자가 트랜잭션을 완료된 것으로 보고하면 동일한 네트워크의 다른 모든 검사자는 결국 트랜잭션을 처리하고 정확히 동일한 결과를 재현할 것으로 예상됩니다. 트랜잭션이 완료된 라운드 ID를 사용하여
QueryAccountRequest를 제출하면(TransactionCertificate에서 찾을 수 있음) 모든 동기화된 검사기에서 동일한 결과가 생성됩니다.미확정 트랜잭션: 트랜잭션은 네트워크 전반에 비동기식으로 전파되므로 트랜잭션이 확정된 것으로 보고되는지 여부는 검사기마다 다를 수 있습니다.
중단에서 복구 중이거나 동기화 지연이 발생하는 검사기는 완료된 트랜잭션을 일시적으로
PENDING또는NOT_FOUND로 보고할 수 있습니다. 검사자가 따라잡으면 트랜잭션 상태가 해결됩니다.
클라이언트 책임 및 오류 처리
트랜잭션 추적: 클라이언트 애플리케이션은 제출된 모든 트랜잭션의 상태를 완료될 때까지 추적해야 합니다.
오류 처리: 트랜잭션이 실패하면
TransactionCertificate에 포함된 실패 세부정보를 검색하고 검사하여 적절한 비즈니스 수준의 해결 방법을 트리거합니다.
다음 단계
- Universal Ledger API에 RPC 요청을 보내는 방법 알아보기
- Universal Ledger API 참조를 확인하세요.