API 센터 포털 자체 호스팅

이 문서에서는 개발자와 조직의 다른 이해 관계자가 API 센터에서 API를 검색하는 데 사용할 수 있는 웹 사이트인 API 센터 포털을 자체 호스팅하는 방법을 보여 줍니다. API Center 포털 시작 리포지토리에서 포털의 참조 구현을 배포합니다.

포털 자체 호스팅 정보

API Center 포털 시작 리포지토리의 코드를 사용하여 포털의 참조 구현을 빌드하고 배포할 수 있습니다. 포털은 Azure API Center 데이터 평면 API 를 사용하여 API 센터에서 데이터를 검색합니다.

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 센터의 데이터에 액세스할 수 있습니다.

API 센터는 앱 등록을 자동으로 설정하거나 수동으로 앱 등록을 만들 수 있습니다.

자동으로 앱 등록 설정

앱 등록을 자동으로 설정하려면 다음 단계를 수행합니다.

1. Azure Portal에서 API 센터로 이동합니다.
2. 왼쪽 메뉴에서 API 센터 포털>설정을 선택합니다.
3. ID 공급자 탭에서 설정 시작을 선택합니다.
4. 빠른 설정 탭에서 저장 + 게시를 선택합니다.

나중에 앱 등록에 액세스해야 하는 경우 앱 등록 아래 포털에서 찾을 수 있습니다. 애플리케이션의 이름은 <api-center-name-apic-aad> 형식으로 지정됩니다.

수동으로 앱 등록 설정

앱 등록을 수동으로 만들려면 다음 단계를 수행합니다.

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

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

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

   1. api-center-portal과 같은 의미 있는 이름으로 이름 설정
   2. 지원되는 계정 유형에서 이 조직 디렉터리의 계정만(<디렉터리 이름> - 단일 테넌트)을 선택합니다.
   3. 리디렉션 URI에서 SPA(단일 페이지 애플리케이션)를 선택하고 URI를 설정합니다. API Center 포털 배포의 URI를 다음 형식 https://<service-name>.portal.<location>.azure-apicenter.ms으로 입력합니다. <service name> 및 <location>를 API 센터의 이름과 배포 위치로 교체하십시오. 예: https://myapicenter.portal.eastus.azure-apicenter.ms.
   4. 등록을 선택합니다.

VS Code 확장에 대한 추가 리디렉션 URI 구성

API Center용 Visual Studio Code 확장에서 API Center 포털 보기를 사용하도록 설정하는 경우 앱 등록에서 다음 리디렉션 URI도 구성합니다.

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

2. 인증> 페이지에서 플랫폼 추가를 선택하고 모바일 및 데스크톱 애플리케이션을 선택합니다.

3. 다음 세 가지 사용자 지정 리디렉션 URI를 구성합니다.
   https://vscode.dev/redirect
http://localhost
ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>
   

   이 앱의 애플리케이션(클라이언트) ID로 바꿉니다 <application-client-id> . 앱 등록의 개요 페이지에서 이 값을 찾을 수 있습니다.

로컬 환경 구성

다음 단계에 따라 API 센터 포털을 로컬로 빌드하고 테스트합니다.

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

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

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

   cd APICenter-Portal-Starter
   

3. 주 분기를 확인합니다.

   git checkout main
   

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

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

   1. <service name> 및 <location>을 API Center 이름과 배포 위치로 바꾸기
   2. <client ID> 및 <tenant ID>를 이전 섹션에서 만든 앱 등록의 애플리케이션(클라이언트) ID 및 디렉터리(테넌트) ID로 바꿉니다.
   3. 포털의 title 위쪽 표시줄에 표시할 이름으로 값을 업데이트합니다.

   {
     "dataApiHostName": "<service name>.data.<location>.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 센터 포털 시작 리포지토리를 참조하세요.

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

API 센터 포털에 로그인하여 API에 액세스할 수 있도록 하려면 API 센터로 범위가 지정된 조직의 사용자 또는 그룹에 Azure API 센터 데이터 읽기 권한자 역할을 할당합니다.

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

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

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

문제 해결

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

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

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 Center 포털에 대한 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 센터 포털 참조 구현에 대한 지원을 받습니다.

관련 콘텐츠

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