Microsoft Learn 目录 API(预览)

Microsoft Learn 目录 API(预览)允许你向 Microsoft Learn 发送基于 Web 的查询,并获取有关已发布内容的详细信息,如标题、所涵盖的产品和指向培训的链接。 客户可以将返回的信息与其他培训内容一起显示在他们的学习管理系统 (LMS) 中。

备注

客户可以使用此 API 显示有关可用培训的信息,但培训必须在 Microsoft Learn 上完成。

目录 API 是根据 Microsoft API 使用条款提供的。 此页面提供有关 API 的技术细节,以及如何解释返回的信息。

模块和学习路径

Microsoft Learn 的内容围绕两个元素组织:模块和学习路径 。

模块

“模块”是实际的培训内容 。 单个模块由多个 Web 页面组成,这些页面探索某项服务或技术,并经常提供某种形式的交互来尝试该技术。 每个模块都有相关的元数据来快速识别它的服务对象、涵盖内容,以及通常需要多长时间来完成。 这些详细信息可以在 Microsoft Learn 浏览页上的图形平铺中找到,如下面的屏幕截图所示。

显示单个模块的屏幕截图,其中包含来自 Microsoft Learn 网站的所有详细信息

学习路径

“学习路径”是按特定顺序呈现的相关模块的集合,以便模块之间相互构建以教授更广泛的主题 。 学习路径还包括类似于模块的描述性元数据,如以下浏览页的屏幕截图所示。

显示 Microsoft Learn 网站学习路径的屏幕截图

API 终结点

Microsoft Learn 目录 API 是一个基于 REST 的 Web API,它返回 JSON 编码的响应。

若要请求模块和学习路径的完整目录,请将“GET”请求发送到:

https://docs.microsoft.com/api/learn/catalog/

重要

请求必须使用 HTTPS 协议。

查询参数

以下是请求可能包含的查询参数。 “必需”列指示是否必须指定参数 。 必须对查询参数值进行 URL 编码。

名称 类型 必需
区域设置 支持的区域设置列表中有效的区域设置代码,例如“en-us”。 如果可用,返回的元数据将位于请求的区域设置中。 如果未提供此参数,则将使用默认值“en us”。 字符串型

API 响应

该服务可能返回以下 HTTP 状态代码。

状态代码 说明
200 成功。 响应的主体包括 JSON 编码的数据。
400 其中一个查询参数丢失或无效。
404 无法在服务器上找到该 URL。
500 意外的服务器错误。
503 该服务暂时不可用。

成功的响应将包括所有模块和学习路径的详细信息,如下所示。

提示

强烈建议按周期而非每次需要时缓存响应并刷新数据视图。

响应正文

成功的响应正文将用 JSON 编码,分为五个部分:

{
    "modules": [ ... ],
    "learningPaths": [ ... ],
    "products": [ ... ],
    "roles": [ ... ],
    "levels": [ ... ]
}

每个数组都有一个或多个 JSON 编码的对象,其中包含特定于响应部分的数据。

  1. modules:是已发布模块的数组。
  2. learningPaths:是已发布的学习路径的数组。
  3. levels:是可能的受众级别数组。
  4. roles:是可能的作业角色的数组。
  5. products:是已发布模块中包含的一系列产品和服务。

模块记录

每个模块将具有以下形式:

{
    "summary": "<p sourcefile=\"azure/principles-cloud-computing/index.yml\" sourcestartlinenumber=\"1\" jsonPath=\"/summary\">Explore the core concepts of cloud computing and how it can help your business.</p>\n",
    "levels": [
        "beginner"
    ],
    "roles": [
        "administrator",
        "business-analyst",
        "developer"
    ],
    "products": [
        "azure",
        "azure-portal",
        "azure-resource-manager"
    ],
    "uid": "learn.principles-cloud-computing",
    "type": "module",
    "title": "Cloud Concepts - Principles of cloud computing",
    "duration_in_minutes": 62,
    "rating": {
        count: 2014,
        average: 4.84
    },
    "popularity": 0.8839785477023878, 
    "icon_url": "https://docs.microsoft.com/learn/achievements/principles-cloud-computing.svg",
    "locale": "en-us",
    "last_modified": "2018-09-24T00:00:00Z",
    "url": "https://docs.microsoft.com/en-us/learn/modules/principles-cloud-computing",
    "firstUnitUrl": "https://docs.microsoft.com/en-us/learn/modules/principles-cloud-computing/1-introduction",
    "number_of_children": 10
}
字段 类型 说明
summary 字符串型 提供模块简短说明的字符串。 该值表示为 HTML 段落标记,内部文本为摘要。
levels 字符串数组 标识了解此模块所有方面所需的角色经验。
roles 字符串数组 与此模块相关的作业角色的列表。
products 字符串数组 本模块涵盖的相关产品列表。
uid 字符串型 此模块的唯一标识符 - 此值在所有 MS Learn 中都是唯一的。
type 字符串型 记录类型。 值将始终为“模块”。
title 字符串型 请求的区域设置中模块的标题,或使用美式英语作为后备。
duration_in_minutes 整型 此模块完成所需的平均时间(分钟)。
rating object 这包含 countaverage,前者是对此模块评级的用户人数,后者是评级总和 (1-5)
popularity Double 一个标准化的值 (0-1),它表示此模块的受欢迎程度
icon_url 字符串型 表示模块的 100x100“.svg”或“.png”图像的完全限定 URL 。
locale 字符串型 JSON 数据的写入语言。 如果可用,此值将是请求的区域设置,如果不可用,则为“en us”。
last_modified 日期 上一次此模块有重大修改。
url 字符串型 在请求的区域设置中,指向 Microsoft Learn 中模块的完全限定 URL。
firstUnitUrl 字符串 在请求的区域设置中,指向 Microsoft Learn 中模块的第一个单元的完全限定 URL。
number_of_children 整型 此模块包含的页数(单位)。

学习路径记录

每个学习路径都有以下形式:

{
    "summary": "<p sourcefile=\"paths/create-serverless-applications/index.yml\" sourcestartlinenumber=\"1\" jsonPath=\"/summary\">Azure Functions enable the creation of event driven, compute-on-demand systems that can be triggered by various external events. Learn how to leverage functions to execute server-side logic and build serverless architectures.</p>\n",
    "levels": [
        "beginner",
        "intermediate"
    ],
    "roles": [
        "developer",
        "solution-architect"
    ],
    "products": [
        "azure",
        "azure-portal",
        "azure-functions",
        "azure-cosmos-db",
        "azure-cloud-shell"
    ],
    "uid": "learn.create-serverless-applications",
    "type": "learningPath",
    "title": "Create serverless applications",
    "duration_in_minutes": 450,
    "rating": {
        count: 2014,
        average: 4.84
    },
    "popularity": 0.8839785477023878, 
    "icon_url": "https://docs.microsoft.com/learn/achievements/create-serverless-applications.svg",
    "locale": "en-us",
    "last_modified": "2018-12-27T00:00:00Z",
    "url": "https://docs.microsoft.com/en-us/learn/paths/create-serverless-applications",
    "firstModuleUrl": "https://docs.microsoft.com/en-us/learn/modules/choose-azure-service-to-integrate-and-automate-business-processes/",
    "modules": [
        "learn.choose-azure-service-to-integrate-and-automate-business-processes",
        "learn.create-serverless-logic-with-functions",
        "learn.execute-azure-function-with-triggers",
        "learn.chain-azure-functions-data-using-input-output-bindings",
        "learn.azure-create-long-running-serverless-workflow-with-durable-functions",
        "learn-pr.develop-test-deploy-azure-functions-core-tools",
        "learn.develop-test-deploy-azure-functions-with-visual-studio",
        "learn.azure.monitor-github-events-with-a-function-triggered-by-a-webhook",
        "learn.advocates.azure-functions-and-signalr"
    ],
    "number_of_children": 9
}
字段 类型 说明
summary 字符串型 提供学习路径简短说明的字符串。 该值表示为 HTML 段落标记,内部文本为摘要。
levels 字符串数组 标识了解此学习路径所有方面所需的角色经验。 此数组将包含基于路径中所包含模块的一个或多个值。
roles 字符串数组 此学习路径的相关工作角色列表。
products 字符串数组 本学习路径涵盖的相关产品列表。
uid 字符串型 此学习路径的唯一标识符 - 此值在所有 MS Learn 中都是唯一的。
type 字符串型 记录类型。 值将始终为“学习路径”。
title 字符串型 请求的区域设置中学习路径的标题,或使用美式英语作为后备。
duration_in_minutes 整型 此学习路径完成所需的平均时间(分钟)。 此值是来自所有模块的数据的总和。
rating object 这包含 countaverage,前者是对此学习路径评级的用户人数,后者是评级总和 (1-5)
popularity Double 一个标准化的值 (0-1),它表示此学习路径的受欢迎程度
icon_url 字符串型 表示学习路径的 100x100“.svg”或“.png”图像的完全限定 URL 。
locale 字符串型 JSON 数据的写入语言。 如果可用,此值将是请求的区域设置,如果不可用,则为“en us”。
last_modified 日期 上一次此学习路径有更改。
url 字符串型 在请求的区域设置中,指向 Microsoft Learn 中学习路径的完全限定 URL。
firstModuleUrl 字符串 在请求的区域设置中,指向 Microsoft Learn 中学习路径的第一个模块的完全限定 URL。
modules 字符串数组 此学习路径中包含的模块标识符 (uid) 列表。
number_of_children 整型 此学习路径中包含的模块数。

产品、角色和级别记录

levelsrolesproducts 集合为模块中使用的值和学习路径数据提供友好的名称。 三个集合都有相同的形状:

{
    "id": "unique-id",
    "name": "name-of-item",
    "children": [
        { "id": "unique-id", "name": "name-of-item" },
        { "id": "unique-id", "name": "name-of-item" },
           ...
    ]
}

id 将匹配每个模块和学习路径中包含的级别、角色和产品的值。 关联的 name 为条目提供了适当的英文名称。 children 数组是可选的,并为具有子关系(如产品)的值启用层次结构。

例如,以下是一组可能的角色:

{
    ...
    "roles": [
        {
            "id": "administrator",
            "name": "Administrator"
        },
        {
            "id": "ai-engineer",
            "name": "AI Engineer"
        },
        {
            "id": "business-analyst",
            "name": "Business Analyst"
        },
        {
            "id": "developer",
            "name": "Developer"
        },
        ...
    ]
}

下面是一组产品的示例,其中包含了提供更具体产品类别的子产品。

{
    ...
    "products": [
        {
            "id": "dotnet",
            "name": ".NET",
            "children": [
                { "id": "dotnet-core", "name": ".NET Core" },
                { "id": "dotnet-standard", "name": ".NET Standard" },
                { "id": "aspnet-core", "name": "ASP.NET Core" },
                { "id": "ef-core", "name": "Entity Framework Core" }
            ]
        },
        {
            "id": "ms-graph",
            "name": "Microsoft Graph"
        },
        {
            "id": "office",
            "name": "Office",
            "children": [
                { "id": "office-365", "name": "Office 365" },
                { "id": "office-add-ins", "name": "Office Add-ins" },
                { "id": "office-teams", "name": "Teams" }
            ]
        },
        {
            "id": "sql-server",
            "name": "SQL Server"
        },
        ...
    ]
}

目录 LTI 提供程序

想要将目录 API 集成到学习管理系统 (LMS) 中吗? 请查看我们的开源 LTI 应用程序

我们创建了参考代码来将目录 API 转换为 LTI 提供程序。 你可快速进行修改或将该应用程序直接安装到你的 LMS 中。 LTI 应用程序让你能够将 Microsoft Learn 模块集成到你的现有课程,同时提供 Azure 和其他 Microsoft 技术的动手体验。 学员们将从你的 LMS 路由到 Microsoft Learn,在这里他们可累积分数和成就并跟踪学习活动的进度。

目录 API 预览计划

是否要将 Microsoft Learn 内容集成到学习平台? 申请目录 API 预览 (CAP) 计划,以便我们的团队可以帮助确保提供最佳集成体验,并在将来的目录 API 版本中采用你的反馈。

反馈和支持

目录 API 目前处于预览阶段,没有服务级别协议。 如果你有建议或者在使用 API 时遇到问题,可以给团队反馈