이 문서는 Microsoft Learn Platform API 사용을 시작하는 데 도움이 됩니다. API의 세부 정보 또는 사용 사례에 대해 잘 모르는 경우 먼저 Microsoft Learn Platform API 개요 문서를 검토하는 것이 좋습니다.
플랫폼 API 인증 학습
Learn Platform REST API는 인증에 Microsoft Entra ID 사용합니다. API를 호출하기 전에 액세스 방법을 선택해야 하며 클라이언트 애플리케이션은 유효한 자격 증명으로 인증해야 합니다.
앱 전용 액세스
앱이 Learn에 직접 액세스하는 경우 해당 액세스는 단일 사용자에 연결되지 않습니다. 앱은 자체 ID를 사용하여 직접 API를 호출합니다. 이 시나리오는 앱 전용 액세스입니다. Microsoft ID 플랫폼에 대해 자세히 알아보세요.
시작하려면 앱 등록 또는 관리 ID일 수 있는 Microsoft ID 플랫폼에 유효한 ID가 필요합니다. 이상적으로 각 파트너에는 할당량 및 파트너 관리를 간소화하기 위한 단일 ID가 있어야 합니다. 사용자 할당 관리 ID를 사용하면 여러 서비스에서 관리 ID를 통합하는 데 도움이 될 수 있습니다.
Entra ID가 설정되면 인증을 증명하기 위해 범위가 로 설정된 을 Entra ID에서 가져옵니다. LEARN에 REST API 요청을 할 때 HTTP 권한 부여 헤더에 액세스 토큰을 포함합니다.
위임된 액세스
사용자가 앱에 로그인하여 Learn에 액세스하는 데 사용할 때 앱은 먼저 사용자를 대신하여 이 리소스에 액세스할 수 있는 권한을 요청해야 합니다. 이 시나리오를 위임된 액세스라고 합니다. Microsoft ID 플랫폼에 대해 자세히 알아보세요.
시작하려면 앱 등록을 등록해야 합니다. 앱 등록이 설정되면 앱에서 사용자를 대신하여 Learn에 액세스하기 위해 특정 범위 또는 범위 집합을 사용자에게 부여하도록 요청해야 합니다. Learn은 세분화된 리소스 액세스를 위한 범위 목록을 제공합니다. 범위 목록은 다음과 같습니다.
- : 이 범위를 통해 사용자는 로그인한 사용자로 가장된 Learn의 공개 콘텐츠에 액세스할 수 있습니다.
Microsoft Learn 플랫폼 API 버전 관리 이해
API에 대한 호환성이 손상되는 변경이 발생하면 날짜가 지정된 새 버전을 릴리스합니다. 호환성 변경은 통합 기능을 손상시킬 수 있는 변경의 내용입니다. 호환성을 유지하는(추가적인) 변경 내용은 지원되는 모든 API 버전에서 사용할 수 있습니다.
API 버전은 api-version 쿼리 매개 변수로 지정되며 안정적인 버전에는 yyyy-MM-dd를 사용하고 미리 보기 버전에는 yyyy-MM-dd-preview를 사용합니다. api-version 쿼리 매개 변수는 모든 API 요청에 필요합니다.
안정적인 새 API 버전이 릴리스되면 새 API 버전이 릴리스된 후 최소 24개월 동안 안정적인 이전 API 버전이 지원됩니다. 미리 보기 API는 새 미리 보기 API가 출시된 후 3개월 더 짧은 지원 주기를 갖습니다.
현재 버전은 2023-11-01-preview입니다.
모든 API 앞의 /v1/URL 세그먼트는 API 버전이 아닌 기본 URL의 일부입니다. 향후 상당한 API 프로토콜 및 패턴 변경을 위해 예약되어 있습니다.
플랫폼 API 속도 제한 알아보기
학습은 특정 시간 내에 수행할 수 있는 REST API 요청 수를 제한합니다. 해당 제한 사항은 남용 및 서비스 거부 공격을 방지하고 모든 사용자가 API를 계속 사용할 수 있도록 합니다.
학습은 액세스 토큰의 oid 클레임에 기반하여 속도 제한을 적용합니다. 앱 전용 액세스의 경우 앱 자체에 제한이 적용되는 반면 위임된 액세스의 경우 앱에 로그인한 사용자에게 제한이 적용됩니다.
기본적으로 속도 제한은 분당 100개의 API 호출이며 5분 동안 계산됩니다. 프로덕션에 더 높은 제한이 필요한 경우 Learn Integrations 지원에 문의하여 증가를 요청할 수 있습니다.
기술 자료 검색 API와 같은 특정 API는 토큰 기반 속도 제한도 구현합니다. 이는 사용된 Microsoft Azure OpenAI 토큰 수를 기반으로 하며 기본 제한은 분당 10,000개입니다. 프로덕션에 대한 이 제한을 늘리려면 Learn Integrations 지원에 문의하세요.
Learn Platform API 페이지네이션
모든 최상위 API 리소스는 'list' API 메서드를 통해 대량 검색을 지원합니다. 예를 들어 모듈 또는 시험 목록을 검색할 수 있습니다. 이러한 메서드는 표준화된 접근 방식에 따라 페이지를 매긴 응답을 반환합니다.
List API 메서드는 응답 본문의 nextLink 필드로 표시된 커서 기반 페이지 매김을 사용합니다. 이 필드에는 결과의 다음 페이지를 가져오는 데 필요한 정보가 포함된 불투명 URL이 포함되어 있습니다. 기본적으로 목록 API는 요청당 30개의 항목을 반환하지만 maxpagesize 매개 변수를 사용하여 페이지 크기를 조정할 수 있습니다.
클라이언트 SDK 라이브러리는 목록의 모든 페이지를 트래버스하는 자동 페이지 매김 도우미를 제공합니다.
관련 콘텐츠
- 빠른 시작: Microsoft Learn Platform API 카탈로그 데이터 설정 및 사용
- Learn Platform API 카탈로그 데이터 개발자 참조
- 플랫폼 API FAQ 알아보기