API Center 포털 자체 호스팅

이 문서에서는 조직의 개발자와 기타 관련자가 API 센터에서 API를 발견하는 데 사용할 수 있는 웹 사이트인 API Center 포털을 설명합니다. API Center 포털 시작 리포지토리에서 포털의 참조 구현을 배포합니다.

API Center 포털 정보

API Center 포털은 API 센터에 API 인벤토리를 표시하기 위해 빌드하고 호스팅할 수 있는 웹 사이트입니다. 포털을 사용하면 조직의 개발자와 기타 관련자가 API를 발견하고 API 세부 정보를 볼 수 있습니다.

API Center 포털 시작 리포지토리의 코드를 사용하여 포털의 참조 구현을 빌드하고 배포할 수 있습니다. 포털은 Azure API Center 데이터 평면 API를 사용하여 API 센터에서 데이터를 검색합니다. API 정보에 대한 사용자 액세스는 Azure 역할 기반 액세스 제어를 기반으로 합니다.

API Center 포털 참조 구현은 다음을 제공합니다.

• GitHub Actions를 사용하여 고객 관리 API 포털을 게시하고 유지 관리하기 위한 프레임워크
• 고객이 필요에 맞게 수정하거나 확장할 수 있는 포털 플랫폼
• Azure Static Web Apps와 같은 서비스에 대한 배포를 포함하여 다양한 인프라에서 호스팅할 수 있는 유연성.

필수 조건

• Azure 구독의 API 센터입니다. 아직 API 센터를 만들지 않았다면 빠른 시작: API 센터 만들기를 참조하세요.

• Azure 구독과 연결된 Microsoft Entra 테넌트에서 앱 등록을 만들 수 있는 권한 및 API 센터의 데이터에 대한 액세스 권한을 부여할 수 있는 권한입니다.

• 포털을 빌드하고 배포하려면 GitHub 계정이 필요하고 로컬 컴퓨터에 다음 도구가 설치되어 있어야 합니다.

  • Node.js 및 npm
  • Vite 패키지

Microsoft Entra 앱 등록 만들기

먼저 Microsoft Entra ID 테넌트에서 앱 등록을 구성합니다. 앱을 등록하면 API 센터 포털에서 로그인한 사용자를 대신하여 API 센터의 데이터에 액세스할 수 있습니다.

1. Azure Portal에서 Microsoft Entra ID>앱 등록으로 이동합니다.

2. + 새 등록을 선택합니다.

3. 응용 프로그램 등록 페이지에서 다음과 같이 값을 설정하세요.

   • 이름을 api-center-portal과 같은 의미 있는 이름으로 설정합니다.

   • 지원되는 계정 유형에서 이 조직 디렉터리의 계정(단일 테넌트)을 선택합니다.

   • 리디렉션 URI에서 SPA(단일 페이지 애플리케이션)를 선택하고 URI를 설정합니다.

     • 로컬 테스트의 경우 URI를 https://localhost:5173으로 설정합니다.
     • 프로덕션의 경우 URI를 API Center 포털 배포의 URI로 설정합니다.

   • 등록을 선택합니다.

4. 개요 페이지에서 애플리케이션(클라이언트) ID와 디렉터리(테넌트) ID를 복사합니다. 포털을 빌드할 때 이러한 값을 설정합니다.

5. API 사용 권한 페이지에서 + 사용 권한 추가를 선택합니다.

   1. API 권한 요청 페이지에서 내 조직에서 사용하는 API 탭을 선택합니다. Azure API 센터를 검색하고 선택합니다. 애플리케이션 ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573을 검색하고 선택할 수도 있습니다.
   2. 권한 요청 페이지에서 user_impersonation을 선택합니다.
   3. 권한 추가를 선택합니다.

   Azure API 센터 권한은 구성된 권한 아래에 표시됩니다.

   

로컬 환경 구성

API Center 포털을 로컬로 빌드하고 테스트하려면 다음 단계를 따릅니다.

1. API Center 포털 시작 리포지토리를 로컬 컴퓨터에 복제합니다.

   git clone https://github.com/Azure/APICenter-Portal-Starter.git
   

2. APICenter-Portal-Starter 디렉터리로 변경합니다.

   cd APICenter-Portal-Starter
   

3. main 분기를 체크 아웃합니다.

   git checkout main
   

4. 서비스를 구성하려면 public/config.example 파일을 복사하거나 이름을 public/config.json으로 바꿉니다.

5. 그런 다음 서비스를 가리키도록 public/config.json 파일을 편집합니다. 파일의 값을 다음과 같이 업데이트합니다.

   • <service name> 및 <region>을 API 센터 이름과 배포된 지역으로 변경
   • <client ID> 및 <tenant ID>를 이전 섹션에서 만든 앱 등록의 애플리케이션(클라이언트) ID 및 디렉터리(테넌트) ID로 바꿉니다.
   • 포털에 표시하려는 이름으로 title 값을 업데이트합니다.

   {
     "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms/workspaces/default",
     "title": "API portal",
     "authentication": {
         "clientId": "<client ID>",
         "tenantId": "<tenant ID>",
         "scopes": ["https://azure-apicenter.net/user_impersonation"],
         "authority": "https://login.microsoftonline.com/"
     }
   }
   

6. 필요한 패키지를 설치합니다.

   npm install
   

7. 개발 서버를 시작합니다. 다음 명령은 로컬로 실행되는 개발 모드에서 포털을 시작합니다.

   npm start
   

   https://localhost:5173에서 포털을 찾습니다.

Azure에 배포

Azure Static Web Apps에 포털을 배포하는 단계는 API Center 포털 시작 리포지토리를 참조하세요.

Microsoft Entra 사용자 및 그룹의 포털 로그인 사용

API 센터에서 API를 보려면 사용자가 로그인해야 합니다. 로그인을 사용하도록 설정하려면 API 센터로 범위가 할당된 조직의 사용자 또는 그룹에 Azure API 센터 데이터 읽기 권한자 역할을 할당합니다.

사용자 및 그룹에 역할을 할당하기 위한 자세한 필수 조건과 단계는 Azure Portal을 사용하여 Azure 역할 할당을 참조하세요. 간단한 단계는 다음과 같습니다.

1. Azure Portal에서 API 센터로 이동합니다.
2. 왼쪽 메뉴에서 액세스 제어(IAM)>+역할 할당 추가를 선택합니다.
3. 역할 할당 추가 창에서 다음과 같이 값을 설정합니다.
   • 역할 페이지에서 Azure API 센터 데이터 읽기 권한자를 검색하여 선택합니다. 다음을 선택합니다.
   • 멤버 페이지의 액세스 할당에서 사용자, 그룹 또는 서비스 주체>+ 멤버 선택을 선택합니다.
   • 멤버 선택 페이지에서 역할을 할당할 사용자 또는 그룹을 검색하고 선택합니다. 선택을 클릭한 후 다음을 클릭합니다.
   • 역할 할당을 검토하고 검토 + 할당을 선택합니다.

포털에 대한 액세스를 구성한 후 구성된 사용자는 포털에 로그인하고 API 센터에서 API를 볼 수 있습니다.

문제 해결

오류: "이 포털에 액세스할 권한이 없습니다."

특정 조건에서 사용자는 구성된 사용자 계정으로 API 센터 포털에 로그인한 후 다음과 같은 오류 메시지가 나타날 수 있습니다.

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

먼저 API 센터에서 사용자에게 Azure API 센터 데이터 읽기 권한자 역할이 할당되었는지 확인합니다.

사용자에게 역할이 할당된 경우 구독에서 Microsoft.ApiCenter 리소스 공급자를 등록하는 데 문제가 있을 수 있으며 리소스 공급자를 다시 등록해야 할 수도 있습니다. 이렇게 하려면 Azure CLI에서 다음 명령을 실행합니다.

az provider register --namespace Microsoft.ApiCenter

포털에 로그인할 수 없음

Azure API Center 데이터 읽기 권한자 역할이 할당된 사용자가 API Center 포털에서 로그인을 선택한 후 로그인 흐름을 완료할 수 없는 경우 Microsoft Entra ID의 ID 공급자 구성에 문제가 있을 수 있습니다.

Microsoft Entra 앱 등록에서 리디렉션 URI 설정을 검토하고 필요한 경우 업데이트하여 URI가 API Center 포털 배포의 URI와 일치하는지 확인합니다.

Microsoft Entra 앱 등록에서 Azure API 센터 권한을 선택할 수 없습니다.

API 센터 포털에 대한 Microsoft Entra 앱 등록에서 Azure API 센터에 대한 API 권한을 요청할 수 없는 경우 Azure API 센터(또는 애플리케이션 ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573)를 검색하고 있는지 확인합니다.

앱이 없으면 구독에 Microsoft.ApiCenter 리소스 공급자를 등록하는 데 문제가 있을 수 있습니다. 리소스 공급자를 다시 등록해야 할 수도 있습니다. 이렇게 하려면 Azure CLI에서 다음 명령을 실행합니다.

az provider register --namespace Microsoft.ApiCenter

리소스 공급자를 다시 등록한 후 API 권한을 다시 요청해 보세요.

지원 정책

API Center 포털 시작 리포지토리에서 API Center 포털 참조 구현에 대한 피드백을 제공하고, 기능을 요청하고, 지원을 받습니다.

관련 콘텐츠

• Azure RBAC(역할 기반 액세스 제어)란?
• Azure RBAC 사용 모범 사례
• 리소스 공급자 등록