API Management 개발자 포털 - 질문과 대답
적용 대상: 개발자 | 기본 | 기본 v2 | 표준 | 표준 v2 | 프리미엄 | 프리미엄 v2
포털에서 지원되지 않는 기능이 필요한 경우 어떻게 하나요?
다음과 같은 옵션이 있습니다.
소규모 사용자 지정의 경우 기본 제공 위젯을 사용하여 사용자 지정 HTML을 추가합니다. 현재 사용자 지정 HTML 코드 위젯은 API Management의 v2 계층에서 사용할 수 없습니다.
대규모 사용자 지정의 경우 관리되는 개발자 포털에 사용자 지정 위젯을 만들어 업로드합니다. 현재 사용자 지정 위젯은 API Management의 v2 계층에서 사용할 수 없습니다.
개발자 포털 코드베이스의 핵심을 수정해야 하는 경우에만 개발자 포털을 자체 호스팅합니다.
GitHub 리포지토리에서 기능 요청을 엽니다.
개발자 포털의 기능을 사용자 지정 및 확장하는 방법에 대해 자세히 알아봅니다.
하나의 API Management 서비스에서 여러 개발자 포털을 사용할 수 있나요?
하나의 관리되는 포털 및 여러 개의 자체 호스팅 포털이 있을 수 있습니다. 모든 포털의 콘텐츠는 동일한 API Management 서비스에 저장되므로 동일합니다. 포털의 외관과 기능을 구분하려면 런타임 시 페이지를 동적으로 사용자 지정하는(예: URL을 기반으로) 고유한 사용자 지정 위젯을 사용하여 자체 호스팅할 수 있습니다.
포털이 Azure Resource Manager 템플릿을 지원하나요? 아니면 API Management DevOps Resource Kit와 호환되나요?
아니요.
포털 콘텐츠가 API Management의 백업/복원 기능으로 저장되나요?
아니요.
관리되는 포털 종속성에 대한 추가 VNet 연결을 사용하도록 설정해야 하나요?
대부분의 경우 아닙니다.
API Management 서비스가 내부 VNet에 있는 경우 개발자 포털은 네트워크 내에서만 액세스할 수 있습니다. 관리 엔드포인트의 호스트 이름은 포털의 관리 인터페이스에 액세스하는 데 사용하는 컴퓨터에서 서비스의 내부 VIP로 확인되어야 합니다. 관리 엔드포인트가 DNS에 등록되어 있는지 확인합니다. 잘못된 구성의 경우 Unable to start the portal. See if settings are specified correctly in the configuration (...) 오류가 표시됩니다.
API Management 서비스가 내부 VNet에 있고 인터넷에서 Application Gateway를 통해 액세스하는 경우 개발자 포털 및 API Management의 관리 엔드포인트에 대한 연결을 사용하도록 설정해야 합니다. Web Application Firewall 규칙을 사용하지 않도록 설정해야 할 수 있습니다. 자세한 내용은 이 설명서 문서를 참조하세요.
사용자 지정 API Management 도메인을 할당하고 게시된 포털이 작동하지 않음
도메인을 업데이트한 후 변경 사항을 적용하려면 포털을 다시 게시해야 합니다.
ID 공급자를 추가하고 포털에서 볼 수 없음
ID 공급자(예: Azure AD, Azure AD B2C)를 추가한 후 변경 사항을 적용하려면 포털을 다시 게시해야 합니다. 개발자 포털 페이지에 OAuth 단추 위젯이 포함되어 있는지 확인합니다.
위임을 설정하고 포털에서 이를 사용하지 않음
위임을 설정한 후 변경 사항을 적용하려면 포털을 다시 게시해야 합니다.
다른 API Management 구성 변경 사항이 개발자 포털에 전파되지 않았음
대부분의 구성 변경(예: VNet, 로그인, 제품 약관) 시 포털을 다시 게시해야 합니다.
대화형 콘솔을 사용할 때 CORS 오류가 발생함
대화형 콘솔은 브라우저에서 클라이언트 측 API 요청을 만듭니다. API에 CORS 정책을 추가하여 CORS 문제를 해결하거나 CORS 프록시를 사용하도록 포털을 구성합니다. 자세한 내용은 API Management 개발자 포털에서 대화형 콘솔에 대해 CORS 사용을 참조하세요.
사용자 지정 HTML 코드 위젯을 사용할 때 CORS 오류가 발생합니다.
사용자 환경에서 사용자 지정 HTML 코드 위젯을 사용하는 경우 위젯에서 로드한 IFrame과 상호 작용할 때 CORS 오류가 표시될 수 있습니다. 이 문제는 IFrame이 개발자 포털과 다른 원본의 콘텐츠를 제공하는 경우 발생합니다. 사용자 지정 위젯을 대신 사용하여 이 문제를 방지할 수 있습니다.
개발자 포털을 편집하는 데 필요한 권한은 무엇인가요?
관리 모드에서 포털을 열었을 때 Oops. Something went wrong. Please try again later. 오류가 표시되는 경우 필요한 권한(Azure RBAC)이 부족한 것일 수 있습니다.
포털에서는 /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1 범위에서 Microsoft.ApiManagement/service/users/token/action 권한이 필요합니다.
다음 PowerShell 스크립트를 사용하여 필요한 권한이 있는 역할을 만들 수 있습니다. <subscription-id> 매개 변수를 변경해야 합니다.
#New Portals Admin Role
Import-Module Az
Connect-AzAccount
$contributorRole = Get-AzRoleDefinition "API Management Service Contributor"
$customRole = $contributorRole
$customRole.Id = $null
$customRole.Name = "APIM New Portal Admin"
$customRole.Description = "This role gives the user ability to log in to the new Developer portal as administrator"
$customRole.Actions = "Microsoft.ApiManagement/service/users/token/action"
$customRole.IsCustom = $true
$customRole.AssignableScopes.Clear()
$customRole.AssignableScopes.Add('/subscriptions/<subscription-id>')
New-AzRoleDefinition -Role $customRole
역할을 만든 후에는 Azure Portal에서 액세스 제어(IAM) 섹션의 모든 사용자에게 역할을 부여할 수 있습니다. 사용자에게 이 역할을 할당하면 서비스 범위에서 권한이 할당됩니다. 사용자는 서비스의 모든 사용자를 대신하여 SAS 토큰을 생성할 수 있습니다. 최소한 이 역할은 서비스 관리자에게 할당되어야 합니다. 다음 PowerShell 명령은 user1 사용자에게 불필요한 권한이 부여되지 않도록 가장 낮은 범위에서 역할을 할당하는 방법을 보여줍니다.
New-AzRoleAssignment -SignInName "user1@contoso.com" -RoleDefinitionName "APIM New Portal Admin" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1"
사용자에게 권한이 부여된 후에는 사용자가 로그아웃하고 Azure Portal에 다시 로그인해야 새 권한이 적용됩니다.
Unable to start the portal. See if settings are specified correctly (...) 오류가 표시됩니다.
https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview에 대한 GET 호출이 실패하면 이 오류가 표시됩니다. 호출은 포털의 관리 인터페이스에 의해 브라우저에서 실행됩니다.
API Management 서비스가 VNet에 있는 경우 VNet 연결 질문을 참조하세요.
사용자 지정 도메인에 할당되고 브라우저에서 신뢰하지 않는 TLS/SSL 인증서로 인해 호출 실패가 발생할 수도 있습니다. 위험 완화로 관리 엔드포인트 사용자 지정 도메인을 제거할 수 있습니다. API Management는 신뢰할 수 있는 인증서로 기본 엔드포인트로 대체합니다.
포털에 대해 어떤 브라우저가 지원되나요?
| 브라우저 | 지원됨 |
|---|---|
| Apple Safari | 예1 |
| Google Chrome | 예1 |
| Microsoft Edge | 예1 |
| Microsoft Internet Explorer | 아니요 |
| Mozilla Firefox | 예1 |
1 2개의 최신 프로덕션 버전에서 지원됩니다.
자체 호스팅 포털의 로컬 개발이 더 이상 작동하지 않습니다.
개발자 포털의 로컬 버전에서 스토리지 계정 또는 API Management 인스턴스에 정보를 저장하거나 검색할 수 없는 경우 SAS 토큰이 만료되었을 수 있습니다. 새 토큰을 생성하여 해결할 수 있습니다. 개발자 포털 자체 호스트 자습서를 참조하세요.
개발자 포털에서 등록을 사용하지 않도록 설정하려면 어떻게 하나요?
개발자 포털에서 기본적으로 등록 기능을 사용하도록 설정할 필요가 없으면 다음 단계를 사용하여 사용하지 않도록 설정할 수 있습니다.
Azure Portal에서 API Management 인스턴스로 이동합니다.
메뉴의 개발자 포털에서 ID를 선택합니다.
목록에 표시되는 각 ID 공급자를 삭제합니다. 각 공급자를 선택하고 상황에 맞는 메뉴(...)를 선택한 후 삭제를 선택합니다.
개발자 포털 관리 인터페이스로 이동합니다.
포털 콘텐츠에서 등록 링크 및 탐색 항목을 제거합니다. 포털 콘텐츠 사용자 지정에 대한 자세한 내용은 자습서: 개발자 포털 액세스 및 사용자 지정을 참조하세요.
사용자가 직접 탐색하는 경우 등록 페이지 콘텐츠를 수정하여 ID 데이터를 입력하는 데 사용되는 필드를 제거합니다.
선택적으로 등록 페이지를 삭제합니다. 현재 contentItem REST API를 사용하여 이 페이지를 나열하고 삭제합니다.
변경 내용을 저장하고 포털을 다시 게시합니다.
API Management 서비스에 프로비전된 개발자 포털 콘텐츠를 어떻게 제거할 수 있나요?
개발자 포털 GitHub 리포지토리의 scripts.v3/cleanup.bat 스크립트에 필요한 매개 변수를 제공하고 스크립트 실행
cd scripts.v3
.\cleanup.bat
cd ..
자체 호스트 개발자 포털에 대한 SSO(Single Sign-On) 인증을 어떻게 사용 설정하나요?
다른 인증 방법 중에서 개발자 포털은 SSO(Single Sign-On)를 지원합니다. 이 방법을 사용하여 인증하려면 쿼리 매개 변수의 토큰을 사용하여 /signin-sso를 호출해야 합니다.
https://contoso.com/signin-sso?token=[user-specific token]
사용자 토큰 생성
API Management REST API의 공유 액세스 토큰 가져오기 작업을 사용하여 사용자별 토큰(관리자 토큰 포함)을 생성할 수 있습니다.
참고 항목
토큰은 URL로 인코딩해야 합니다.
관련 콘텐츠
다음 문서를 통해 개발자 포털에 대해 자세히 알아봅니다.
- 관리형 개발자 포털 액세스 및 사용자 지정
- 개발자 포털의 기능을 확장합니다.
- 포털의 자체 호스트 버전 설정
다른 리소스 찾아보기: