서버리스 개발자 포털을 사용하여 API Gateway API를 목록화하십시오 - Amazon API Gateway

서버리스 개발자 포털을 사용하여 API Gateway API를 목록화하십시오

개발자 포털은 API를 고객에게 제공하기 위해 사용되는 애플리케이션입니다. 서버리스 개발자 포털을 사용하여 API Gateway 관리형 API를 API Gateway에서 직접 게시할 수 있습니다. 또한 API에 대한 OpenAPI 정의를 업로드하여 API Gateway 관리형이 아닌 API를 게시하는 데 사용할 수도 있습니다. 고객은 서버리스 개발자 포털에 API를 게시할 때 다음 작업을 쉽게 수행할 수 있습니다.

  • 사용 가능한 API를 검색합니다.

  • API 설명서를 찾아봅니다.

  • 애플리케이션을 빌드하는 데 사용할 수 있는 자체 API 키를 등록하면 —즉시 받을 수 있습니다—.

  • 개발자 포털 UI에서 API를 사용해 보십시오.

  • 자체 API 사용을 모니터링합니다.

Amazon API Gateway는 정기적으로 업데이트되는 서버리스 개발자 포털 애플리케이션을 AWS Serverless Application RepositoryGitHub에 게시합니다. Apache 2.0 라이선스에 따라 릴리스되므로 빌드 및 배포 도구에 맞게 사용자 지정 및 통합할 수 있습니다. 프런트 엔드는 React에서 작성되었으며 완벽하게 사용자 지정 가능하도록 설계되었습니다. https://github.com/awslabs/aws-api-gateway-developer-portal/wiki/Customization을 참조하십시오.

AWS Serverless Application Repository에 대한 자세한 내용은 AWS Serverless Application Repository 개발자 안내서 단원을 참조하십시오.

작은 정보

개발자 포털의 예제를 사용하려면 https://developer.exampleapigateway.com/을 참조하십시오.

개발자 포털 생성

원본 그대로 API Gateway 서버리스 개발자 포털을 배포하거나 브랜드에 맞게 사용자 지정할 수 있습니다. 개발자 포털을 배포하는 방법은 두 가지가 있습니다.

  • AWS Serverless Application Repository를 사용합니다. 배포 버튼을 선택하여 API Gateway 서버리스 개발자 포털 AWS CloudFormation 스택을 시작하고 Lambda 콘솔에 몇 가지 스택 파라미터를 입력합니다.

  • AWS GitHub 리포지토리에서 API Gateway 서버리스 개발자 포털을 다운로드하고, AWS SAM CLI에서 API Gateway 서버리스 개발자 포털 AWS CloudFormation 스택을 시작합니다.

AWS Serverless Application Repository을 사용하여 서버리스 개발자 포털을 배포하려면

  1. AWS Serverless Application Repository에서 API Gateway 서버리스 개발자 포털 페이지로 이동합니다.

  2. 배포를 선택합니다.

    참고

    AWS Lambda 콘솔에 로그인하라는 메시지가 표시될 수 있습니다.

  3. Lambda 콘솔의 애플리케이션 설정에서 필요한 개발자 포털 스택 파라미터를 입력합니다.

    참고

    S3 버킷 이름과 Amazon Cognito 도메인 접두사는 필수이며, 다른 설정은 선택 사항입니다.

  4. Got an opinion?(의견 듣기) 고객 피드백 버튼을 활성화하려면 다음과 같이 해야 합니다.

    • DevPortalAdminEmail 상자에 이메일 주소를 입력합니다. 고객이 피드백을 제출하면 이 주소로 이메일이 전송됩니다.

      참고

      이메일 주소를 제공하지 않으면 개발자 포털에 Got an opinion?(의견 듣기)이 나타나지 않습니다.

    • 원할 경우, DevPortalFeedbackTableName 상자에 테이블 이름을 입력할 수 있습니다. 기본 이름은 DevPortalFeedback입니다. 고객이 피드백을 제출할 경우 DynamoDB 테이블에 이 이름으로 저장됩니다.

  5. 이 앱이 사용자 지정 IAM 역할 및 리소스 정책을 생성하는 것을 확인 옆 확인란을 선택합니다.

  6. 배포를 선택합니다.

  7. AdminEmail 스택 파라미터에 이메일 주소를 입력한 경우 Amazon SNS 구독 이메일이 해당 이메일 주소로 전송됩니다. 이 이메일은 MarketplaceSubscriptionTopicProductCode 설정에서 지정한 Amazon SNS 주제에 대한 구독을 확인합니다.

AWS SAM을 사용하여 서버리스 개발자 포털을 다운로드하고 배포하려면

  1. 최신 AWS CLI and AWS SAM CLI를 설치하고 구성하였는지 확인하십시오.

  2. API Gateway 서버리스 개발자 포털 리포지토리를 다운로드하거나 복제합니다.

  3. 압축된 Lambda 함수를 업로드할 수 있는 프라이빗 Amazon S3 버킷이 있는지 확인하십시오. 아직 없는 경우 Amazon S3 콘솔 또는 CLI를 사용하여 생성할 수 있습니다.

    AWS SAM CLI의 경우, 프로젝트 루트에서 다음 명령을 실행하여 {your-lambda-artifacts-bucket-name}을 Amazon S3 버킷 이름으로 바꿉니다.

    sam package --template-file ./cloudformation/template.yaml \ --output-template-file ./cloudformation/packaged.yaml \ --s3-bucket {your-lambda-artifacts-bucket-name}
  4. 이 단계의 경우, --parameter-overrides를 따르는 파라미터(예: CognitoDomainNameOrPrefix)에 대한 자세한 내용은 개발자 포털 설정 단원을 참조하십시오.

    참고

    AWS SAM 템플릿을 업로드할 수 있는 프라이빗 Amazon S3 버킷이 있는지 확인하십시오(AWS CloudFormation은 개발자 포털을 배포하기 위해 버킷에서 템플릿을 읽음). 이 버킷은 압축된 Lambda 함수를 업로드하기 위해 이전 단계에서 지정한 버킷일 수 있습니다.

    프로젝트 루트에서 다음 명령을 실행하여 다음과 같이 변경합니다.

    • {your-template-bucket-name}을 Amazon S3 버킷 이름으로 바꿉니다.

    • {custom-prefix}를 전역적으로 고유한 접두사로 바꿉니다.

    • {cognito-domain-or-prefix}를 고유한 문자열로 바꿉니다.

    sam deploy --template-file ./cloudformation/packaged.yaml \ --s3-bucket {your-template-bucket-name} \ --stack-name "{custom-prefix}-dev-portal" \ --capabilities CAPABILITY_NAMED_IAM \ --parameter-overrides CognitoDomainNameOrPrefix= "{cognito-domain-or-prefix}" DevPortalSiteS3BucketName="{custom-prefix}-dev-portal-static-assets" ArtifactsS3BucketName="{custom-prefix}-dev-portal-artifacts"

개발자 포털이 완전히 배포되고 나면 다음과 같이 URL을 가져올 수 있습니다.

새로 생성된 개발자 포털의 URL을 얻으려면

  1. AWS CloudFormation 콘솔을 엽니다.

  2. 스택 이름(기본 스택 이름은 aws-serverless-repository-api-gateway-dev-portal)을 선택합니다.

  3. Outputs 섹션을 여십시오. 개발자 포털의 URL은 WebsiteURL 속성에 지정되어 있습니다.

개발자 포털 설정

다음은 개발자 포털의 배포 과정과 배포 이후에 필요한 설정입니다.

참고

개발자 포털을 배포한 후 AWS CloudFormation 스택을 업데이트하여 아래의 많은 설정을 변경할 수 있습니다. 자세한 내용은 AWS CloudFormation 스택 업데이트를 참조하십시오.

ArtifactsS3BucketName(REQUIRED)

배포 프로세스에서 카탈로그 메타데이터가 저장되는 비공개 액세스 Amazon S3 버킷을 생성합니다. 버킷에 사용할 이름을 지정합니다. 이 이름은 전역적으로 고유해야 합니다.

CognitoDomainNameOrPrefix(REQUIRED)

이 문자열은 사용자 등록 및 로그인을 위한 Amazon Cognito 호스팅 UI에 사용됩니다. 고유한 도메인 이름이나 접두사 문자열을 지정합니다.

CognitoIdentityPoolName

배포 프로세스에서 Amazon Cognito 자격 증명 풀을 생성합니다. 자격 증명 풀의 기본 이름은 DevPortalIdentityPool입니다.

CustomDomainNameAcmCertArn

ACM 인증서와 연결된 도메인 이름을 제공한 경우 여기에 ACM 인증서의 ARN도 지정해야 합니다. 고객 도메인 이름 없이 개발자 포털을 생성하려면 빈 칸으로 둡니다.

DevPortalAdminEmail

Got an opinion(의견 듣기)? 고객 피드백 버튼을 활성화하려면 이메일 주소를 지정합니다. 고객이 피드백을 제출하면 이 주소로 이메일이 전송됩니다.

참고

이메일 주소를 제공하지 않으면 개발자 포털에 Got an opinion?(의견 듣기) 버튼이 나타나지 않습니다.

DevPortalFeedbackTableName

DevPortalAdminEmail에서 이메일 주소를 지정하면 배포 프로세스에서 고객이 입력한 피드백을 저장할 DynamoDB 테이블을 생성합니다. 기본 이름은 DevPortalFeedback입니다. 사용자가 직접 테이블 이름을 지정할 수도 있습니다.

DevPortalCustomersTableName

배포 프로세스에서 고객 계정이 저장되는 DynamoDB 테이블을 생성합니다. 이 테이블에 할당할 이름을 지정할 수도 있습니다(선택 사항). 이름은 계정 리전 내에서 고유해야 합니다. 테이블의 기본 이름은 DevPortalCustomers입니다.

DevPortalSiteS3BucketName(REQUIRED)

배포 프로세스에서 웹 애플리케이션 코드가 저장될 비공개 액세스 Amazon S3 버킷을 생성합니다. 이 버킷에 사용할 이름을 지정합니다. 이 이름은 전역적으로 고유해야 합니다.

MarketplaceSubscriptionTopicProductCode

이벤트 구독/구독 취소를 위한 Amazon SNS 주제 접두사입니다. 원하는 값을 입력합니다. 기본값은 DevPortalMarketplaceSubscriptionTopic입니다. 이 설정은 AWS Marketplace 통합을 사용할 경우에만 적용됩니다. 자세한 내용은 신규 고객을 수락하도록 SaaS 제품 구성을 참조하십시오.

StaticAssetRebuildMode

정적 애셋을 재빌드할 경우 기본적으로 사용자 지정 콘텐츠를 덮어쓰지 않습니다. overwrite-content를 지정하여 사용자 지정 콘텐츠를 해당 로컬 버전으로 바꿉니다.

중요

overwrite-content를 지정할 경우 Amazon S3 버킷의 모든 사용자 지정 변경 사항이 손실됩니다. 확실하지 않은 한 이렇게 하지 마십시오.

StaticAssetRebuildToken

개발자 포털 사이트의 정적 애셋을 다시 업로드하려면 이전 배포의 토큰과 다른 토큰을 제공하십시오. 각 배포에 타임스탬프나 GUID를 제공하여 항상 애셋을 다시 업로드하십시오.

UseRoute53Nameservers

개발자 포털에 대한 사용자 지정 도메인 이름을 생성할 경우에만 적용됩니다. Route 53 HostedZone 및 RecordSet를 생성을 건너뛰려면 true를 지정합니다. Route 53 대신에 자체 이름 서버 호스팅을 제공해야 합니다. 제공하지 않으려면, 이 필드를 false 설정으로 두십시오.

개발자 포털의 관리자 생성

개발자 포털을 배포한 후 관리 사용자를 한 명 이상 생성합니다. 새 사용자를 생성하고, 개발자 포털을 배포할 때 AWS CloudFormation이 생성한 Amazon Cognito 사용자 풀의 관리자 그룹에 이 사용자를 추가하면 됩니다.

관리 사용자 생성

  1. 개발자 포털에서 등록을 선택합니다.

  2. 이메일 주소와 암호를 입력하고 등록을 선택하십시오.

  3. 새로운 브라우저 탭에서 Amazon Cognito 콘솔에 로그인합니다.

  4. Manage User Pools(사용자 풀 관리)를 선택합니다.

  5. 개발자 포털을 배포할 때 설정한 개발자 포털을 위한 사용자 풀을 선택합니다.

  6. 관리자로 승격시킬 사용자를 선택합니다.

  7. 그룹에 추가를 선택합니다.

  8. 드롭다운 메뉴에서 {stackname}-dev-portalAdminsGroup을 선택합니다. {stackname}은 개발자 포털을 배포했던 스택 이름입니다.

  9. 그룹에 추가를 선택합니다.

  10. 개발자 포털에서 로그아웃한 후 동일한 자격 증명을 사용하여 다시 로그인합니다. 상단 오른쪽 모서리 부분의 My Dashboard(내 대시보드) 옆에 Admin Panel(관리자 패널) 링크가 나타납니다.

개발자 포털의 사용자 관리

관리 사용자로 로그인한 후 관리자 패널계정 섹션을 사용하여 사용자를 관리할 수 있습니다. 관리 사용자는 개발자 포털에서 새 사용자를 초대하고, 사용자를 삭제하고, 기존 사용자를 관리자 상태로 승격할 수 있습니다.

개발자 포털에 API Gateway 관리형 API 게시

다음 단계에서는 API 소유자로서 API를 개발자 포털에 게시하여 고객이 구독할 수 있도록 하는 방법을 간략하게 설명합니다.

1단계: API Gateway 관리형 API가 게시에 사용할 수 있게 만들기

  1. 스테이지에 API를 배포하지 않았다면 이를 수행합니다.

  2. 사용량 계획을 생성하여 배포된 API를 위한 API 스테이지에 연결하지 않았다면 이를 수행합니다.

    참고

    API 키를 사용량 계획과 연결할 필요는 없습니다. 개발자 포털이 사용자를 대신해 이 작업을 수행합니다.

  3. 개발자 포털에 로그인한 후 Admin Panel(관리자 패널)로 이동합니다.

  4. 관리자 패널 API 목록에 해당 API가 나타납니다. API 목록에서 API는 사용량 계획별로 그룹화됩니다. Not Subscribable(구독 불가) No Usage Plan(사용량 계획 없음) 그룹에는 사용량 계획과 연결되지 않은 API의 목록이 표시됩니다.

2단계: API Gateway 관리형 API를 개발자 포털에 표시되게 하기

  1. Admin Panel(관리자 패널) API 목록에서 해당 API의 Displayed(표시됨) 값을 선택합니다. 처음으로 업로드하는 경우, 이 값이 False로 설정됩니다.

  2. 개발자 포털에서 API가 표시되게 하려면 False 버튼을 선택합니다. 이 값이 True로 변경되면 이제 API가 표시된다는 뜻입니다.

    작은 정보

    사용량 계획의 모든 API가 표시되게 하려면 사용량 계획의 제목 줄에서 False 또는 Partial(일부) 버튼을 누릅니다.

  3. API 패널로 이동한 후 고객이 보는 개발자 포털을 확인합니다. 왼쪽 탐색 열에 API가 표시되어야 합니다.

    사용량 계획과 연결된 스테이지에 API가 배포된 경우, API에 대해 구독 버튼이 표시됩니다. 이 버튼은 고객의 API 키를, 해당 API와 연결된 사용량 계획에 연결합니다.

이제 API Gateway 관리형 API가 표시되고, SDK 생성을 활성화하여 고객이 해당 SDK를 다운로드하게 할 수 있습니다.

3단계: SDK 생성 활성화

  1. Admin Panel(관리자 패널) API l목록에서 Disabled(비활성화됨) 버튼을 선택합니다. 이 값이 Enabled로 변경되면 이제 SDK 생성이 허용된다는 뜻입니다.

  2. API 패널로 이동한 후 왼쪽 탐색 열에서 API를 선택합니다. 이제 SDK 다운로드 버튼과 API 내보내기 버튼이 표시됩니다.

API Gateway 관리형 API를 업데이트 또는 삭제

API를 게시한 후 API Gateway에서 변경한 경우에는 다시 배포해야 합니다.

API Gateway 관리형 API를 업데이트하려면

  1. API Gateway 콘솔, AWS CLI 또는 SDK에서 API를 원하는 대로 변경합니다.

  2. 앞에서와 같이, API를 동일한 단계에 다시 배포합니다.

  3. 개발자 포털의 Admin Panel(관리자 패널) API 목록에서 업데이트를 선택합니다. 그러면 개발자 포털 UI에 표시되는 API가 업데이트됩니다.

    참고

    SDK 다운로드 버튼은 개발자 포털에서 업데이트하지 않은 경우에도 항상 최신 버전의 API를 다운로드합니다.

  4. API 패널로 이동한 후 왼쪽 탐색 열에서 API를 선택합니다. 변경 사항이 나타납니다.

API에 대한 고객의 액세스 권한을 취소하지 않고 개발자 포털 API 목록에 API가 표시되는 것을 중지하려면 다음과 같이 합니다.

  1. Admin Panel(관리자 패널) API 목록에서 해당 API의 Displayed(표시됨) 값을 선택합니다. API가 표시될 경우 이 값은 True로 설정됩니다.

  2. API가 표시되지 않게 하려면 True 버튼을 선택합니다. 값이 False, 로 변경되면 이제 API가 표시되지 않는다는 뜻입니다.

  3. API 패널로 이동합니다. 왼쪽 탐색 열에 더 이상 API가 표시되지 않습니다.

API를 완전히 삭제하지 않고 API에 대한 고객의 액세스 권한을 취소하려면, API Gateway 콘솔이나 API Gateway CLI 또는 REST API에서 다음 중 하나를 수행해야 합니다.

  • 사용량 계획에서 API 키를 제거합니다.

  • 사용량 계획에서 API 단계를 제거합니다.

API Gateway 관리형이 아닌 API 제거

API Gateway 관리형이 아닌 API의 표시를 중지하고 이에 대한 고객의 액세스 권한을 제거하려면 삭제를 선택합니다. 이 삭제 작업은 API를 삭제하지는 않고 개발자 포털에서 해당 API의 OpenAPI 사양 파일을 삭제합니다.

개발자 포털에 API Gateway 관리형이 아닌 API 게시

다음 단계에서는 API Gateway 관리형이 아닌 "일반" API를 고객에게 게시하는 방법을 간략하게 설명합니다. API에 대한 OpenAPI 2.0(Swagger) 또는 3.x 정의를 JSON, YAML 또는 YML 파일로 업로드할 수 있습니다.

개발자 포털에서 API Gateway 관리형이 아닌 API를 게시하려면

  1. 개발자 포털에 로그인한 후 Admin Panel(관리자 패널)로 이동합니다.

  2. Generic APIs(일반 API)에서 Add API(API 추가)를 선택합니다.

  3. 해당 API에 대한 OpenAPI 파일이 위치한 디렉터리를 찾아서 업로드할 파일을 선택합니다.

  4. [Upload]를 선택합니다.

    참고

    구문 분석을 할 수 없거나 API 제목을 포함하지 않는 파일이 있으면 경고가 표시되고, 이러한 파일은 업로드되지 않습니다. 다른 모든 파일은 업로드됩니다. 경고 대화 상자를 무시하려면 x 아이콘을 선택해야 합니다.

  5. Generic APIs(일반 API) 아래에 해당 API가 나타납니다. Admin Panel(관리자 패널)에서 나왔다가 다시 돌아가서 목록을 새로 고칩니다.

고객이 개발자 포털을 사용하는 방법

애플리케이션을 빌드하고 API를 테스트하려면 고객이 개발자 포털에 등록하여 개발자 계정을 생성해야 합니다.

개발자 계정을 생성하고 API 키를 얻으려면

  1. 개발자 포털에서 등록을 선택하십시오.

  2. 이메일 주소와 암호를 입력하고 등록을 선택하십시오.

  3. API 키의 위치를 찾으려면 My Dashboard(내 대시보드)를 선택하십시오.

개발자 계정은 고객에게 API를 사용 및 테스트하는 데 필요한 API 키를 제공합니다. 따라서 귀하와 귀하의 고객 모두의 사용 현황을 추적할 수 있습니다.

고객이 처음 등록할 때 새 API 키는 사용자의 API에 결합할 수 없습니다.

API의 API 키를 활성화하려면

  1. API(APIs)를 선택합니다.

  2. API 목록에서 API를 선택하고 구독을 선택하십시오.

    그러면 API 키가, 해당 API와 연결된 사용량 계획에 연결됩니다.

고객은 이제 API를 구독하고 API의 메서드를 호출할 수 있습니다. API의 일일 사용량 통계는 MyDashboard(내 대시보드)에 표시됩니다.

고객은 구독하지 않고도 개발자 포털 UI에서 API 메서드를 사용해 볼 수 있습니다.

참고

API 키가 필요한 API 메서드가 있을 경우 메서드 목록 위에 승인 버튼이 나타납니다. API 키가 필요한 메서드에는 검은색 잠금 아이콘이 표시됩니다. API 키가 필요한 메서드를 사용하려면 승인 버튼을 선택하고 해당 API 단계에 대한 사용량 계획과 연결된 유효한 API 키를 입력합니다.

이미 구독한 API에 승인 버튼이 나타날 경우 무시해도 됩니다.

고객은 개발자 포털을 통해 고객 피드백을 제출할 수 있습니다.

고객의 피드백은 개발자 포털의 DynamoDB 테이블에 저장됩니다. 이 테이블의 기본 이름은 DevPortalFeedback입니다. 또한 DevPortalAdminEmail 필드에 지정된 이메일 주소로 이메일이 전송됩니다. 개발자 포털을 배포할 때 이메일 주소를 지정하지 않은 경우 Got an opinion?(의견 듣기) 버튼이 나타나지 않습니다.

참고

이 테이블의 이름을 변경할 경우 해당 계정 리전에서 고유한 이름을 사용해야 합니다.

관리자 패널에서 API에 대해 SDK 생성을 활성화한 경우 고객이 해당 API에 대한 SDK를 다운로드하고 API 정의를 내보낼 수 있습니다. 자세한 내용은 API Gateway에서 REST API에 대한 SDK 생성API Gateway에서 REST API 내보내기 단원을 참조하십시오.

개발자 포털 모범 사례

다음은 개발자 포털을 배포할 때 권장되는 모범 사례입니다.

  • 대부분의 경우 모든 API에 대해 하나의 개발자 포털만 배포하려 할 것입니다. 경우에 따라 해당 API의 개발 및 프로덕션 버전에 대해 별도의 개발자 포털을 선택할 수 있습니다. 프로덕션 API에서는 개발자 포털을 두 개 이상 사용하지 않는 것이 좋습니다.

  • 사용량 계획을 생성하여 단계와 연결할 경우 API 키를 사용량 계획과 연결할 필요는 없습니다. 개발자 포털이 사용자를 대신해 이 작업을 수행합니다.

  • 특정 사용량 계획의 API가 표시될 경우, 고객에게 표시하도록 설정하지 않았더라도 해당 사용량 계획의 모든 API가 구독 가능해야 합니다.