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

아티클
03/29/2024

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

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

Important

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

가용성 및 성능 향상을 위해 CDN과 같은 솔루션이 선택적으로 제공되는 호스팅 플랫폼에 배포
호스팅 인프라 유지 및 관리
코드베이스를 업그레이드할 때 코드 충돌을 해결해야 하는 보안 패치를 포함한 수동 업데이트

참고 항목

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

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

필수 조건

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

API Management 서비스 인스턴스 없는 경우 빠른 시작 - Azure API Management 인스턴스 만들기를 참조하세요.
정적 웹 사이트 기능이 있는 Azure Storage 계정 스토리지 계정 만들기를 참조하세요.
컴퓨터의 Git 이 Git 자습서에 따라 설치하세요.
Node.js(LTS 버전 v10.15.0 이상) 및 컴퓨터의 npm Node.js 및 npm 다운로드 및 설치를 참조하세요.
Azure CLI Azure CLI 설치 단계를 수행합니다.

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
```

팁

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

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

개발자 포털에서 콘텐츠를 관리하려면 API Management REST API가 필요합니다.

config.design.json 파일

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

{
  "environment": "development",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature ...",
  "backendUrl": "https://<service-name>.developer.azure-api.net",
  "useHipCaptcha": false,
  "integration": {
      "googleFonts": {
          "apiKey": "..."
      }
  }
}

파일 구성:

managementApiUrl 값에서 <service-name>을 API Management 인스턴스의 이름으로 대체합니다. 사용자 지정 도메인을 구성한 경우 이를 대신 사용합니다(예: https://management.contoso.com).
```
{
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...
```
수동으로 SAS 토큰을 만들어 직접 REST API가 API Management에 액세스하도록 할 수 있습니다.
생성된 토큰을 복사하여 managementApiAccessToken 값으로 붙여 넣습니다.
backendUrl 값에서 <service-name>을 API Management 인스턴스의 이름으로 대체합니다. 사용자 지정 도메인을 구성한 경우 이를 대신 사용합니다(예: https://portal.contoso.com).
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```
개발자 포털에서 CAPTCHA를 활성화하려면 "useHipCaptcha": true를 설정합니다. 개발자 포털 백 엔드에 대한 CORS 설정을 구성해야 합니다.
integration의 googleFonts에서 선택적으로 apiKey를 웹 글꼴 개발자 API에 대한 액세스를 허용하는 Google API 키로 설정합니다. 이 키는 개발자 포털 편집기의 스타일 섹션에 Google 글꼴을 추가하려는 경우에만 필요합니다.

아직 키가 없으면 Google Cloud 콘솔을 사용하여 구성할 수 있습니다. 다음 단계를 수행합니다.
1. Google Cloud 콘솔을 엽니다.
2. 웹 글꼴 개발자 API가 사용하도록 설정되어 있는지 확인합니다. 그렇지 않은 경우 사용하도록 설정합니다.
3. 자격 증명 만들기>API 키를 선택합니다.
4. 열린 대화 상자에서 생성된 키를 복사하여 config.design.json 파일의 apiKey 값으로 붙여넣습니다.
5. API 키 편집을 선택하여 키 편집기를 엽니다.
6. 편집기의 API 제한에서 키 제한을 선택합니다. 드롭다운에서 웹 글꼴 개발자 API를 선택합니다.
7. 저장을 선택합니다.

config.publish.json 파일

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

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

파일 구성:

이전 구성 파일에서 managementApiUrl 및 managementApiAccessToken 값을 복사하여 붙여 넣습니다.
개발자 포털에서 CAPTCHA를 활성화하려면 "useHipCaptcha": true를 설정합니다. 개발자 포털 백 엔드에 대한 CORS 설정을 구성해야 합니다.

config.runtime.json 파일

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

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

파일 구성:

이전 구성 파일에서 managementApiUrl 값을 복사하여 붙여 넣습니다.
backendUrl 값에서 <service-name>을 API Management 인스턴스의 이름으로 대체합니다. 사용자 지정 도메인을 구성한 경우 이를 대신 사용합니다(예: https://portal.contoso.com).
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```

정적 웹 사이트 구성

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

Azure Portal의 저장소 계정으로 이동하고 왼쪽 메뉴에서 정적 웹 사이트를 선택합니다.
정적 웹 사이트 페이지에서 사용을 선택합니다.
인덱스 문서 이름에 index.html을 입력합니다.
오류 문서 경로에 404/index.html을 입력합니다.
저장을 선택합니다.

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

스토리지 계정에 대한 CORS(원본 간 리소스 공유) 설정 구성

Azure Portal의 저장소 계정으로 이동하고 왼쪽 메뉴에서 CORS를 선택합니다.
Blob service 탭에서 다음 규칙을 구성합니다.

규칙 값

허용된 원본 *

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

허용된 헤더 *

노출된 헤더 *

최대 기간 0
저장을 선택합니다.

규칙	값
허용된 원본	*
허용된 메서드	모든 HTTP 동사를 선택합니다.
허용된 헤더	*
노출된 헤더	*
최대 기간	0

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

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

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

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

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

3단계: 포탈 실행

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

다음 명령을 실행합니다.

npm start

잠시 후 기본 브라우저가 로컬 개발자 포털 인스턴스와 함께 자동으로 열립니다. 기본 주소는 http://localhost:8080이지만 8080이 이미 점유된 경우 포트가 변경될 수 있습니다. 프로젝트의 코드베이스를 변경하면 브라우저 창을 다시 빌드하고 새로 고칩니다.

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

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

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

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

5단계: 로컬에 게시

포털 데이터는 강력한 개체 형식으로 발생합니다. 다음 명령은 개체를 정적 파일로 변환하고 출력을 ./dist/website 디렉터리에 배치합니다.

npm run publish

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

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

Windows 명령 프롬프트, PowerShell 또는 다른 명령 셸을 엽니다.
다음 Azure CLI 명령을 실행합니다.

<account-connection-string>을 스토리지 계정의 연결 문자열로 바꿉니다. 연결 문자열은 스토리지 계정의 액세스 키 섹션에서 가져올 수 있습니다.
```
az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-connection-string>
```

7단계: 웹 사이트로 이동

이제 웹 사이트가 Azure Storage 속성(정적 웹 사이트의 기본 엔드포인트)에 지정된 호스트 이름 아래에 있습니다.

8단계: 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 개발자 포털 GitHub 리포지토리의 scripts 폴더에서 백업 스크립트를 찾을 수 있습니다.

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

팁

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

다음 단계

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

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

필수 조건

1단계: 로컬 환경 설정

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

config.design.json 파일

config.publish.json 파일

config.runtime.json 파일

정적 웹 사이트 구성

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

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

3단계: 포탈 실행

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

5단계: 로컬에 게시

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

7단계: 웹 사이트로 이동

8단계: API Management 알림 템플릿 변경

전자 메일 변경 확인

새 개발자 계정 확인

사용자 초대

새 구독 활성화

암호 변경 확인

모든 템플릿

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

전환 프로세스

다음 단계

추가 리소스