Invoke-RestMethod în PowerShell

Invoke-RestMethod [-Uri] <Uri> [-Method <WebRequestMethod>] [-Headers <IDictionary>] [-Body <Object>] [-ContentType <String>]

Ce face Invoke-RestMethod

Invoke-RestMethod trimite o cerere HTTP la fel ca Invoke-WebRequest, dar întoarce direct datele: un răspuns JSON devine obiecte [pscustomobject], un răspuns XML devine XmlDocument, iar un flux RSS sau Atom devine lista de articole. Astfel scrii $comanda.total în loc să parsezi text. Când API-ul întoarce o listă, primești un tablou.

Pentru o cerere POST, un tabel hash dat la -Body este trimis ca formular (application/x-www-form-urlencoded, tipul implicit pentru POST). Ca să trimiți JSON, convertești datele cu ConvertTo-Json și pui -ContentType 'application/json'. Din PowerShell 7.4 cererile sunt codificate implicit în UTF-8; în versiunile mai vechi adaugă charset=utf-8 în -ContentType ca diacriticele să ajungă corect.

PowerShell 6 și 7 au adăugat parametri utili: -Authentication Bearer cu -Token (6.0), -ResponseHeadersVariable (6.0), -FollowRelLink pentru paginare (6.0), -StatusCodeVariable și -SkipHttpErrorCheck (7.0). Atenție: un tablou întors de API trece prin pipeline ca un singur obiect [Object[]]; ca să fie enumerat element cu element, pune comanda în paranteze. Alias: irm.

Parametri

Parametru	Descriere
-Uri	Adresa endpoint-ului; parametru pozițional.
-Method	Metoda HTTP: Get (implicit), Post, Put, Patch, Delete etc.
-Body	Datele trimise: tabel hash (formular sau parametri GET) ori text, de exemplu JSON produs cu ConvertTo-Json.
-ContentType	Tipul conținutului trimis; pentru JSON, application/json. Implicit: formular la POST, application/json la PUT.
-Headers	Tabel hash cu antete, de exemplu o cheie de API.
-Authentication / -Token	Bearer sau OAuth cu un token SecureString în -Token, ori Basic cu -Credential. Din PowerShell 6.0.
-StatusCodeVariable	Numele (fără $) unei variabile în care se pune codul HTTP. Din PowerShell 7.0.
-ResponseHeadersVariable	Numele unei variabile care primește antetele răspunsului. Din PowerShell 6.0.
-SkipHttpErrorCheck	Nu aruncă eroare la coduri 4xx și 5xx; răspunsul este întors normal. Din PowerShell 7.0.
-FollowRelLink / -MaximumFollowRelLink	Urmează automat linkurile de paginare (antetul Link) și limitează câte pagini citește.
-OutFile	Salvează răspunsul într-un fișier în loc să-l întoarcă.

Ce returnează

Pentru JSON, obiecte PSObject ([pscustomobject]); pentru XML, XmlDocument; altfel String sau Int64.

Exemple

Exemplul 1: Citirea unei liste de comenzi dintr-un API

API-ul întoarce un tablou JSON, iar PowerShell afișează obiectele ca tabel.

Invoke-RestMethod -Uri 'https://api.exemplu.ro/comenzi?oras=Iasi'

Ieșire în terminal

id client oras total
-- ------ ---- -----
17 Ana    Iași 249.5
18 Mihai  Iași   120

Exemplul 2: Trimiterea unei comenzi noi în format JSON

Datele sunt convertite cu ConvertTo-Json; serverul răspunde cu comanda creată.

$comanda = @{ client = 'Mihai'; oras = 'Cluj'; total = 89.9 } | ConvertTo-Json
Invoke-RestMethod -Uri https://api.exemplu.ro/comenzi -Method Post -Body $comanda -ContentType 'application/json; charset=utf-8'

Ieșire în terminal

id client oras total
-- ------ ---- -----
19 Mihai  Cluj  89.9

Exemplul 3: Codul HTTP al unei cereri eșuate

-SkipHttpErrorCheck evită eroarea, iar -StatusCodeVariable cod pune codul în $cod; mesajul vine din JSON-ul de eroare al API-ului.

$r = Invoke-RestMethod -Uri https://api.exemplu.ro/comenzi/999 -SkipHttpErrorCheck -StatusCodeVariable cod
$cod
$r.mesaj

Ieșire în terminal

404
Comanda nu există

Greșeli frecvente

• Dai un tabel hash la -Body și aștepți ca serverul să primească JSON: fără conversie, datele pleacă drept formular; folosește ConvertTo-Json și -ContentType 'application/json'.
• Trimiți obiecte imbricate cu ConvertTo-Json fără -Depth: adâncimea implicită este 2, iar nivelurile mai adânci sunt transformate în text.
• Pui -StatusCodeVariable $cod cu dolar: parametrul primește numele variabilei, deci scrie -StatusCodeVariable cod.
• Trimiți rezultatul direct la ForEach-Object și primești un singur element: tabloul întors nu e enumerat; scrie (Invoke-RestMethod ...) | ForEach-Object { ... }.

Comenzi înrudite

• Invoke-WebRequest: Trimite o cerere HTTP sau HTTPS și întoarce răspunsul complet (cod de stare, antete, conținut, linkuri); poate și descărca fișiere.
• ConvertTo-Json: Transformă obiecte PowerShell într-un șir JSON, de exemplu pentru un fișier de configurare sau corpul unei cereri către un API.
• ConvertFrom-Json: Transformă un text JSON în obiecte PowerShell (sau hashtable-uri), ale căror câmpuri le citești cu punct.
• Hashtable (@{}): Un hashtable ține perechi cheie-valoare; [ordered] păstrează ordinea cheilor, iar [pscustomobject] transformă perechile într-un obiect.
• try / catch / finally: try/catch prinde erorile care opresc o comandă, iar finally rulează mereu; pentru erorile obișnuite ale cmdlet-urilor pui -ErrorAction Stop.