래퍼 API 배치

Oracle Blockchain Platform Digital Assets Edition을 사용하면 App Builder에서 생성한 체인코드 내의 모든 컨트롤러 API에 대한 래퍼 API를 생성할 수 있습니다. 이 항목에서는 스택 리소스 관리자에 래퍼 API 패키지를 배치하고 연관된 Postman 모음을 사용하여 래퍼 API를 테스트하기 위한 자세한 단계를 제공합니다.

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

1. <ChaincodeName>WrapperAPI.zip: 이 파일에는 Oracle Cloud Infrastructure Resource Manager에서 래퍼 API를 배포하는 데 필요한 Terraform 스크립트가 포함되어 있습니다.
2. <ChaincodeName>_WrapperAPI.postman_collection.json: 배치 후 래퍼 API를 테스트하는 데 사용되는 Postman 모음입니다.

래퍼 API를 배치하려면 OCI Resource Manager 내에서 WrapperAPI.zip 파일을 사용해야 합니다.

필요 조건

래퍼 API 패키지를 배치하기 위한 필요 조건은 다음과 같습니다.

• 래퍼 API 패키지는 App Builder를 사용하여 생성해야 합니다.
• 패키지는 래퍼 API에 필요한 모든 구성 변수 값과 끝점 값을 포함해야 합니다.

래퍼 API 패키지 배치

1. OCI에 로그인합니다.
   OCI 콘솔을 열고 https://cloud.oracle.com/에 사인인합니다.
   스택이 배치될 컴파트먼트에 있는지 확인하십시오.
2. 탐색 메뉴를 확장합니다. 개발자 서비스를 선택합니다. Resource Manager에서 Stacks를 선택합니다.
   스택에 대한 Resource Manager 인터페이스가 열립니다. Terraform 구성을 사용하여 기존 스택을 보고, 새 스택을 생성하고, 인프라를 코드형으로 관리할 수 있습니다.
3. 스택 생성을 눌러 새 스택을 생성합니다.
4. 스택 정보를 구성합니다.
   1. Terraform 구성 섹션에서 내 구성을 선택합니다.
   2. 스택 구성, Terraform 구성 소스에서 .Zip 파일을 선택합니다.
   3. 찾아보기를 누르고 래퍼 API Zip 파일로 이동합니다.
   4. 업로드가 완료되면 스택 이름이 올바른지 확인하십시오.
   5. 나머지 설정은 모두 기본값으로 유지할 수 있습니다. 다음을 누르십시오.
5. 스택 변수를 구성합니다.
   1. 모든 구성 변수 값이 정확한지 확인하고 배치 요구사항을 충족하도록 래퍼 API 패키지에 지정된 구성 변수에 맞춰 조정하십시오.
   2. ocir_user_name의 경우 OCI 계정과 연관된 전자메일 주소를 입력합니다.
   3. ocir_user_password에 대해 Oracle Cloud Infrastructure 인증 토큰인 비밀번호를 입력합니다. 이 토큰은 OCI 콘솔에서 사용자 설정으로 생성할 수 있습니다. 인증 토큰은 OCIR(Oracle Cloud Infrastructure Registry)에 로그인하기 위한 암호 역할을 합니다.
      인증 토큰 생성에 대한 자세한 내용은 인증 토큰 생성을 참조하십시오.
   4. 나머지 설정은 모두 기본값으로 유지할 수 있습니다. 다음을 누르십시오.
6. 스택 정보를 검토합니다. 모든 항목이 올바른 경우 생성을 누릅니다.
7. Terraform 계획을 실행합니다.
   1. 스택의 세부정보 페이지에서 계획을 눌러 실행 계획 생성을 시작합니다.
   2. 선택적으로 작업 계획을 구성합니다. 기본 이름을 편집하거나 고급 옵션을 선택하여 조정 설정의 제공자 버전을 변경할 수 있습니다.
   3. 계획을 눌러 계획 작업을 생성하고 실행합니다.
      그러면 Terraform 구성의 구문이 분석되고, 실행 계획이 생성되고, 다음 작업을 수행하는 계획이 실행됩니다.

      • 구문 또는 구성 오류가 없는지 확인하기 위해 Terraform 스크립트를 검증합니다.
      • 실제 기반 구조를 변경하지 않고 리소스 생성 프로세스를 시뮬레이트합니다.
      • 스크립트가 만들거나 수정 또는 삭제하려는 리소스를 나열하는 출력 요약을 제공합니다.
   4. 스택의 작업 섹션에서 상태를 모니터링합니다. 계획이 성공적으로 완료되면 출력을 검토하여 생성될 리소스 수를 확인하고 문제가 없는지 확인합니다.
8. 스택에 Terraform 계획을 적용합니다.
   1. 스택의 세부정보 페이지에서 적용을 누릅니다.
   2. Terraform [적용] 패널에서 적용을 누릅니다.
      이렇게 하면 다음이 수행됩니다.

      • Terraform 스크립트에 정의된 대로 다음 리소스를 모두 프로비전합니다.
        • VCN(가상 클라우드 네트워크)
        • 애플리케이션(OCI 함수)
        • API 게이트웨이
        • API 배치
        • IAM 정책
        • OCI 레지스트리 저장소
      • 래퍼 API에 필요한 인프라를 모두 생성합니다.
   3. 스택의 Jobs 섹션에서 상태를 모니터하여 작업이 오류 없이 성공적으로 완료되었는지 확인합니다.
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 컬렉션의 모든 변수를 구성합니다. api_gateway_endpoint 값은 동적으로 생성된 게이트웨이 끝점이 제공될 OCI의 스택 배치 출력에서 가져와야 합니다.

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

그림 6-1 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 이미지를 OCIR(Oracle Cloud Infrastructure Registry)로 푸시하려고 할 때 발생합니다.

래퍼 API 패키지에는 이미지를 푸시하기 전에 docker login를 수행하는 스크립트가 포함되어 있지만 이 오류는 계속 산발적으로 발생할 수 있습니다. 일반적으로 Docker 인증 단계가 이미지 푸시 시 시스템에서 제대로 인식되지 않는 경우에 발생합니다.

이 오류가 발생하면 다음 단계를 수행하여 문제를 해결하십시오.

1. 기존 리소스 삭제:

   OCI 스택 리소스 관리자에서 삭제를 눌러 배치 프로세스 중 생성된 모든 리소스를 삭제합니다.

2. 스택 재적용:

   리소스를 삭제한 후 적용을 다시 눌러 스택을 재배치합니다. 그러면 적절한 Docker 인증을 포함하여 필요한 리소스가 생성되고 문제가 해결됩니다.

일반 배치 실패: 간헐적인 문제

임의의 유사 도커 관련 문제로 인해 스택 배치가 실패할 수 있습니다. 이 경우 다음 단계에 따라 문제를 해결하십시오.

1. 실패한 배치 중 생성된 모든 리소스를 제거하려면 삭제를 누릅니다.
2. 리소스가 삭제되면 스택으로 돌아가서 적용을 눌러 스택을 재배치합니다.

이 프로세스는 간헐적인 문제를 해결하여 배포를 성공적으로 진행할 수 있도록 하는 경우가 많습니다.