پاورشل برای برنامه‌نویسان

درسنامه: پارس JSON پاسخ API

این درسنامه درباره‌ی نحوه‌ی کار با داده‌های JSON در PowerShell است، به‌ویژه زمانی که از یک REST API پاسخ دریافت می‌کنی. JSON (JavaScript Object Notation) یکی از رایج‌ترین فرمت‌ها برای تبادل داده بین سرویس‌ها است و در اکثر APIها استفاده می‌شود. در PowerShell، JSON به‌طور مستقیم پشتیبانی می‌شود و ابزارهای داخلی برای خواندن، تبدیل و دسترسی به مقادیر در آن وجود دارد.

۱. فرمت JSON چیست و چرا اهمیت دارد

فرمت JSON یک ساختار متنی ساده است که داده‌ها را به‌صورت کلید-مقدار سازمان‌دهی می‌کند.

مثلاً یک پاسخ از API ممکن است به شکل زیر باشد:

{
  "name": "Ali",
  "age": 27,
  "skills": ["Python", "PowerShell", "Data Analysis"]
}

در PowerShell وقتی چنین داده‌ای از یک API می‌گیری، آن را باید به یک شی قابل استفاده تبدیل کنی تا بتوانی به مقادیرش دسترسی داشته باشی.

۲. دریافت JSON از API

زمانی که با Invoke-RestMethod کار می‌کنی، PowerShell به‌صورت خودکار JSON را پارس (تجزیه) و به شی تبدیل می‌کند.

به عنوان مثال:

$response = Invoke-RestMethod -Uri "https://api.github.com/users/octocat"

در این حالت، $response دیگر یک رشته JSON نیست، بلکه یک شی PowerShell است.

می‌توانی مستقیماً به ویژگی‌های آن دسترسی پیدا کنی:

$response.login
$response.id
$response.public_repos

پاورشل خودش تشخیص می‌دهد که داده از نوع JSON است و آن را به ساختار شیء تبدیل می‌کند.

۳. تبدیل رشته JSON دستی به شی

اگر داده‌ی JSON را از منبع دیگری گرفته باشی (مثلا از فایل یا یک رشته‌ی متنی)، باید خودت آن را تبدیل کنی.

برای این کار از دستور ConvertFrom-Json استفاده می‌شود.

مثال:

$jsonText = '{"name": "Ali", "age": 27, "skills": ["Python", "PowerShell"]}'
$data = $jsonText | ConvertFrom-Json

الان $data یک شیء است، و می‌توانی با نقطه به فیلدهایش دسترسی داشته باشی:

$data.name
$data.skills[0]

۴. کار با JSON چند سطحی (تو در تو)

در JSONهای واقعی، داده‌ها معمولاً تو در تو هستند. مثلاً:

{
  "user": {
    "name": "Ali",
    "contact": {
      "email": "ali@example.com",
      "phone": "09120000000"
    }
  }
}

اگر چنین داده‌ای را از API گرفتی یا از فایل خواندی، با ConvertFrom-Json آن را تبدیل کن:

$json = Get-Content "user.json" | ConvertFrom-Json
$json.user.name
$json.user.contact.email

PowerShell با استفاده از نقطه (.) به تو اجازه می‌دهد به هر سطح از JSON دسترسی پیدا کنی، درست مثل کار با Properties یک Object.

۵. کار با JSONهایی که آرایه دارند

خیلی از APIها داده را در قالب آرایه (لیست) برمی‌گردانند، مثلاً:

[
  {"id": 1, "name": "Ali"},
  {"id": 2, "name": "Sara"},
  {"id": 3, "name": "Nima"}
]

در PowerShell، چنین پاسخی به یک آرایه از اشیاء تبدیل می‌شود.

می‌توانی به‌صورت زیر از آن استفاده کنی:

$response = Invoke-RestMethod -Uri "https://api.example.com/users"
$response[0].name

یا با حلقه foreach:

foreach ($user in $response) {
    Write-Host "User: $($user.name)"
}

این کار برای نمایش یا پردازش مجموعه‌ای از داده‌ها (مثل کاربران، محصولات، یا پیام‌ها) بسیار کاربردی است.

۶. تبدیل شی PowerShell به JSON

گاهی لازم است داده‌ای که خودت در PowerShell ساخته‌ای را در قالب JSON بفرستی (مثلاً در درخواست POST).

برای این کار از ConvertTo-Json استفاده می‌شود.

مثال:

$user = @{
    name = "Ali"
    age = 27
    skills = @("Python", "PowerShell")
}

$jsonBody = $user | ConvertTo-Json

حالا $jsonBody شامل یک رشته JSON است که می‌توانی آن را در درخواست API استفاده کنی:

Invoke-RestMethod -Uri "https://api.example.com/addUser" -Method Post -Body $jsonBody -ContentType "application/json"

۷. ذخیره و بارگذاری JSON از فایل

گاهی لازم است پاسخ API را ذخیره و بعداً دوباره استفاده کنی.

ذخیره JSON در فایل:

$response | ConvertTo-Json | Out-File "C:\Temp\data.json"

خواندن JSON از فایل:

$data = Get-Content "C:\Temp\data.json" | ConvertFrom-Json
$data.name

۸. بررسی نوع داده‌ها بعد از تبدیل

بعد از پارس کردن JSON، می‌توانی نوع داده را بررسی کنی تا بفهمی با چه ساختاری کار می‌کنی:

$data.GetType().Name

اگر خروجی مثلاً PSCustomObject باشد، یعنی با یک شیء کار می‌کنی.

اگر Object[] باشد، یعنی داده‌ات آرایه‌ای از اشیاء است.

۹. فیلتر کردن داده از JSON با PowerShell

می‌توانی از دستورات فیلترینگ استفاده کنی تا فقط بخشی از JSON را بگیری.

مثلاً اگر لیستی از کاربران داری و می‌خواهی فقط نام آن‌هایی را که سن بالای 25 دارند ببینی:

$response | Where-Object { $_.age -gt 25 } | Select-Object name

این دستور فقط کاربرانی را نشان می‌دهد که مقدار age آن‌ها بیش از ۲۵ است.

جمع‌بندی

• پس JSON فرمت اصلی داده در APIهاست.
• با Invoke-RestMethod، PowerShell به‌صورت خودکار JSON را پارس می‌کند.
• اگر داده‌ی JSON را به‌صورت متنی داری، از ConvertFrom-Json برای تبدیل آن به شیء استفاده کن.
• برای ارسال داده به API، از ConvertTo-Json استفاده کن.
• PowerShell JSONهای تو در تو و آرایه‌ای را هم به‌خوبی پشتیبانی می‌کند.

با یادگیری پارس JSON در PowerShell، می‌توانی به‌راحتی داده‌های هر API مدرن را دریافت، فیلتر و در اسکریپت‌های خودت استفاده کنی.