مشاركة عبر

البدء السريع: إعداد واستخدام بيانات كتالوج واجهة برمجة تطبيقات Microsoft Learn Platform

في هذا البداية السريعة، تتعلم كيفية إعداد وتشغيل واجهة برمجة تطبيقات Microsoft Learn Platform، والتي تتضمن أمثلة لاسترجاع الدورات ومسارات التعلم والوحدات والشهادات.

المتطلبات الأساسية

قبل أن تبدأ، تأكد من أنك قمت بتثبيت ما يلي:

  • Node.js (الإصدار 18.0.0 أو أعلى)

    • Node.js هو تشغيل جافا سكريبت يسمح لك بتشغيل كود جافا سكريبت/تايب سكريبت خارج متصفح الويب. يطلب تنفيذ السكريبتات النموذجية وإدارة الحزم عبر npm (مدير حزم العقد).
    • تحميل من: https://nodejs.org/
    • تحقق من التثبيت: node --version

  • Azure CLI

    • واجهة Azure Command-Line (CLI) هي أداة لإدارة موارد Azure من سطر الأوامر. في هذا الدليل، يستخدم ذلك لتوثيق هويتك حتى تتمكن الأمثلة من الوصول إلى واجهة Learn Platform نيابة عنك.
    • تحميل من: https://learn.microsoft.com/cli/azure/install-azure-cli>
    • تحقق من التثبيت: az --version

  • حساب Azure

    • يتطلب الأمر حساب Azure مع اشتراك نشط للمصادقة والوصول إلى واجهة برمجة تطبيقات Microsoft Learn Platform. تستخدم واجهة برمجة التطبيقات Microsoft Entra ID (المعروف سابقا باسم Azure Active Directory) للمصادقة، والتي تتطلب بيانات اعتماد Azure الصالحة. لا توجد تكلفة لاسترجاع رمز المصادقة من اشتراكك في أزور.
    • تحتاج إلى اشتراك نشط في Azure
    • سجل على: https://azure.microsoft.com/free/

  • كود فيجوال ستوديو (اختياري)

    • كود فيجوال ستوديو (VS code) هو محرر كود مجاني وخفيف الوزن مزود بطرفية مدمجة، ودعم IntelliSense، وTypeScript. بينما يمكنك استخدام أي محرر نصوص أو طرفية، يوفر كود Visual Studio تجربة مبسطة لتشغيل هذه الأمثلة.
    • تحميل من: https://code.visualstudio.com/
    • تحقق من التثبيت: افتح كود Visual Studio واضغط Ctrl+' لفتح الطرفية المدمجة

‏‫ملاحظة‬

جميع الأوامر المكتوبة أدناه يجب أن تشغل في محطة Git Bash. يمكنك استخدام الطرفية المدمجة في VS Code (اضغط Ctrl+')، أو Windows PowerShell، أو موجه الأوامر.

إعداد المشروع

اتبع هذه الخطوات لإنشاء مشروع جديد وتثبيت التبعيات المطلوبة.

  1. أنشئ مجلد جديد لمشروعك وانتقل إليه.

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

  2. قم بتهيئة مشروع Node.js جديد بالإعدادات الافتراضية. العلم -y يقبل تلقائيا جميع الإعدادات الافتراضية.

    npm init -y

  3. تثبيت حزم npm المطلوبة (@azure/identity للمصادقة، tsx لتشغيل TypeScript مباشرة، typescript المترجم، وتعريفات @types/node الأنواع).

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

  4. أنشئ ملفا جديدا يسمى examples.ts والصق الكود أدناه. يشمل ذلك المصادقة باستخدام بيانات اعتماد Azure الافتراضية وعدة أمثلة على قدرات الكتالوج المتاحة من خلال واجهة 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();

قم بالتحقق من الشهادات وتشغيل الأمثلة

اتبع هذه الخطوات للمصادقة باستخدام Azure وتشغيل كود المثال.

  1. تسجيل الدخول إلى Azure CLI. تفتح هذه الخطوة نافذة متصفح حيث تدخل بيانات اعتماد Azure الخاصة بك.

    az login

  2. إذا كان لديك عدة اشتراكات، حدد الاشتراك النشط. استبدلها <your-subscription-name> باسم اشتراكك أو معرفك.

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

  3. تحقق من إمكانية الوصول إلى واجهة برمجة تطبيقات Learn Platform.

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

    إذا نجحت، سترى استجابة JSON مع accessToken حقل.

  4. شغل ملف الأمثلة لتنفيذ npx الحزمة tsx .

    npx tsx examples.ts

  5. (اختياري) احفظ الإخراج في ملف باستخدام إعادة توجيه المخرج.

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

تنظيف الموارد

إذا لم تعد بحاجة إلى الموارد التي تم إنشاؤها في هذا البدء السريع، يمكنك إزالتها.

  1. أزل مجلد المشروع وكل محتوياته.

    cd ..
rm -rf learn-api-examples

    على نظام Windows PowerShell، استخدم:

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

  2. (اختياري) قم بتسجيل الخروج من Azure CLI لإزالة بيانات الاعتماد المخزنة مؤقتا.

    az logout

‏‫ملاحظة‬

هذا البدء السريع لا ينشئ أي موارد Azure تتحمل تكاليف. استدعاءات واجهة برمجة التطبيقات تستخدم هوية Azure الحالية الخاصة بك فقط للمصادقة.

المحتوى ذو الصلة

  • Last updated on