래퍼 API 배치

Oracle Blockchain Platform Digital Assets Edition은 블록체인 앱 빌더에서 생성된 체인코드의 모든 컨트롤러 API에 대한 래퍼 API를 생성할 수 있습니다. 스택 리소스 관리자에 래퍼 API 패키지를 배치하고 연관된 Postman 모음을 사용하여 래퍼 API를 테스트하려면 다음 단계를 완료합니다.

Blockchain App Builder를 사용하여 래퍼 API 패키지를 생성하면 선택한 디렉토리에 기본 이름 지정 규칙을 사용하여 두 개의 파일이 생성됩니다.

  • <ChaincodeName>WrapperAPI.zip: OCI(Oracle Cloud Infrastructure) 리소스 관리자에서 래퍼 API를 배치하는 데 필요한 Terraform 스크립트가 포함된 아카이브 파일입니다.
  • <ChaincodeName>_WrapperAPI.postman_collection.json: 배치 후 래퍼 API를 테스트하는 데 사용되는 Postman 모음입니다.

래퍼 API를 배치하려면 WrapperAPI.zip 파일을 사용하여 OCI Resource Manager에서 스택을 생성합니다.

래퍼 API 패키지를 배치하려면 다음 필요 조건을 충족해야 합니다.

  • 래퍼 API 패키지는 Blockchain App Builder를 사용하여 생성되어야 합니다.
  • 패키지는 래퍼 API에 필요한 모든 구성 변수 값과 끝점 값을 포함해야 합니다.
  1. OCI에 로그인합니다.
    OCI 콘솔을 열고 https://cloud.oracle.com/에 사인인합니다. 스택이 배치될 컴파트먼트에 있는지 확인합니다.
  2. 탐색 메뉴를 확장합니다. Developer Services를 선택합니다. 리소스 관리자에서 스택을 선택합니다.
    스택에 대한 리소스 관리자 인터페이스가 열립니다. Terraform 구성을 사용하여 기존 스택을 보고, 스택을 생성하고, 인프라를 코드로 관리할 수 있습니다.
  3. 스택 생성을 누릅니다.
  4. 스택 정보를 구성합니다.
    1. Terraform 구성 섹션에서 내 구성을 선택합니다.
    2. 스택 구성, Terraform 구성 소스에서 .Zip 파일을 선택합니다.
    3. 찾아보기를 누르고 래퍼 API .zip 파일로 이동합니다.
    4. .zip 파일이 업로드된 후 스택 이름이 올바른지 확인합니다.
    5. Terraform 버전 드롭다운 목록에서 v1.2 이상을 선택합니다. 기본적으로 Resource Manager는 최신 버전을 사용합니다. v1.2 이전 버전을 선택하면 배치가 실패합니다.
    6. 나머지 모든 설정은 기본값으로 유지할 수 있습니다. 다음을 누르십시오.
  5. 스택 변수를 구성합니다.
    1. 모든 구성 변수 값이 정확한지 확인하고 배치 요구사항을 충족하도록 래퍼 API 패키지에 지정된 구성 변수에 맞춥니다.
    2. ocir_user_name의 경우 OCI 계정과 연관된 전자메일 주소를 입력합니다.
    3. ocir_user_password의 경우 OCI 인증 토큰인 비밀번호를 입력합니다. OCI 콘솔의 프로파일 또는 사용자 설정 섹션에서 이 토큰을 생성할 수 있습니다. 인증 토큰은 Oracle Cloud Infrastructure Registry에 로그인하기 위한 비밀번호로 작동합니다.
      인증 토큰 생성에 대한 자세한 내용은 승인 토큰 생성을 참조하십시오.
    4. 나머지 모든 설정은 기본값으로 유지할 수 있습니다. 다음을 누르십시오.
  6. 스택 정보를 검토합니다. 모든 항목이 올바르면 생성을 누릅니다.
  7. Terraform 계획을 실행합니다.
    1. 스택의 세부정보 페이지에서 계획을 눌러 실행 계획 생성을 시작합니다.
    2. 선택적으로 작업 계획을 구성합니다. 기본 이름을 편집하거나 고급 옵션을 선택하여 제공자 버전을 변경하거나 설정을 조정할 수 있습니다.
    3. 계획 작업을 생성하고 실행하려면 계획을 누릅니다.
      Terraform 구성이 구문 분석되고 실행 계획이 생성되어 실행되어 다음 작업이 완료됩니다.
      • 구문 또는 구성 오류가 없는지 확인하기 위해 Terraform 스크립트를 검증합니다.
      • 실제 Infrastructure를 변경하지 않고 리소스 생성 프로세스를 시뮬레이트합니다.
      • 스크립트가 생성, 수정 또는 삭제할 리소스를 나열하는 출력 요약을 제공합니다.
    4. 스택의 작업 섹션에서 상태를 모니터링합니다. 계획이 성공적으로 완료된 후 출력을 검토하여 생성될 리소스 수를 확인하고 문제가 없는지 확인합니다.
  8. 스택에 Terraform 계획을 적용합니다.
    1. 스택의 세부정보 페이지에서 적용을 누릅니다.
    2. Terraform 적용 패널에서 적용을 누릅니다.
      Terraform 계획을 적용하면 다음 작업이 완료됩니다.
      • Terraform 스크립트에 정의된 대로 다음 리소스를 모두 프로비전합니다.
        • VCN(가상 클라우드 네트워크)
        • 애플리케이션(OCI 함수)
        • API 게이트웨이
        • API 배포
        • IAM 정책
        • OCI 레지스트리 저장소
      • 래퍼 API에 필요한 모든 기반구조를 생성합니다.
    3. 스택의 작업 섹션에서 상태를 모니터링하여 작업이 오류 없이 성공적으로 완료되는지 확인합니다.
  9. API 게이트웨이 끝점을 검색합니다.
    1. 적용 작업이 완료된 후 작업 적용 페이지의 출력 섹션으로 이동하여 생성된 출력 값을 확인합니다.
    2. 출력은 키가 끝점 이름을 나타내고 값이 해당 끝점 값인 JSON 객체를 반환합니다.
      api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}
    3. 끝점을 복사합니다. API Postman 모음을 업데이트하려면 끝점이 필요합니다.
Postman으로 래퍼 API 테스트

Postman을 사용하여 래퍼 API를 테스트할 수 있습니다. 적절한 값을 할당하여 래퍼 API Postman 컬렉션의 모든 변수를 구성합니다. 동적으로 생성된 게이트웨이 엔드포인트가 제공되는 OCI의 스택 배포 출력에서 api_gateway_endpoint 값을 가져옵니다.

Postman 컬렉션의 변수가 업데이트되면 래퍼 API를 테스트할 수 있습니다. 컬렉션의 각 API 요청에는 해당 래퍼 API와 관련된 필수 페이로드가 포함됩니다.

그림 4-1 Postman으로 API 래퍼 컬렉션 테스트


이 그림은 생성된 게이트웨이 API를 사용하여 모음에서 API를 실행하는 Postman을 보여줍니다.

다음 정보는 래퍼 API를 배치 및 사용할 때 문제를 해결하는 데 사용할 수 있습니다.

승인되지 않음: 잘못된 ocir_user_name 또는 ocir_user_password
이 오류는 사용자 이름 또는 암호 자격 증명이 올바르지 않은 경우에 발생합니다. 이 문제를 해결하려면 다음 단계를 수행합니다.
  1. 스택 세부정보 페이지의 변수 섹션으로 이동합니다.
  2. 사용자 이름 및 비밀번호 값을 수정하려면 변수 편집을 누릅니다.
  3. 올바른 정보로 인증서를 업데이트합니다.
  4. 적용을 눌러 스택을 재배치합니다.
배치 실패 - "거부됨: 익명 사용자는 공용 저장소에서만 읽기 액세스가 허용됩니다."
경우에 따라 다음 오류와 함께 배치가 실패할 수 있습니다.
denied: Anonymous users are only allowed read access on public repos

이는 스택 백엔드의 Docker 작업과 관련된 간헐적인 문제입니다. 특히 이 오류는 적절한 인증 없이 Docker 이미지를 Oracle Cloud Infrastructure Registry로 푸시하려고 시도할 때 발생합니다.

래퍼 API 패키지에는 이미지를 푸시하기 전에 적절한 인증을 보장하기 위해 docker login 명령을 실행하는 스크립트가 포함되어 있지만, 이 오류는 여전히 산발적으로 발생할 수 있습니다. 일반적으로 이미지 푸시 시 시스템에서 Docker 인증 단계를 제대로 인식하지 못할 때 발생합니다.

이 오류가 발생하면 다음 단계에 따라 문제를 해결하십시오.

  1. OCI 스택 리소스 관리자에서 삭제를 눌러 배치 프로세스 중 생성된 모든 리소스를 삭제합니다.
  2. 리소스가 삭제된 후 적용을 다시 눌러 스택을 재배치합니다. 그러면 적절한 Docker 인증을 포함하여 필요한 리소스가 만들어집니다.
일반 배치 실패: 간헐적인 문제
스택 배치는 임의의 Docker 관련 문제로 인해 실패할 수 있습니다. 이 경우 다음 단계에 따라 문제를 해결합니다.
  1. 실패한 배치 중 생성된 모든 리소스를 제거하려면 삭제를 누릅니다.
  2. 리소스가 삭제된 후 스택으로 돌아가서 적용을 눌러 스택을 재배치합니다.

이렇게 하면 간헐적인 문제를 해결하고 성공적으로 배치할 수 있습니다.