API Management 개발자 포털 자체 호스팅

적용 대상: 개발자 | 기본 | 기본 v2 | 표준 | 표준 v2 | 프리미엄 | 프리미엄 v2

이 자습서에서는 API Management 개발자 포털을 자체 호스트하는 방법에 대해 설명합니다. 자체 호스팅은 개발자 포털의 기능을 확장하는 여러 옵션 중 하나입니다. 예를 들어 다양한 기능을 사용하여 API Management 인스턴스에 대해 여러 포털을 자체 호스팅할 수 있습니다. 포털을 자체 호스트하는 경우 사용자는 관리자가 되며 업그레이드를 담당하게 됩니다. 개발자 포털에서 콘텐츠를 관리하려면 API Management REST API가 필요합니다.

중요합니다

개발자 포털 코드베이스의 핵심을 수정해야 하는 경우에만 개발자 포털을 자체 호스팅하는 것을 고려합니다. 이 옵션을 사용하려면 다음을 포함한 고급 구성이 필요합니다.

가용성 및 성능 향상을 위해 CDN(콘텐츠 배달 네트워크)과 같은 솔루션에서 선택적으로 앞장서서 호스팅 플랫폼에 배포합니다.
호스팅 인프라 유지 관리 및 관리.
코드베이스를 업그레이드할 때 코드 충돌을 해결해야 할 수 있는 보안 패치를 포함한 수동 업데이트입니다.

비고

자체 호스팅 포털은 관리되는 개발자 포털에서 사용할 수 있는 표시 유형 및 액세스 제어를 지원하지 않습니다.

관리되는 포털에서 미디어 파일을 이미 업로드하거나 수정한 경우 이 문서의 뒷부 분에 있는 관리되는 파일에서 자체 호스팅으로 이동을 참조하세요.

필수 조건

로컬 개발 환경을 설정하려면 다음을 갖춰야 합니다.

API Management 서비스 인스턴스 없는 경우 빠른 시작 - Azure API Management 인스턴스 만들기를 참조하세요.

v2 서비스 계층에서 인스턴스를 만든 경우 먼저 개발자 포털을 사용하도록 설정합니다.
1. 사이드바 메뉴의 개발자 포털에서 포털 설정을 선택합니다.
2. 포털 설정 창에서 [사용]을 선택합니다. 저장을 선택합니다. 개발자 포털을 사용하도록 설정하는 데 몇 분 정도 걸릴 수 있습니다.
정적 웹 사이트 기능을 사용하도록 설정하는 데 사용할 Azure Blob Storage 계정입니다. 스토리지 계정 만들기를 참조하세요.
컴퓨터의 Git 이 Git 자습서에 따라 설치하세요.
Node.js(LTS(장기 지원) 버전 v10.15.0 이상) 및 npm이 컴퓨터에 설치되어 있어야 합니다. Node.js 및 npm 다운로드 및 설치를 참조하세요.
Azure CLI. Azure CLI 설치 단계를 수행합니다.
Microsoft Entra 앱 등록을 만들 수 있는 권한입니다.

1단계: 로컬 환경 설정

로컬 환경을 설정하려면 리포지토리를 복제하고, 개발자 포털의 최신 릴리스로 전환하고, npm 패키지를 설치합니다.

GitHub에서 api-management-developer-portal 리포지토리를 복제합니다.
```
git clone https://github.com/Azure/api-management-developer-portal.git
```
리포지토리의 로컬 복사본으로 이동합니다.
```
cd api-management-developer-portal
```
포털의 최신 릴리스를 체크 아웃합니다.

다음 코드를 실행하기 전에 리포지토리의 릴리스 섹션 에서 현재 릴리스 태그를 확인하고 <current-release-tag> 값을 최신 릴리스 태그로 바꿉니다.
```
git checkout <current-release-tag>
```
사용 가능한 npm 패키지를 설치합니다.
```
npm install
```

팁 (조언)

항상 최신 포털 릴리스를 사용하고 포크된 포털을 최신 상태로 유지하세요. API Management 개발 팀은 일일 개발 작업을 위해 이 저장소의 master 분기를 사용합니다. 이 리포지토리에는 불안정한 소프트웨어 버전이 있습니다.

2단계: JSON 파일, 정적 웹 사이트 및 CORS 설정 구성

config.design.json 파일

src 폴더로 이동하여 config.design.json 파일을 엽니다.

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

subscriptionId, resourceGroupName, serviceName에 구독, 리소스 그룹 및 서비스 이름 값을 API Management 인스턴스에 대해 입력합니다. I

config.design.json의 선택적 설정

필요에 따라 파일에서 config.design.json 다음 설정을 구성합니다.

개발자 포털에서 CAPTCHA를 활성화하려면 "useHipCaptcha": true를 설정합니다. 개발자 포털 백 엔드에 대한 CORS 설정을 구성해야 합니다.
```
{
    ...
    "useHipCaptcha": true
    ...
}
```
integration의 googleFonts에서 선택적으로 apiKey를 웹 글꼴 개발자 API에 대한 액세스를 허용하는 Google API 키로 설정합니다. 이 키는 개발자 포털 편집기의 스타일 섹션에 Google 글꼴을 추가하려는 경우에만 필요합니다.
```
{
    ...
    "integration": {
        "googleFonts": {
            "apiKey": "< your Google API key >"
        }
    }
    ...
}
```
아직 키가 없으면 Google Cloud 콘솔을 사용하여 구성할 수 있습니다. 다음 단계를 수행하세요.
1. Google Cloud 콘솔을 엽니다.
2. 웹 글꼴 개발자 API가 사용하도록 설정되어 있는지 확인합니다. 그렇지 않은 경우 사용하도록 설정합니다.
3. 자격 증명 만들기>API 키를 선택합니다.
4. 열린 대화 상자에서 생성된 키를 복사하여 apiKey 파일의 config.design.json 값으로 붙여넣습니다.
5. API 키 편집을 선택하여 키 편집기를 엽니다.
6. 편집기의 API 제한에서 키 제한을 선택합니다. 드롭다운에서 웹 글꼴 개발자 API를 선택합니다.
7. 저장을 선택합니다.

config.publish.json 파일

src 폴더로 이동하여 config.publish.json 파일을 엽니다.

{
    "environment": "publishing",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

이전 구성 파일의 subscriptionId값 resourceGroupName및 serviceName 값을 복사하여 붙여넣습니다.

config.runtime.json 파일

src 폴더로 이동하여 config.runtime.json 파일을 엽니다.

{
    "environment": "runtime",
    "backendUrl": "https://< service name >.developer.azure-api.net"
}

< service name > 이전 구성 파일에 사용된 API Management 인스턴스의 이름으로 대체합니다.

정적 웹 사이트 구성

인덱스 및 오류 페이지에 대한 경로를 제공하여 스토리지 계정에서 정적 웹 사이트 기능을 구성합니다.

Azure Portal에서 Azure Portal의 스토리지 계정으로 이동합니다.
사이드바 메뉴에서 데이터 관리>정적 웹 사이트를 선택합니다.
정적 웹 사이트 페이지에서 사용을 선택합니다.
인덱스 문서 이름에 index.html을 입력합니다.
오류 문서 경로에 404/index.html을 입력합니다.
저장을 선택합니다.

기본 엔드포인트 URL을 기록해 둡다. 나중에 자체 호스팅 포털에 액세스하도록 구성합니다.

스토리지 계정에 대한 CORS 설정 구성

스토리지 계정에 대한 CORS(원본 간 리소스 공유) 설정을 구성하려면 다음을 수행합니다.

Azure Portal에서 스토리지 계정으로 이동합니다.
사이드바 메뉴의 설정에서 CORS(리소스 공유)를 선택합니다.
Blob service 탭에서 다음 규칙을 구성합니다.

규칙 가치

허용된 출처 *

허용되는 메서드 모든 HTTP 동사를 선택합니다.

허용되는 헤더 *

노출된 헤더 *

최대 연령 0
저장을 선택합니다.

규칙	가치
허용된 출처	*
허용되는 메서드	모든 HTTP 동사를 선택합니다.
허용되는 헤더	*
노출된 헤더	*
최대 연령	0

개발자 포털 백 엔드에 대한 CORS 설정 구성

자체 호스팅 개발자 포털을 통해 시작된 요청을 허용하도록 개발자 포털 백 엔드에 대한 CORS 설정을 구성합니다. 셀프 호스팅 개발자 포털은 포털 backendUrl 파일에 설정된 개발자 포털의 백엔드 엔드포인트를 활용하여 다음을 포함한 여러 기능을 사용할 수 있도록 합니다.

CAPTCHA 확인
테스트 콘솔에서 OAuth 2.0 권한 부여
사용자 인증 및 제품 구독의 위임

CORS 설정을 추가하려면 다음을 수행합니다.

Azure Portal에서 API Management 인스턴스로 이동합니다.
사이드바 메뉴에서 개발자 포털>설정을 선택합니다.
자체 호스팅 포털 구성 탭에서 하나 이상의 원본 도메인 값을 추가합니다. 예를 들어:
- 자체 호스팅 포털이 호스트되는 도메인(예: https://contoso.developer.azure-api.net)
- 로컬 개발(해당하는 경우)의 경우 localhost(예: http://localhost:8080 또는 https://localhost:8080)
저장을 선택합니다.

3단계: 포탈 실행

이제 개발 모드에서 로컬 포털 인스턴스를 빌드하고 실행할 수 있습니다. 개발 모드에서는 모든 최적화가 해제되고 원본 맵이 설정됩니다.

다음 명령을 실행합니다.
```
npm run start
```
브라우저를 통해 인증하라는 메시지가 표시됩니다. 계속하려면 Microsoft 자격 증명을 선택합니다.
시간이 지나면 기본 브라우저가 로컬 개발자 포털 인스턴스와 함께 자동으로 열립니다. 기본 주소는 http://localhost:8080이지만 8080이 이미 점유된 경우 포트가 변경될 수 있습니다. 프로젝트의 코드베이스를 변경하면 다시 빌드가 트리거되고 브라우저 창이 새로 고쳐집니다.

4단계: 비주얼 편집기를 통해 편집

비주얼 편집기를 사용하여 다음 작업을 수행할 수 있습니다.

포털 사용자 지정
작성자 콘텐츠
웹 사이트 구조 구성
외관 스타일 지정

자습서: 개발자 포털 액세스 및 사용자 지정을 참조하세요. 관리자 사용자 인터페이스의 기본 사항에 대해 설명하고, 기본 콘텐츠에 대해 권장되는 변경 사항을 나열합니다. 로컬 환경의 모든 변경 내용을 저장하고 Ctrl+C를 눌러 닫습니다.

5단계: 포털을 로컬로 게시

npm run publish를 실행합니다. 브라우저를 통해 인증하라는 메시지가 표시됩니다. 계속하려면 Microsoft 자격 증명을 선택합니다.
잠시 후 콘텐츠가 폴더에 dist/website 게시됩니다.

6단계: BLOB에 정적 파일 업로드

Azure CLI를 사용하여 로컬로 생성된 정적 파일을 Blob에 업로드하고 방문자가 액세스할 수 있는지 확인합니다.

Windows 명령 프롬프트, PowerShell 또는 다른 명령 셸을 엽니다.
다음 명령을 실행합니다 az storage blog upload-batch . 스토리지 계정에 대한 연결 문자열로 대체 <connection-string> 합니다. 스토리지 계정의 보안 + 네트워킹>액세스 키 섹션에서 가져올 수 있습니다.
```
az storage blob upload-batch --source dist/website \
    --account-name <your-storage-account-name> \
    --destination '$web' \
    --connection-string "<connection-string>"
```

7단계: 웹 사이트로 이동

이제 웹 사이트가 Azure Storage 속성에 지정된 호스트 이름으로 라이브 상태가 됩니다. 사이드바 메뉴에서 데이터 관리>정적 웹 사이트로 이동합니다. 호스트 이름은 기본 엔드포인트의 값입니다.

웹사이트 편집기를 호스팅합니다

웹 사이트 코드를 변경할 때 수정된 위젯의 편집을 제대로 지원하려면 웹 사이트 편집기 코드를 업데이트해야 할 수 있습니다. 이 경우 포털을 호스팅하는 것 외에 편집기 애플리케이션을 호스트할 수도 있습니다. 이를 위해 빌드하고 API Management 서비스에 액세스하도록 구성해야 합니다.

이를 위해 테넌트에 Microsoft Entra ID 애플리케이션이 필요합니다.

Microsoft Entra ID 테넌트에 애플리케이션을 등록합니다. 애플리케이션(클라이언트) ID 및 디렉터리(테넌트) ID를 기록해 둡니다. 이후 단계에서 구성합니다.
디자이너가 호스트되는 웹앱의 엔드포인트를 가리키도록 이 애플리케이션에서 웹 리디렉션 URI (회신 URL)를 구성합니다. 일반적으로 Blob Storage 기반 웹 사이트의 위치입니다. 예: https://<your-storage-account-name>z13.web.core.windows.net/.
파이프라인(GitHub Actions)에 포털을 게시하려면 이 애플리케이션에 대한 클라이언트 암호도 만듭니다. 생성된 비밀 값을 기록하고 안전한 위치에 저장합니다.

그런 다음, 다음 단계에 따라 웹 사이트 편집기를 호스트합니다.

config.design.json 파일에 clientId 및 tenantId 필드를 추가합니다.

{
    ...
    "clientId": "< Entra ID app ID >",
    "tenantId": "< Entra ID tenant ID >"
    ...
}

npm run build-designer 명령을 실행하여 디자이너를 빌드합니다.

생성된 /dist/designer 폴더로 이동합니다. 해당 폴더에는 다음 콘텐츠가 포함된 config.json 파일이 있습니다.

{
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >",
    "clientId": "< Entra ID client ID >",
    "tenantId": "< Entra ID tenant ID >"
}

Azure Resource Manager API를 사용하여 API Management 서비스에 연결하는 데 필요한 구성 subscriptionIdresourceGroupName 및 serviceName구성을 확인합니다.

파이프라인에서 포털 배포(GitHub Actions)

GitHub Actions와 같은 파이프라인에서 자체 호스팅 포털을 게시할 수 있습니다.

파이프라인에서 게시를 실행하기 위해서는 Entra ID 애플리케이션 자격 증명이 필요합니다. 이전 단계에서 설명한 것과 동일한 Entra ID 애플리케이션을 사용할 수 있습니다. tenantId, clientId, 그리고 특히 clientSecret는 각 키 스토리지에 보관해야 합니다. 자세한 내용은 GitHub Actions에서 비밀 사용을 참조하세요.

GitHub Actions 파이프라인 YAML의 예:


name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

API Management 알림 템플릿 변경

자체 호스팅 포털을 가리키도록 API Management 알림 템플릿의 개발자 포털 URL을 바꿉니다. Azure API Management에서 알림 및 메일 템플릿을 구성하는 방법을 참조하세요.

구체적으로는 기본 템플릇에 다음과 같은 변경 사항을 적용합니다.

비고

다음 업데이트됨 섹션의 값은 사용자가 https://portal.contoso.com/에서 포털을 호스트하고 있는 것으로 가정합니다.

전자 메일 변경 확인

전자 메일 변경 확인 알림 템플릿에서 개발자 포털 URL을 업데이트합니다.

원본 콘텐츠

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

업데이트됨

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

새 개발자 계정 확인

새 개발자 계정 확인 알림 템플릿에서 개발자 포털 URL을 업데이트합니다.

원본 콘텐츠

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

업데이트됨

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

사용자 초대

사용자 알림 초대 템플릿에서 개발자 포털 URL을 업데이트 합니다.

원본 콘텐츠

<a href="$ConfirmUrl">$ConfirmUrl</a>

업데이트됨

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

새 구독 활성화

새 구독 활성화 알림 템플릿에서 개발자 포털 URL을 업데이트합니다.

원본 콘텐츠

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

업데이트됨

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

원본 콘텐츠

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

업데이트됨

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

원본 콘텐츠

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

업데이트됨

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

원본 콘텐츠

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

업데이트됨

<!--Remove the entire block of HTML code above.-->

암호 변경 확인

암호 변경 확인 알림 템플릿에서 개발자 포털 URL을 업데이트합니다.

원본 콘텐츠

<a href="$DevPortalUrl">$DevPortalUrl</a>

업데이트됨

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

모든 템플릿

바닥글에 링크가 포함된 모든 템플릿에서 개발자 포털 URL을 업데이트합니다.

원본 콘텐츠

<a href="$DevPortalUrl">$DevPortalUrl</a>

업데이트됨

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

관리에서 자체 호스트된 개발자 포털로 이동

시간이 지남에 따라 비즈니스 요구 사항이 변경될 수 있습니다. API Management 개발자 포털의 관리형 버전이 더 이상 요구 사항을 충족하지 못하는 상황이 발생할 수 있습니다. 예를 들어 새 요구 사항으로 인해 타사 데이터 공급자와 통합되는 사용자 지정 위젯을 빌드해야 할 수 있습니다. 관리되는 버전과 달리 자체 호스팅 버전의 포털은 유연성과 확장성을 제공합니다.

전환 프로세스

관리형 버전에서 동일한 API Management 서비스 인스턴스 내의 자체 호스팅 버전으로 전환할 수 있습니다. 이 프로세스는 관리되는 버전의 포털에서 수행한 수정 사항을 유지합니다. 포털의 콘텐츠를 미리 백업했는지 확인하세요. API Management 개발자 포털 scripts.v3의 폴더에서 백업 스크립트를 찾을 수 있습니다.

변환 프로세스는 이 문서의 이전 단계에 표시된 것처럼 일반 자체 호스팅 포털을 설정하는 프로세스와 거의 동일합니다. 구성 단계에서는 한 가지 예외가 있습니다. config.design.json 파일의 저장소 계정은 관리형 버전의 포털의 저장소 계정과 동일해야 합니다. 자습서: 시스템에 할당된 ID를 사용하여 Linux VM에서 SAS URL을 검색하는 방법과 SAS 자격 증명을 통해 Azure Storage에 액세스하는 지침을 참조하세요.

팁 (조언)

config.publish.json 파일에 별도의 스토리지 계정을 사용하는 것이 좋습니다. 이러한 방식으로 더 많은 제어권을 확보하고 포털의 호스팅 서비스 관리를 간소화할 수 있습니다.

자체 호스팅을 위한 다른 방법에 대해 알아봅니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-10-30

다음을 통해 공유

API Management 개발자 포털 자체 호스팅

필수 조건

1단계: 로컬 환경 설정

2단계: JSON 파일, 정적 웹 사이트 및 CORS 설정 구성

config.design.json 파일

config.design.json의 선택적 설정

config.publish.json 파일

config.runtime.json 파일

정적 웹 사이트 구성

스토리지 계정에 대한 CORS 설정 구성

개발자 포털 백 엔드에 대한 CORS 설정 구성

3단계: 포탈 실행

4단계: 비주얼 편집기를 통해 편집

5단계: 포털을 로컬로 게시

6단계: BLOB에 정적 파일 업로드

7단계: 웹 사이트로 이동

웹사이트 편집기를 호스팅합니다

파이프라인에서 포털 배포(GitHub Actions)

API Management 알림 템플릿 변경

전자 메일 변경 확인

새 개발자 계정 확인

사용자 초대

새 구독 활성화

암호 변경 확인

모든 템플릿

관리에서 자체 호스트된 개발자 포털로 이동

전환 프로세스

관련 콘텐츠

피드백

추가 리소스