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

درسنامه: فراخوانی REST API با Invoke-RestMethod و Invoke-WebRequest

در این درسنامه یاد می‌گیری چطور از PowerShell برای برقراری ارتباط با REST APIها استفاده کنی. REST API یکی از متداول‌ترین روش‌ها برای تبادل داده بین نرم‌افزارها و سرویس‌های وب است. PowerShell ابزارهای داخلی قدرتمندی برای کار با API دارد، به‌ویژه دو دستور اصلی:

Invoke-RestMethod و Invoke-WebRequest.

۱. مفهوم کلی REST API

مفهوم REST (Representational State Transfer) یک الگوی طراحی برای ارتباط سرویس‌ها از طریق HTTP است.

در REST، داده‌ها معمولاً در قالب JSON ارسال و دریافت می‌شوند و از متدهای استاندارد HTTP مثل GET, POST, PUT, و DELETE استفاده می‌شود.

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

۲. دستور Invoke-RestMethod

این دستور برای کار مستقیم با داده‌های API طراحی شده است. وقتی از API داده‌ای (معمولاً JSON) دریافت می‌کنی، PowerShell آن را به‌صورت خودکار به شیء تبدیل می‌کند تا بتوانی به‌صورت مستقیم با آن کار کنی.

مثال ۱: ارسال درخواست GET

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

در این مثال، پاسخ JSON از GitHub گرفته می‌شود و به صورت شیء PowerShell درمی‌آید. می‌توانی به‌راحتی به ویژگی‌های مختلف آن مثل name یا public_repos دسترسی داشته باشی.

مثال ۲: ارسال درخواست POST

اگر بخواهی داده‌ای را به یک سرور بفرستی (مثلاً برای لاگین یا ایجاد رکورد جدید)، از -Method Post و -Body استفاده می‌کنی:

$body = @{
    username = "testuser"
    password = "mypassword"
}

$response = Invoke-RestMethod -Uri "https://api.example.com/login" `
    -Method Post `
    -Body ($body | ConvertTo-Json) `
    -ContentType "application/json"

$response.token

در اینجا ابتدا داده‌ها به JSON تبدیل می‌شوند و سپس در بدنه‌ی درخواست فرستاده می‌شوند.

مثال ۳: استفاده از Headerها

بعضی از APIها نیاز به header خاص دارند، مثلاً کلید احراز هویت (API Key):

$headers = @{
    "Authorization" = "Bearer my_api_token"
}

$response = Invoke-RestMethod -Uri "https://api.example.com/data" -Headers $headers

در این حالت PowerShell هدرهای لازم را همراه درخواست ارسال می‌کند.

۳. دستور Invoke-WebRequest

این دستور مشابه Invoke-RestMethod است، اما به‌جای تمرکز روی داده‌های JSON یا XML، برای دریافت کامل پاسخ وب (شامل HTML، headerها، cookieها و فایل‌ها) استفاده می‌شود.

در واقع Invoke-WebRequest بیشتر برای اسکرپینگ وب‌سایت‌ها یا دانلود فایل‌ها کاربرد دارد.

مثال ۱: دانلود فایل

Invoke-WebRequest -Uri "https://example.com/file.zip" -OutFile "C:\Temp\file.zip"

در این مثال، فایل مستقیماً از وب دانلود و ذخیره می‌شود.

مثال ۲: واکشی HTML صفحه

$response = Invoke-WebRequest -Uri "https://www.example.com"
$html = $response.Content

در اینجا محتوای HTML سایت در $response.Content ذخیره می‌شود و می‌توانی آن را پردازش یا ذخیره کنی.

۴. تفاوت بین Invoke-RestMethod و Invoke-WebRequest

• Invoke-RestMethod: برای کار با APIهایی که داده (JSON/XML) برمی‌گردانند. خروجی مستقیماً به اشیاء PowerShell تبدیل می‌شود.
• Invoke-WebRequest: برای دانلود فایل، گرفتن HTML، یا دسترسی به جزئیات پاسخ (مثل Headerها یا Cookies).

اگر فقط می‌خواهی داده‌ی JSON را از API بگیری، از Invoke-RestMethod استفاده کن.

اگر به اطلاعات خام وب (مثل منبع HTML یا فایل) نیاز داری، از Invoke-WebRequest استفاده کن.

۵. کار با متدهای مختلف HTTP

GET

برای گرفتن داده از سرور:

Invoke-RestMethod -Uri "https://api.example.com/users"

POST

برای ارسال داده:

Invoke-RestMethod -Uri "https://api.example.com/users" -Method Post -Body '{"name":"Ali"}' -ContentType "application/json"

PUT

برای به‌روزرسانی داده موجود:

Invoke-RestMethod -Uri "https://api.example.com/users/1" -Method Put -Body '{"name":"Ali Updated"}' -ContentType "application/json"

DELETE

برای حذف داده:

Invoke-RestMethod -Uri "https://api.example.com/users/1" -Method Delete

۶. مدیریت خطا در درخواست‌های API

اگر درخواست با خطا مواجه شود (مثلاً سرور پاسخ 404 یا 500 دهد)، PowerShell استثنا (Exception) تولید می‌کند.

می‌توانی با try/catch آن را مدیریت کنی:

try {
    $result = Invoke-RestMethod -Uri "https://api.example.com/wrong-endpoint"
}
catch {
    Write-Error "Request failed: $($_.Exception.Message)"
}

این کار مخصوصاً برای اسکریپت‌هایی که با چندین درخواست کار می‌کنند بسیار مهم است.

۷. کار با پاسخ‌های JSON و ذخیره آن‌ها

می‌توانی پاسخ JSON را در فایل ذخیره کنی:

$response = Invoke-RestMethod -Uri "https://api.github.com/users/octocat"
$response | ConvertTo-Json | Out-File "C:\Temp\octocat.json"

یا اگر فایل JSON داری و می‌خواهی دوباره از آن استفاده کنی:

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

۸. ترکیب با Automation

از آنجا که PowerShell ابزار مدیریت سیستم است، می‌توانی APIها را با عملیات سیستمی ترکیب کنی.

مثلاً داده‌ی کاربران را از API بگیری و به CSV تبدیل کنی:

$users = Invoke-RestMethod -Uri "https://api.example.com/users"
$users | Export-Csv "C:\Temp\users.csv" -NoTypeInformation

جمع‌بندی

دستورات Invoke-RestMethod و Invoke-WebRequest دو ابزار کلیدی برای برقراری ارتباط با سرویس‌های وب هستند.

• اگر هدفت دریافت یا ارسال داده‌ی JSON/XML است، از Invoke-RestMethod استفاده کن.
• اگر می‌خواهی فایل‌ها یا HTML را دانلود و تجزیه‌کنی، از Invoke-WebRequest استفاده کن.

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