Condividi tramite

Guida introduttiva: Configurare e usare i dati del Catalogo API di Microsoft Learn Platform

In questa guida introduttiva si apprenderà come configurare ed eseguire l'API della piattaforma Microsoft Learn, che include esempi per recuperare corsi, percorsi di apprendimento, moduli e certificazioni.

Prerequisiti

Prima di iniziare, assicurarsi di avere installato quanto segue:

  • Node.js (versione 18.0.0 o successiva)

    • Node.js è un runtime JavaScript che consente di eseguire codice JavaScript/TypeScript all'esterno di un Web browser. È necessario eseguire gli script di esempio e gestire i pacchetti tramite npm (Node Package Manager).
    • Scaricare da: https://nodejs.org/
    • Verificare l'installazione: node --version

  • CLI di Azure

    • L'interfaccia Command-Line di Azure è uno strumento per la gestione delle risorse di Azure dalla riga di comando. In questa guida viene usata per autenticare l'identità in modo che gli esempi possano accedere all'API Learn Platform per conto dell'utente.
    • Scaricare da: https://learn.microsoft.com/cli/azure/install-azure-cli>
    • Verificare l'installazione: az --version

  • Un account Azure

    • Per autenticare e accedere all'API microsoft Learn Platform, è necessario un account Azure con una sottoscrizione attiva. L'API usa l'ID Microsoft Entra (in precedenza Azure Active Directory) per l'autenticazione, che richiede credenziali di Azure valide. Non è previsto alcun costo per recuperare il token di autenticazione dalla sottoscrizione di Azure.
    • È necessaria una sottoscrizione di Azure attiva
    • Iscriversi all'indirizzo: https://azure.microsoft.com/free/

  • Visual Studio Code (facoltativo)

    • Visual Studio Code (VS Code) è un editor di codice gratuito e leggero con un terminale integrato, IntelliSense e supporto TypeScript. Anche se è possibile usare qualsiasi editor di testo e terminale, Visual Studio Code offre un'esperienza semplificata per l'esecuzione di questi esempi.
    • Scaricare da: https://code.visualstudio.com/
    • Verificare l'installazione: aprire Visual Studio Code e premere CTRL+' per aprire il terminale integrato

Annotazioni

Tutti i comandi scritti di seguito devono essere eseguiti in un terminale Git Bash. È possibile usare il terminale integrato di VS Code (premere CTRL+'), Windows PowerShell o prompt dei comandi.

Configurare il progetto

Seguire questa procedura per creare un nuovo progetto e installare le dipendenze necessarie.

  1. Creare una nuova cartella per il tuo progetto e accedervi.

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

  2. Inizializzare un nuovo progetto Node.js con le impostazioni predefinite. Il -y flag accetta automaticamente tutte le impostazioni predefinite.

    npm init -y

  3. Installare i pacchetti npm necessari (@azure/identity per l'autenticazione, tsx per eseguire TypeScript direttamente, typescript compilatore e @types/node per le definizioni dei tipi).

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

  4. Creare un nuovo file denominato examples.ts e incollare il codice seguente. Ciò include l'autenticazione che sfrutta le credenziali predefinite di Azure e diversi esempi delle funzionalità del catalogo disponibili tramite l'API Learn Platform.

    /**
 * 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();

Autenticare ed eseguire gli esempi

Seguire questa procedura per eseguire l'autenticazione con Azure ed eseguire il codice di esempio.

  1. Accedere all'interfaccia della riga di comando di Azure. Questo passaggio apre una finestra del browser in cui immettere le credenziali di Azure.

    az login

  2. Se si hanno più sottoscrizioni, impostarne una attiva. Sostituire <your-subscription-name> con il nome o l'ID della sottoscrizione.

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

  3. Verificare che le credenziali possano accedere all'API Learn Platform.

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

    In caso di esito positivo, verrà visualizzata una risposta JSON con un accessToken campo.

  4. Eseguire il file di esempi usando npx per eseguire il tsx pacchetto.

    npx tsx examples.ts

  5. (Facoltativo) Salvare l'output in un file usando il reindirizzamento di output.

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

Pulire le risorse

Se le risorse create in questa guida introduttiva non sono più necessarie, è possibile rimuoverle.

  1. Rimuovere la cartella del progetto e tutto il relativo contenuto.

    cd ..
rm -rf learn-api-examples

    In Windows PowerShell usare:

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

  2. (Facoltativo) Disconnettersi dall'interfaccia della riga di comando di Azure per rimuovere le credenziali memorizzate nella cache.

    az logout

Annotazioni

Questa guida introduttiva non crea risorse di Azure che comportano costi. Le chiamate API usano l'identità di Azure esistente solo per l'autenticazione.

Contenuti correlati

  • Last updated on