Compartilhar via

Início Rápido: Configurar e usar os dados do catálogo de API da Plataforma Microsoft Learn

Neste Início Rápido, você aprenderá a configurar e executar a API da Plataforma Microsoft Learn, que inclui exemplos para recuperar cursos, roteiros de aprendizagem, módulos e certificações.

Pré-requisitos

Antes de começar, verifique se você tem o seguinte instalado:

  • Node.js (versão 18.0.0 ou superior)

    • Node.js é um runtime do JavaScript que permite executar código JavaScript/TypeScript fora de um navegador da Web. É necessário executar os scripts de exemplo e gerenciar pacotes por meio do npm (Gerenciador de Pacotes do Nó).
    • Baixe de: https://nodejs.org/
    • Verificar a instalação: node --version

  • Azure CLI

    • A CLI (Interface de Command-Line) do Azure é uma ferramenta para gerenciar recursos do Azure da linha de comando. Neste guia, ele é usado para autenticar sua identidade para que os exemplos possam acessar a API da Plataforma Learn em seu nome.
    • Baixe de: https://docs.microsoft.com/cli/azure/install-azure-cli
    • Verificar a instalação: az --version

  • Uma conta do Azure

    • Uma conta do Azure com uma assinatura ativa é necessária para autenticar e acessar a API da Plataforma Microsoft Learn. A API usa a ID do Microsoft Entra (antigo Azure Active Directory) para autenticação, que requer credenciais válidas do Azure. Não há custo para recuperar o token de autenticação de sua assinatura do Azure.
    • Você precisa de uma assinatura ativa do Azure
    • Inscreva-se em: https://azure.microsoft.com/free/

  • Visual Studio Code (opcional)

    • O Visual Studio Code (VS Code) é um editor de código leve e gratuito com um terminal integrado, intelliSense e suporte ao TypeScript. Embora você possa usar qualquer editor de texto e terminal, o Visual Studio Code fornece uma experiência simplificada para executar esses exemplos.
    • Baixe de: https://code.visualstudio.com/
    • Verificar a instalação: abra o Visual Studio Code e pressione Ctrl+' para abrir o terminal integrado

Observação

Todos os comandos gravados abaixo devem ser executados em um terminal do Git Bash. Você pode usar o terminal integrado do VS Code (pressione Ctrl+'), o Windows PowerShell ou o Prompt de Comando.

Configurar o projeto

Siga estas etapas para criar um novo projeto e instalar as dependências necessárias.

  1. Crie uma nova pasta para seu projeto e navegue até ela.

    mkdir learn-api-examples
cd learn-api-examples

  2. Inicialize um novo projeto de Node.js com configurações padrão. O -y sinalizador aceita automaticamente todos os padrões.

    npm init -y

  3. Instale os pacotes npm necessários (@azure/identity para autenticação, tsx para executar TypeScript diretamente, typescript compilador e @types/node para definições de tipo).

    npm install @azure/identity tsx typescript @types/node

  4. Crie um novo arquivo chamado examples.ts e cole o código abaixo. Isso inclui a autenticação aproveitando as Credenciais Padrão do Azure e vários exemplos dos recursos de catálogo disponíveis por meio da API da Plataforma Learn.

    /**
 * Microsoft Learn Platform API Examples
 * API Version: 2023-11-01-preview
 * Base URL: https://learn.microsoft.com/api/v1
 *
 * Authentication: OAuth2 with scope https://learn.microsoft.com/.default
 */

import { DefaultAzureCredential } from "@azure/identity";

const API_BASE_URL = "https://learn.microsoft.com/api/v1";
const API_VERSION = "2023-11-01-preview";

// ============================================================================
// AUTHENTICATION HELPER
// ============================================================================

async function getAccessToken(): Promise<string> {
  const credential = new DefaultAzureCredential();
  const token = await credential.getToken("https://learn.microsoft.com/.default");
  return token.token;
}

/**
 * Helper to handle API response with error checking
 */
async function handleResponse(response: Response, label: string): Promise<void> {
  if (!response.ok) {
    const text = await response.text();
    console.log(`${label} Error: ${response.status} ${response.statusText}`);
    console.log("Response:", text || "(empty)");
    return;
  }

  const text = await response.text();
  if (!text) {
    console.log(`${label}: (empty response)`);
    return;
  }

  try {
    const data = JSON.parse(text);
    console.log(`${label}:`, JSON.stringify(data, null, 2));
  } catch (e) {
    console.log(`${label} Parse Error: Invalid JSON`);
    console.log("Raw response:", text.substring(0, 500));
  }
}

// ============================================================================
// TRAINING ENDPOINTS
// ============================================================================

/**
 * List all courses with optional filters
 * GET /courses
 */
async function listCourses(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/courses?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Courses");
}

/**
 * Get a specific course by ID
 * GET /courses/{id}
 */
async function getCourse(courseId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/courses/${courseId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Course");
}

/**
 * List all learning paths
 * GET /learning-paths
 */
async function listLearningPaths(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  subjects?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.subjects) params.append("subjects", options.subjects.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/learning-paths?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Learning Paths");
}

/**
 * Get a specific learning path by ID
 * GET /learning-paths/{id}
 */
async function getLearningPath(learningPathId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/learning-paths/${learningPathId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Learning Path");
}

/**
 * List all modules
 * GET /modules
 */
async function listModules(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  subjects?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.subjects) params.append("subjects", options.subjects.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/modules?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Modules");
}

/**
 * Get a specific module by ID
 * GET /modules/{id}
 */
async function getModule(moduleId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/modules/${moduleId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Module");
}

/**
 * Get a specific unit by ID
 * GET /units/{id}
 */
async function getUnit(unitId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/units/${unitId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Unit");
}

// ============================================================================
// CREDENTIALS ENDPOINTS
// ============================================================================

/**
 * List all certifications
 * GET /certifications
 */
async function listCertifications(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  subjects?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.subjects) params.append("subjects", options.subjects.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/certifications?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Certifications");
}

/**
 * Get a specific certification by ID
 * GET /certifications/{id}
 */
async function getCertification(certificationId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/certifications/${certificationId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Certification");
}

/**
 * List all exams
 * GET /exams
 */
async function listExams(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/exams?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Exams");
}

/**
 * Get a specific exam by ID
 * GET /exams/{id}
 */
async function getExam(examId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/exams/${examId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Exam");
}

/**
 * List all applied skills
 * GET /applied-skills
 */
async function listAppliedSkills(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  subjects?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.subjects) params.append("subjects", options.subjects.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/applied-skills?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Applied Skills");
}

/**
 * Get a specific applied skill by ID
 * GET /applied-skills/{id}
 */
async function getAppliedSkill(appliedSkillId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/applied-skills/${appliedSkillId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Applied Skill");
}

// ============================================================================
// PAGINATION HELPER
// ============================================================================

/**
 * Helper to handle paginated responses
 */
async function fetchAllPages<T>(initialUrl: string, token: string): Promise<T[]> {
  const allItems: T[] = [];
  let nextLink: string | undefined = initialUrl;

  while (nextLink) {
    const response = await fetch(nextLink, {
      method: "GET",
      headers: {
        "Accept": "application/json",
        "Authorization": `Bearer ${token}`
      }
    });

    const data = await response.json();
    allItems.push(...data.value);
    nextLink = data.nextLink;
  }

  return allItems;
}

// ============================================================================
// EXAMPLE USAGE
// ============================================================================

async function main() {
  try {
    // List beginner-level certifications for Azure
    console.log("=== Listing Azure certifications (beginner level) ===");
    await listCertifications({
      levels: ["beginner"],
      products: ["azure"],
      maxpagesize: 5
    });

    // List certifications
    console.log("\n=== Listing certifications ===");
    await listCertifications({ maxpagesize: 5 });

    // List all Spanish learning paths
    console.log("\n=== Listing Spanish learning paths ===");
    await listLearningPaths({ locale: "es-es", maxpagesize: 5 });

    // Get a specific learning path by ID
    console.log("\n=== Getting learning path: learn.introduction-ai-azure ===");
    await getLearningPath("learn.introduction-ai-azure");

    // Get a specific module by ID
    console.log("\n=== Getting module: learn.wwl.fundamentals-generative-ai ===");
    await getModule("learn.wwl.fundamentals-generative-ai");

    // Get a specific unit by ID
    console.log("\n=== Getting unit: learn.wwl.fundamentals-generative-ai.agents ===");
    await getUnit("learn.wwl.fundamentals-generative-ai.agents");

    // Get a specific applied skill by ID
    console.log("\n=== Getting applied skill: applied-skill.deploy-and-configure-azure-monitor ===");
    await getAppliedSkill("applied-skill.deploy-and-configure-azure-monitor");

    // Get a specific certification by ID
    console.log("\n=== Getting certification: certification.d365-functional-consultant-customer-service ===");
    await getCertification("certification.d365-functional-consultant-customer-service");

    // Get a specific exam by ID
    console.log("\n=== Getting exam: exam.77-881 ===");
    await getExam("exam.77-881");

    // Get a specific instructor-led course by ID
    console.log("\n=== Getting instructor-led course: course.ai-900t00 ===");
    await getCourse("course.ai-900t00");

  } catch (error) {
    console.error("Error:", error);
  }
}

main();

Autenticar e executar os exemplos

Siga estas etapas para autenticar com o Azure e executar o código de exemplo.

  1. Entre na CLI do Azure. Esta etapa abre uma janela do navegador na qual você insere suas credenciais do Azure.

    az login

  2. Se você tiver várias assinaturas, defina a ativa. Substitua <your-subscription-name> pelo nome ou ID da assinatura.

    az account set --subscription "<your-subscription-name>"

  3. Verifique se suas credenciais podem acessar a API da Plataforma Learn.

    az account get-access-token --resource https://learn.microsoft.com

    Se tiver êxito, você verá uma resposta JSON com um accessToken campo.

  4. Execute o arquivo de exemplos usando npx para executar o tsx pacote.

    npx tsx examples.ts

  5. (Opcional) Salve a saída em um arquivo usando o redirecionamento de saída.

    npx tsx examples.ts > output.txt 2>&1

Limpar os recursos

Se você não precisar mais dos recursos criados neste início rápido, poderá removê-los.

  1. Remova a pasta do projeto e todo o seu conteúdo.

    cd ..
rm -rf learn-api-examples

    No Windows PowerShell, use:

    cd ..
Remove-Item -Recurse -Force learn-api-examples

  2. (Opcional) Saia da CLI do Azure para remover credenciais armazenadas em cache.

    az logout

Observação

Este início rápido não cria nenhum recurso do Azure que incorre em custos. As chamadas à API usam sua identidade existente do Azure somente para autenticação.

Conteúdo relacionado

  • Last updated on