Microsoft Learn 카탈로그 API 사용 모범 사례
이 문서에서 Learn 카탈로그 API를 사용에 대한 모범 사례를 설명합니다.
서비스 약관 이해
Learn 카탈로그 API는 공개적으로 사용할 수 있고 무료이긴 하지만 사용자에게 Microsoft API 사용 약관이 적용됩니다. 카탈로그 학습 API를 사용하기 전과 프로덕션 환경에 출력을 포함하기 전에 API 사용 약관을 읽고 이해합니다.
Learn 카탈로그 API의 제한 사항 이해
Learn 카탈로그 API 기능 개요 문서에서 제한 사항을 참조하세요.
Learn 콘텐츠 모델 이해
Learn 카탈로그 API 응답을 효과적으로 사용하려면 Microsoft Learn에서 사용할 수 있는 콘텐츠 형식과 콘텐츠 사이의 관계를 이해하는 것이 중요합니다. 자세한 내용은 Learn 콘텐츠 모델 학습 문서를 검토하세요.
특이점:
- UID는 고유 ID를 나타내며 각 콘텐츠 개체마다 고유합니다. UID가 변경되면 제목이나 다른 메타데이터가 동일하게 유지되더라도 콘텐츠는 새 개체로 간주됩니다.
- 모듈은 Learn 교육 카탈로그 내 핵심 개체입니다. 모듈은 자체 내에서 시나리오 또는 개념을 포괄적으로 가르치고 필수 모듈을 수강할 필요가 없다는 점에서 모두 독립 실행형입니다. 일부 모듈의 경우 이와 같으며 학습 경로에 속하지 않습니다. 다른 모듈에서는 사용자가 고급 개념을 파악하도록 안내하는 하나 이상의 학습 경로에 함께 번들로 제공됩니다. 모듈은 학습 경로의 일부일 필요는 없으며, 하나 이상의 일부일 수 있습니다.
- 단원은 독립 실행형 콘텐츠로 작성되지 않습니다. 모듈에서 특정 순서로 수강할 수 있습니다. 이러한 이유로 모듈 세부 정보 페이지의 링크와 첫 번째 단원을 포함하여 사용자가 해당 위치에서 시작하고 콘텐츠를 진행할 수 있도록 했습니다.
Learn에서 지역화가 작동하는 방식과 지역화된 콘텐츠가 API 출력에 반영되는 방식 이해
Microsoft Learn은 사이트에서 65개 이상의 로캘을 지원하며 대부분의 콘텐츠가 이러한 로캘로 번역됩니다. 콘텐츠에서 가르치는 제품이 제공되는 모든 언어로 콘텐츠를 제공하는 것을 목표로 하지만 모든 로캘 환경에 지역화된 콘텐츠가 제공되는 것은 아닙니다.
로캘 레코드에 사용 가능한 연결된 번역이 없는 경우 사이트의 콘텐츠와 API 응답이 기본값인 영어로 “폴백”됩니다. API 출력에서 대체가 발생하면 다른 로캘 응답에 영어 메타데이터가 표시됩니다. 그러나 기본 콘텐츠가 대체되더라도 콘텐츠의 URL은 여전히 로캘을 가리킵니다. 그 이유는 사용자가 해당 로캘(번역된 머리글/바닥글 및 번역 가능한 기타 링크 표시)로 사이트를 계속 탐색할 수 있도록 하기 위해서입니다.
업데이트가 영어 콘텐츠로 게시되면 지역화 파이프라인이 작동하여 지역화된 버전을 가능한 한 빨리 업데이트하며, 일반적으로 며칠 이내에 업데이트됩니다.
지원되는 로캘의 전체 목록을 Microsoft Learn 사이트 바닥글에서 볼 수 있습니다(보고 있는 언어에서 선택). 각 로캘은 locale 필터를 사용하여 Learn 카탈로그 API와 함께 쿼리할 수 있습니다.
학습 콘텐츠 완성 레코드는 로캘에 구애받지 않습니다. 즉, 사용자 학습 완료 레코드에서 지역화된 버전의 콘텐츠를 별도의 개체로 구분하지 않습니다. 사용자가 어떤 언어로 학습을 완료하더라도 전체 개체에 대한 크레딧을 받게 되며 어떤 언어로 완료했는지에 대한 참조를 저장하지 않습니다. 이러한 로캘 중립적 완료는 학습 환경에서 카탈로그 학습 API를 구현하는 경우 이를 고려해야 하며, 콘텐츠 개체를 별도의 개체로 로드하는 경우 사용자가 학습을 완료하는 언어에 관계없이 다른 언어로 크레딧을 받고 다시 가져올 필요가 없도록 콘텐츠 개체 간에 동등성을 구현해야 합니다.
Learn에서 콘텐츠 버전 관리가 작동하는 방식과 API 출력에 반영되는 방식 이해
특히 콘텐츠는 항상 업데이트되고 있습니다. 하루에 두 번 사용 가능한 업데이트를 게시합니다. 사소한 텍스트 변경처럼 사소한 내용이거나 주요 내용을 수정, 추가, 삭제와 같은 주요 업데이트일 수 있습니다. 일반적으로 콘텐츠 포트폴리오는 관련 업무를 담당하는 사람만 수천 명이며 규모도 크고 고도로 관리되는 오픈 소스 프로젝트로 관리하여 항상 업데이트가 진행 중입니다. 프로덕션 시스템에서 Learn 카탈로그 API를 사용하는 경우 이를 인식하고 시스템에서 처리할 수 있어야 합니다.
새 콘텐츠 개체가 추가되면 응답에서 새 개체(UID로 식별됨)로 나타납니다. 콘텐츠가 수정되면 해당 last_modified 값에 따라 알 수 있습니다. 콘텐츠가 삭제되면 콘텐츠 개체가 응답에서 제거됩니다. API 응답에서 업데이트되는 콘텐츠가 약간 지연되는 경우도 있지만 사용자가 콘텐츠의 URL을 따라 갈 때 항상 최신 정보가 표시됩니다. 삭제하는 경우 이전 URL은 새로운 콘텐츠나 환경 또는 차선책으로 리디렉션됩니다.
현재 last_modified 날짜 이후의 콘텐츠 버전에 대한 참조가 없습니다.
정기적으로 데이터 새로 고침
Learn 카탈로그 API의 카탈로그 정보를 사용하여 비즈니스 프로세스를 지원하거나 고객에게 사이트 환경의 일부로 표시하는 경우 하루에 한 번 이상 콘텐츠를 새로 고침해야 합니다.
특히 콘텐츠는 항상 업데이트되고 있습니다. 하루에 두 번 사용 가능한 업데이트를 게시합니다. 사소한 텍스트 변경처럼 사소한 내용이거나 주요 내용을 수정, 추가, 삭제와 같은 주요 업데이트일 수 있습니다. 일반적으로 콘텐츠 포트폴리오는 관련 업무를 담당하는 사람만 수천 명이며 규모도 크고 고도로 관리되는 오픈 소스 프로젝트로 관리하여 항상 업데이트가 진행 중입니다. 프로덕션 시스템에서 Learn 카탈로그 API를 사용하는 경우 이를 인식하고 시스템에서 처리할 수 있어야 합니다.
개발자 설명서 권장 사항 검토
Learn 카탈로그 API 개발자 설명서에는 응답의 일부로 제공되는 데이터의 전체 목록이 제공되며 훌륭한 학습 환경 지원을 위해 각 필드를 사용하기를 추천합니다.
쿼리 논리 이해
응답을 미리 필터링하는 데 사용할 수 있는 필터가 많이 있으므로 원하는 내용만 가져와 더 작은 크기의 파일을 처리할 수 있습니다. Learn 카탈로그 API 개발자 참조 문서에서 쿼리 필터의 전체 목록을 볼 수 있습니다. 특히, 쿼리를 올바르게 구성해야 하며 요청에 둘 이상의 쿼리 매개 변수를 사용하는 경우 쿼리는 AND 연산자를 사용하여 평가됩니다.
다음 단계
Learn 카탈로그 API를 지원하는 자세한 내용은 다음 문서를 검토하세요.