Azure API Center 플랫폼 API 카탈로그 사용 및 보기

이 문서에서는 엔터프라이즈 개발자에게 Azure API Center용 Visual Studio Code 확장의 Azure API 센터 플랫폼 API 카탈로그(미리 보기)에 대한 액세스를 제공하는 방법을 보여 줍니다. 개발자는 플랫폼 API 카탈로그를 사용하여 Azure API 센터에서 API를 검색하고, API 정의를 보고, API 센터 자체를 관리하거나 인벤토리에 API를 추가할 수 있는 액세스 권한이 없는 경우 필요에 따라 API 클라이언트를 생성할 수 있습니다. 플랫폼 API 카탈로그에 대한 액세스는 Microsoft Entra ID 및 Azure 역할 기반 액세스 제어를 사용하여 관리됩니다.

필수 조건

API 센터 관리자의 경우

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

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

앱 개발자용

• Visual Studio Code용 Azure API 센터 확장

  Important

  현재 플랫폼 API 카탈로그에 대한 액세스는 확장의 시험판 버전에서만 사용할 수 있습니다. Visual Studio Code Marketplace의 확장을 설치할 때는 릴리스 버전 또는 시험판 버전을 설치하도록 선택할 수 있습니다. 확장 보기에서 확장의 관리 단추 상황에 맞는 메뉴를 사용하여 언제든지 두 버전 간을 전환합니다.

다음 Visual Studio Code 확장은 선택 사항입니다.

• Microsoft Kiota 확장 - API 클라이언트를 생성합니다.

API 센터 관리자가 카탈로그에 대한 액세스를 사용하도록 설정하는 단계

다음 섹션에서는 엔터프라이즈 개발자가 플랫폼 API 카탈로그에 액세스할 수 있도록 API 센터 관리자를 위한 단계를 제공합니다.

Microsoft Entra 앱 등록 만들기

먼저 Microsoft Entra ID 테넌트에서 앱 등록을 구성합니다. 앱 등록을 사용하면 Azure API Center용 Visual Studio Code 확장에서 로그인한 사용자를 대신하여 플랫폼 API 카탈로그에 액세스할 수 있습니다.

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

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

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

   • platform-api-catalog와 같은 의미 있는 이름으로 이름 설정
   • 지원되는 계정 유형에서 이 조직 디렉터리의 계정(단일 테넌트)을 선택합니다.
   • 리디렉션 URI에서 SPA(단일 페이지 애플리케이션)를 선택하고 URI를 API 센터의 런타임 URI로 설정합니다. 예들 들어 https://<service name>.data.<region>.azure-apicenter.ms입니다. 예: https://contoso-apic.data.eastus.azure-apicenter.ms
   • 등록을 선택합니다.

   팁

   더 많은 API 센터에 액세스하기 위해 동일한 앱 등록을 사용할 수 있습니다. 리디렉션 URI에서 플랫폼 API 카탈로그에 표시하려는 다른 API 센터에 대한 리디렉션 URI를 계속 추가합니다.

4. 개요 페이지에서 애플리케이션(클라이언트) ID와 디렉터리(테넌트) ID를 복사합니다. 나중에 Visual Studio Code 확장에서 API 센터에 연결할 때 이러한 값을 설정합니다.

5. 왼쪽 메뉴의 관리에서 인증>+ 플랫폼 추가를 선택합니다.

6. 플랫폼 구성 페이지에서 모바일 및 데스크톱 애플리케이션을 선택합니다.

7. 데스크톱 + 디바이스 구성 페이지에서 다음 리디렉션 URI를 입력하고 구성을 선택합니다.

   https://vscode.dev/redirect

8. 왼쪽 메뉴의 관리 아래에서 API 사용 권한>+ 권한 추가를 선택합니다.

9. 요청 API 권한 페이지에서 다음을 수행합니다.

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

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

   

Microsoft Entra 사용자 및 그룹에서 플랫폼 API 카탈로그에 로그인 사용

엔터프라이즈 개발자는 Microsoft 계정으로 로그인하여 API 센터의 플랫폼 API 카탈로그를 확인해야 합니다. 필요한 경우 개발자를 Microsoft Entra 테넌트에 추가하거나 초대합니다.

그런 다음 로그인을 사용하도록 설정하려면 Azure API 센터 데이터 판독기 역할을 테넌트 내의 사용자 또는 그룹에 할당합니다. 이 역할은 API 센터로 범위가 지정됩니다.

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

1. Azure Portal에서 API 센터로 이동합니다.
2. 왼쪽 메뉴에서 액세스 제어(IAM)>+역할 할당 추가를 선택합니다.
3. 역할 할당 추가 창에서 다음과 같이 값을 설정합니다.
   • 역할 페이지에서 Azure API 센터 데이터 읽기 권한자를 검색하여 선택합니다. 다음을 선택합니다.
   • 멤버 페이지의 액세스 할당에서 사용자, 그룹 또는 서비스 주체>+ 멤버 선택을 선택합니다.
   • 멤버 선택 페이지에서 역할을 할당할 사용자 또는 그룹을 검색하고 선택합니다. 선택을 클릭한 후 다음을 클릭합니다.
   • 역할 할당을 검토하고 검토 + 할당을 선택합니다.
4. 이전 단계를 반복하여 더 많은 API 센터에 대한 플랫폼 API 카탈로그에 로그인할 수 있도록 합니다.

엔터프라이즈 개발자가 플랫폼 API 카탈로그에 액세스하는 단계

개발자는 다음 단계에 따라 연결하고 로그인하여 Visual Studio Code 확장을 사용하여 플랫폼 API 카탈로그를 볼 수 있습니다. API 센터에 연결하는 설정은 API 센터 관리자가 제공해야 합니다.

API 센터에 연결

1. Visual Studio Code for Visual Studio Code용 Azure API Center 확장의 시험판 버전을 설치합니다.

2. Visual Studio Code의 왼쪽 작업 표시줄에서 API 센터를 선택합니다.

   

3. 명령 팔레트를 열려면 Ctrl+Shift+P 바로 가기 키를 사용합니다. Azure API 센터 입력 : API 센터에 연결하고 Enter 키를 누릅니 다.

4. 다음 정보를 입력하라는 메시지에 응답합니다.

   1. API 센터의 런타임 URL 형식 <service name>.data.<region>.azure-apicenter.ms (접두사 사용 안 함)입니다 https://. 예: contoso-apic.data.eastus.azure-apicenter.ms 이 런타임 URL은 Azure Portal 의 API 센터 개요 페이지에 표시됩니다.
   2. 이전 섹션의 관리자가 구성한 앱 등록의 애플리케이션(클라이언트) ID입니다.
   3. 이전 섹션의 관리자가 구성한 앱 등록의 디렉터리(테넌트) ID입니다.

   팁

   API 센터 관리자는 개발자에게 이러한 연결 세부 정보를 제공하거나 다음 형식으로 직접 링크를 제공해야 합니다.
   vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.ms

   API 센터에 연결한 후 API 센터 이름이 API 센터 플랫폼 API 카탈로그에 표시됩니다.

5. API 센터에서 API를 보려면 API 센터 이름 아래에서 Azure에 로그인을 선택합니다. API 센터에서 Azure API Center 데이터 판독기 역할이 할당된 Microsoft 계정으로 로그인할 수 있습니다.

   

6. 로그인한 후 API를 선택하여 API 센터의 API를 나열합니다. API를 확장하여 해당 버전 및 정의를 탐색합니다.

   

7. 액세스가 구성된 경우 이전 단계를 반복하여 더 많은 API 센터에 연결합니다.

카탈로그에서 API 검색 및 사용

플랫폼 API 카탈로그는 엔터프라이즈 개발자가 API 세부 정보를 검색하고 API 클라이언트 개발을 시작하는 데 도움이 됩니다. 개발자는 플랫폼 API 카탈로그에서 API 정의를 마우스 오른쪽 단추로 클릭하여 다음 기능에 액세스할 수 있습니다.

• API 사양 문서 내보내기 - 정의에서 API 사양을 내보낸 다음 파일로 다운로드
• API 클라이언트 생성 - Microsoft Kiota 확장을 사용하여 선호하는 언어에 대한 API 클라이언트 생성
• Markdown 생성 - Markdown 형식으로 API 설명서 생성
• OpenAPI 설명서 - API 정의에 대한 설명서 보기 및 Swagger UI에서 작업 시도(OpenAPI 정의에만 사용 가능)

문제 해결

오류: 정의되지 않은 속성을 읽을 수 없음('nextLink' 읽기)

특정 조건에서 사용자는 API 센터 플랫폼 API 카탈로그에 로그인하고 API 센터의 API 목록을 확장한 후 다음과 같은 오류 메시지가 표시될 수 있습니다.

Error: Cannot read properties of undefined (reading 'nextLink')

사용자에게 API 센터에서 Azure API 센터 데이터 판독기 역할이 할당되어 있는지 확인합니다. 필요한 경우 사용자에게 역할을 다시 할당합니다. 그런 다음 Visual Studio Code 확장에서 API Center 플랫폼 API 카탈로그를 새로 고칩니다.

Azure에 로그인할 수 없음

Azure API Center 데이터 판독기 역할이 할당된 사용자가 플랫폼 API 카탈로그에서 Azure에 로그인을 선택한 후 로그인 흐름을 완료할 수 없는 경우 연결 구성에 문제가 있을 수 있습니다.

Microsoft Entra ID에서 구성한 앱 등록의 설정을 확인합니다. API 센터의 앱 등록 및 런타임 URL에서 애플리케이션(클라이언트) ID 및 디렉터리(테넌트) ID의 값을 확인합니다. 그런 다음 API 센터에 대한 연결을 다시 설정합니다.

Microsoft Entra ID 앱 등록에서 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 권한을 다시 요청해 보세요.

관련 콘텐츠

• Visual Studio Code용 Azure API 센터 확장을 사용하여 API 빌드 및 등록
• Azure RBAC 사용 모범 사례
• 리소스 공급자 등록