REST API'leri ve PowerShell'in Invoke-RestMethod'uyla çalışma

PowerShell'i kullanarak uygulama programlama arayüzlerine (API'ler) sıklıkla erişiyor musunuz? Belki de istiyorsun ama nereden başlayacağını bilmiyor musun? İster bir PowerShell uzmanı olun ister yeni başlıyor olun, bu eğitimde size Invoke-RestMethod adı verilen API'lerle etkileşim kuran yerleşik bir PowerShell cmdlet'i anlatılmaktadır.

Bu makalede temsili durum aktarımı (REST) API'leriyle çalışmanın, GET ve POST isteklerinin kullanılması, kimlik doğrulama, dosyaların nasıl indirileceği ve daha fazlasını kapsayan birçok farklı yolunu öğreneceksiniz!

Özetle Invoke-RestMethod

REST API'ye veri almanız veya göndermeniz gerektiğinde bir istemciye ihtiyacınız vardır. PowerShell dünyasında bu istemci Invoke-RestMethod cmdlet'idir. Bu cmdlet, çeşitli HTTP yöntemlerini kullanarak HTTP isteklerini REST API uç noktalarına gönderir.

HTTP yöntemleri daha sonra REST API'lerine bir kaynak üzerinde gerçekleştirilecek çeşitli eylemleri gerçekleştirme talimatı verir.

Resmi HTTP yöntemleri GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE ve PATCH'tir ancak bazı API'ler özel yöntemler uygulayabilir.

Invoke-RestMethod cmdlet'i, kimlik doğrulama, farklı HTTP üstbilgileri gönderme, HTTP gövdeleri de dahil olmak üzere tüm HTTP yöntemlerini destekler ve ayrıca JSON ve XML yanıtlarını otomatik olarak PowerShell nesnelerine çevirir. Invoke-RestMethod cmdlet'i, REST API'leriyle etkileşimde bulunmak için kullanılan PowerShell cmdlet'idir!

Önkoşullar

Bu eğitimdeki birçok demoyu takip etmek istiyorsanız aşağıdakilere sahip olduğunuzdan emin olun:

PowerShell 7.0 veya üzeri yüklü. Bu eğitimde Windows 10 makinesi ve PowerShell 7.1 kullanılmaktadır.

Daha fazla uzatmadan PowerShell konsolunuzu ve/veya kod düzenleyicinizi açın ve başlayalım!

Basit bir GET isteği yoluyla Veri Alma

En basit örnekle başlayalım; GET isteğiyle bir REST API'yi sorgulamak. Invoke-RestMethod çok şey yapabilir, ancak önce temelleri anlamanız gerekir.

Bir REST API uç noktasına basit bir GET isteği göndermek için yalnızca tek bir parametreye ihtiyacınız vardır: Uri. Uri parametresi, Invoke-RestMethod'a uç noktanın nerede olduğunu söyleyen şeydir.

Örneğin aşağıdaki komutu çalıştırın. Bu komut, JSONPlaceholder API'lerinin posts uç noktasını sorgular ve post kaynaklarının bir listesini döndürür.

JSONPlaceholder sitesi, test için ücretsiz bir sahte API sunar ve bu, Invoke-RestMethod komutuyla gerçek sorgu örneklerini göstermek için kullanılır.

Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts"

REST uç noktası https://jsonplaceholder.typicode.com/posts veri döndürdüğünde, yukarıda gördüğünüz gibi Nice PowerShell nesnelerinde döndürmez. Bunun yerine verileri JSON formatında döndürür. Invoke-RestMethod sizin için JSON'u otomatik olarak PowerShell nesnelerine dönüştürdü.

Aşağıda PowerShell'in, PowerShell dizisindeki tek bir öğeye bakıp üzerinde GetType() yöntemini çalıştırarak çıktıyı PSCustomObject türüne dönüştürdüğünü görebilirsiniz.

# Store the API GET response in a variable ($Posts).
$Posts = Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts"

# Run the GetType() method against the first item in the array, identified by its index of 0.
$Posts[0].GetType()

Bir API'de kimlik doğrulaması

Önceki bölümde, GET yöntemini kullanarak genel bir REST API'yi sorguladınız. API herhangi bir kimlik doğrulama gerektirmiyordu. Ancak çoğu zaman bir REST API'sinde kimlik doğrulaması yapmanız gerekir.

REST API'sinde kimlik doğrulamanın en yaygın yollarından ikisi Temel (kullanıcı adı/parola) veya Taşıyıcı (belirteç) kimlik doğrulamasını kullanmaktır. Oldukça farklı olan bu iki kimlik doğrulama şemasını birbirinden ayırmak için, istek gönderilirken Yetkilendirme HTTP başlığının kullanılması gerekir.

Şimdi HTTP üstbilgilerini (özellikle Yetkilendirme HTTP üstbilgisini) REST uç noktalarına göndermek için Invoke-RestMethod'u nasıl kullanabileceğinizi ele alalım.

Invoke-RestMethod, HTTP isteklerinin gönderilmesindeki sıkıntının çoğunu ortadan kaldırır. Bir HTTP isteğinde Yetkilendirme başlığı sağlamanız gerekse de bu örnekte "başlıklara" herhangi bir referans görmezsiniz. Bunun gibi kavramların soyutlanması Invoke-RestMethod cmdlet'inde yaygındır.

Temel Kimlik Doğrulamayla Kullanıcı Adı ve Parola Kullanma

REST uç noktasında kimlik doğrulamanın en basit yolu kullanıcı adı ve parola kullanmaktır. Bu kullanıcı adını ve parolayı yakalamak için kullanıcı adını ve parolayı içeren uç noktaya bir PSCredential nesnesi iletmeniz gerekir.

Öncelikle kullanıcı adını ve şifreyi içeren PSCredential nesnesini oluşturun.

# This will prompt for credentials and store them in a PSCredential object.
$Cred = Get-Credential

Bir değişkende depolanan bir PSCredential nesnesine sahip olduğunuzda, gerekli URI'yi komuta iletin ancak bu sefer Authentication ve Credential parametresini ekleyin.

Kimlik Doğrulama parametresinin ayarlanması, Basic kelimesini ve ardından base64 ile kodlanmış kullanıcı adı:şifre kelimesini içeren bir yetkilendirme HTTP başlığı gönderir. Yetkilendirme: Temel ZGVtbzpwQDU1dzByZA== gibi bir dize.

Kimlik Bilgisi parametresi, daha önce oluşturduğunuz PSCredential'ı kabul eder.

Aşağıdaki örnek ve bu eğitimdeki çok daha fazlası, bir karma tablosunda parametreleri tanımlamanıza ve ardından komuta aktarmanıza olanak tanıyan PowerShell sıçraması adı verilen bir kavramı kullanır. PowerShell Splatting: Nedir ve nasıl çalışır? başlıklı ATA yayınından sıçrama hakkında daha fazla bilgi edinin.

# Send a GET request including Basic authentication.
$Params = @{
	Uri = "https://jsonplaceholder.typicode.com/posts"
	Authentication = "Basic"
	Credential = $Cred
}

Invoke-RestMethod @Params

Kimlik Bilgisi veya Kimlik Doğrulama parametre seçeneğini https:// ile başlamayan bir Uri ile kullanırsanız, Invoke -RestMethod güvenlik nedeniyle bir hata döndürecektir. Bu varsayılan davranışı geçersiz kılmak için, risk size ait olmak üzere AllowUnencryptedAuthentication parametresini kullanın.

Taşıyıcı Kimlik Doğrulaması ile API/OAuth Jetonu Kullanma

Temel kullanıcı adı ve şifre kimlik doğrulaması tamamdır, ancak mükemmel değildir. Kimlik bilgileri basitçe base64 (şifrelenmemiş) olarak kodlanır ve bu da güvenlik sorunlarına yol açar. Bu sorunu çözmek için API'ler genellikle bir belirteç kimlik doğrulama sistemi veya Taşıyıcı/OAuth kimlik doğrulaması uygular.

OAuth belirteciyle bir REST API'sinde kimlik doğrulaması yapmak için:

1. API'nizden OAuth jetonunu alın. Bu tokenın nasıl elde edileceği API sağlayıcınıza bağlı olacaktır.

2. Ardından, aşağıda gösterildiği gibi ConvertTo-SecureString cmdlet'ini kullanarak belirteç dizinizi güvenli bir dizeye dönüştürün. Invoke-RestMethod, belirtecin güvenli bir dize olmasını gerektirir.

$Token = "123h1v23yt2egv1e1e1b2ei1ube2iu12be" | ConvertTo-SecureString -AsPlainText -Force

3. Son olarak Uri'yi, Kimlik Doğrulama türünü ve Token'ı tanımlayın ve Invoke-RestMethod cmdlet'ine iletin. Invoke-RestMethod daha sonra sağlanan URI'yi çağıracak ve belirteci Yetkilendirme HTTP başlığına ekleyecektir.

Kimlik Doğrulama parametre bağımsız değişkeni OAuth, Taşıyıcı'nın takma adıdır. Bu parametre değerlerinin her ikisini de birbirinin yerine kullanabilirsiniz.

# Send a GET request including bearer authentication.
 $Params = @{
     Uri = "https://jsonplaceholder.typicode.com/posts"
     Authentication = "Bearer"
     Token = $Token
 }
 Invoke-RestMethod @Params

Sorgu Parametrelerini Kullanarak Veri Alma

Tipik olarak, bir REST API'sine GET isteği göndermek, bir uç noktaya basit, genel bir istek göndermekten daha kapsamlıdır. Bunun yerine, API'den tam olarak neye ihtiyacınız olduğunu belirtmek için parametreleri iletmeniz gerekir; HTTP sorgu parametrelerini iletmeniz gerekir.

Invoke-RestMethod ile sorgu parametrelerini göndermek için iki seçeneğiniz vardır. Aşağıda gösterildiği gibi, userId 1 ve id 8'i geçen URI'ye doğrudan parametreleri ekleyebilirsiniz. .

https://jsonplaceholder.typicode.com/posts?userId=1&id=8

Veya Body parametresini hash tablosu olarak kullanarak HTTP gövdesindeki parametreleri tanımlayabilirsiniz. Body parametresini kullanarak parametrelerin bir uç noktaya nasıl aktarılacağını ele alalım.

Sorgu parametresi anahtar/değer çiftlerini içeren bir karma tablosunu aşağıdaki gibi oluşturun.

$Body = @{
    userId = 1
    id = 8
}

Son olarak, aşağıda gösterildiği gibi Body parametresine $Body değişkenini sağlayın.

GET değerini kullanarak Method parametresini belirtebilir veya Method parametresini veya Invoke-RestMethod varsayılan değere ayarlamak için.

$Params = @{
	Method = "Get"
	Uri = "https://jsonplaceholder.typicode.com/posts"
	Body = $Body
}

Invoke-RestMethod @Params

Artık uç noktanın yalnızca aradığınız gönderi öğesini döndürdüğünü aşağıda görebilirsiniz.

POST HTTP Yöntemiyle Verileri bir API'ye Gönderme

Önceki örneklerde, bir REST API'sinden veri sorguluyor veya HTTP GET isteklerini kullanıyordunuz. Geri gönderdiği verileri okudunuz, ancak birçok REST API'sinde okumak hikayenin yalnızca yarısıdır. Hizmetle etkileşimde bulunabilmeniz için REST API'lerin tam CRUD modelini desteklemesi gerekir.

API sağlayan bir hizmette değişiklik yapmanız gerektiğinde GET HTTP isteğini kullanmazsınız; POST gibi "yazılabilir" bir istek kullanacaksınız.

PUT veya PATCH gibi herhangi bir "yazılabilir" HTTP yöntemini kullanırken genellikle isteklerle birlikte bir HTTP gövdesi iletmeniz de gerekecektir.

JSON Verilerini POST İsteğinde Gönderme

Önceki REST API uç noktasını kullanarak, şimdi yalnızca okumak yerine yeni bir gönderi öğesi oluşturalım.

1. Öncelikle, gönderi API uç noktasının tüm özelliklerini içeren bir hash tablosu oluşturun. Aşağıda, eğitimin özel uç noktasının, title, body ve userId ile yeni bir gönderi öğesi oluşturmanıza olanak tanıdığını göreceksiniz.

$Body = @{
     title = "foo"
     body = "bar"
     userId = 1
 }

2. Daha sonra, $Body değişkeninde temsil edilen karma tablosunu, onu yeni bir $JsonBody değişkeninde saklayan bir JSON dizesine dönüştürün.

REST uç noktaları PowerShell karma tablosunun ne olduğunu bilmez ve nesneyi REST API'nin anlayacağı bir dile dönüştürmeniz gerekir. Önce karma tablo oluşturmak isteğe bağlıdır. İsterseniz doğrudan JSON'u yazıp bu adımı atlayabilirsiniz.

$JsonBody = $Body | ConvertTo-Json

3. Son olarak gerekli parametreleri oluşturun ve Invoke-RestMethod'u çalıştırın. Aşağıda, artık Method parametresini Post değeriyle kullanmanız gerektiğine dikkat edin. Method parametresini kullanmadan, Invoke-RestMethod varsayılan olarak bir GET isteği gönderir.

Ayrıca birçok REST API, Body'in depolandığı HTTP İçerik Türü başlığını belirten ContentType'ı belirtmenizi gerektirir. Bu örnekte application/ kullanmanız gerekir. json.

# The ContentType will automatically be set to application/x-www-form-urlencoded for
# all POST requests, unless specified otherwise.
 $Params = @{
     Method = "Post"
     Uri = "https://jsonplaceholder.typicode.com/posts"
     Body = $JsonBody
     ContentType = "application/json"
 }
 Invoke-RestMethod @Params

API'nin bu yeni gönderi için bir id ile birlikte bir gönderi öğesi döndürdüğüne aşağıda dikkat edin.

Form Verilerini `Invoke-RestMethod` ile Gönderme

Bazı REST API uç noktaları, verileri multipart/form-data HTTP içerik türü aracılığıyla göndermenizi gerektirebilir. Invoke-RestMethod ile farklı bir içerik türü göndermek JSON'u kullanmaktan biraz daha kolaydır. PowerShell 6.1.0'dan itibaren artık Form parametresini kullanabilirsiniz.

Form parametresi, .NET System.Net.Http.MultipartFormDataContent kullanmaya gerek kalmadan bir isteğe multipart/form-data nesneleri eklemek için kullanışlı bir yol sağlar sınıfını doğrudan kullanın.

Form verilerini Invoke-RestMethod ile göndermek için öncelikle daha önce olduğu gibi her öğeyle bir karma tablosu oluşturun.

$Form = @{
    title = "foo"
    body = "bar"
    userId = 1
}

Form parametresinin kullanıldığına dikkat edin; Body parametresini kullanmanıza gerek yoktur. Ayrıca, ContentType ve Form parametresini birlikte belirtmeye çalışırsanız Invoke-RestMethod, ContentType'ı yok sayacaktır. parametre.

Son olarak, hash tablosunu aşağıda gösterildiği gibi Form parametresine aktarmanız yeterlidir.

$Params = @{
	Method = "Post"
	Uri = "https://jsonplaceholder.typicode.com/posts"
	Form = $Form
}

Invoke-RestMethod @Params

İlişki Bağlantılarını Takip Etme

API'ler tek seferde çok büyük veri kümelerini döndürmek yerine genellikle "sayfalarca" veri döndürür. Örneğin GitHub Issues API, varsayılan olarak sayfa başına 30 sayı döndürür. Bazı API'ler, ilişki bağlantıları olarak bilinen veri kümesinde gezinmeye yardımcı olmak için sonraki (veya önceki, son vb.) veri sayfasına (yanıt) bağlantılar içerir.

Bir API'nin döndürdüğü ilişki bağlantılarını bulmak için HTTP yanıt başlıklarını incelemeniz gerekir. Bunu yapmanın kolay bir yolu ResponseHeadersVariable parametresini kullanmaktır. Bu parametre otomatik olarak bir değişken oluşturur ve başlıkları bir hash tablosunda saklar.

Örnek olarak PowerShell GitHub deposunun sorunlarını kullanalım.

1. PowerShell GitHub deposunun sorun uç noktasına aşağıda gösterildiği gibi bir GET isteği yapın. Bir değişken oluşturmak için ResponseHeadersVariable'ı kullandığınızdan emin olun. Aşağıdaki örnekte $Headers değişkeni kullanılmaktadır.

# Issue GET request to GitHub issues API for the PowerShell project repo and store
# the response headers in a variable ($Headers).
 Invoke-RestMethod -Uri "https://api.github.com/repos/powershell/powershell/issues" -ResponseHeadersVariable "Headers"
# Print the $Headers variable to the console.
 $Headers

Aşağıda $Headers değişkeninin içindeki karma tablosunun Bağlantılar adında bir anahtara sahip olduğuna dikkat edin. Bu anahtar, veri kümesinin yalnızca bu tek yanıttan daha büyük olduğunu gösteren yanıta ilişkin ilişki bağlantılarını içerir.

2. Daha sonra FollowRelLink parametresini kullanarak ilişki bağlantılarını izleyin. Bu parametre, ilişki bağlantılarının her birini otomatik olarak okur ve her biri için bir GET isteği gönderir.

Aşağıdaki kod pasajı, üçe kadar her ilişki bağlantısını takip ediyor. Bu örnekte, Invoke-RestMethod cmdlet'i, 90'a ulaştığında (istek başına 30 öğe) sorunları sorgulamayı durduracaktır.

$Params = @{
   Uri = "https://api.github.com/repos/powershell/powershell/issues"
     FollowRelLink = $true
     MaximumFollowRelLink = 3
 }
 Invoke-RestMethod @Params

FollowRelLink parametresi kullanıldığında, Invoke-RestMethod bir dizi nesne döndürür (Object[]). Dizideki her öğe, başka bir nesne dizisi olabilecek ilişki bağlantılarından birinden gelen yanıtı içerir!

3. Önceki örneği yeniden çalıştırın ancak bu sefer ilk sorgudan döndürülen sonuçları kontrol edin. Yalnızca 3 sayısını göreceksiniz, bu da üç "sayfa" anlamına gelir. Ancak öğelerin ilk sayfasında ($Results[0]) 30 öğe bulunduğunu göreceksiniz.

$Params = @{
   Uri = "https://api.github.com/repos/powershell/powershell/issues"
     FollowRelLink = $true
     MaximumFollowRelLink = 3
 }
 # Store the three pages of results in the $Results variable.
 $Results = Invoke-RestMethod @Params
 # Check that $Results contains three items (pages of issues from the GitHub issues API).
 $Results.Count
 # Check that the first item in the $Results array contains the first page of thirty issues.
 $Results[0].Count

4. Son olarak, foreach döngüsünü kullanarak $Results değişkenindeki her öğe üzerinde yineleme yapın. Aşağıda her sayfayı bir foreach döngüsüyle yinelemeniz gerekeceğini göreceksiniz. Daha sonra, her sayfa için, o sayfadaki iç içe döngü gerektiren tüm öğeleri yineleyin.

# This might be different depending on the data structure of the API you are using.
# 1) $Results.ForEach({}) - this loops through each page in the $Results array.
# 2) $_.ForEach({}) - this loops through each item in the current page.
# 3) $_ - this simply returns each item to the pipeline.
 $AllResults = @( $Results.ForEach({ $_.ForEach({ $_ }) }) )
# Check that the $AllResults variable contains all ninety items.
 $AllResults.Count

Oturum Bilgilerinin Korunması

API'lerle çalışırken, önceki isteklerle ilgili üstbilgiler, kimlik bilgileri, proxy ayrıntıları ve çerezler gibi bilgileri sonraki isteklerde yeniden kullanmak üzere depolamak genellikle yararlı olur. Bu bilgilerin tümü bir oturumda saklanır.

Invoke-RestMethod, SessionVariable parametresini kullanarak oturumu depolayıp ardından WebSession parametresini kullanarak bu oturuma başvuruda bulunarak oturumlardan yararlanabilir.

Göstermek için posts uç noktasını tekrar arayın ve bu sefer aşağıda gösterildiği gibi SessionVariable parametresini kullanın. Bu örnekte Invoke-RestMethod, MySession adında bir değişken oluşturacaktır.

Unutmayın, oturum nesnesi kalıcı bir bağlantı değildir. Oturum, istekle ilgili bilgileri içeren bir nesnedir.

# Invoke the request storing the session as MySession.
# The SessionVariable value shouldn't include a dollar sign ($).
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -SessionVariable "MySession"

# Print the session object to the console.
$MySession

Şimdi Invoke-RestMethod'u WebSession parametresiyle çağırarak oturum bilgilerini yeniden kullanın. Aşağıdaki örnekte görebileceğiniz gibi, önceki tüm oturum değerleri yeni istekte $MySession değişkeni aracılığıyla iletilir.

# Invoke the request using the session information stored in the $MySession variable.
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -WebSession $MySession

Oturum Değerlerini Geçersiz Kılma

Bir oturum istekle ilgili çeşitli bilgiler içerir. Oturumu yeniden kullanmak ancak bir değeri değiştirmek istiyorsanız bunu geçersiz kılabilirsiniz.

Belki daha önce oluşturulan oturumu yeniden kullanmak, ancak şimdi bir kullanıcı adı ve parolayla kimlik doğrulaması yapmak isteyebilirsiniz. Önce önceki durumun nasıl göründüğüne bakalım.

Aşağıda $MySession nesnesinin Credentials özelliği için herhangi bir değer içermediğine dikkat edin. Ancak Credential parametresini kullanarak Invoke-RestMethod'u tekrar çağırdıktan sonra, REST uç noktası oturumda olmasa bile kimlik bilgisini alır.

# Print the $MySession variable to the console to demonstrate that the Credentials
# property is empty.
$MySession

# Override the session value by specifying the Credential parameter.
# In this example you will be prompted for the username and password.
$Params = @{
	Uri = "https://jsonplaceholder.typicode.com/posts"
	WebSession = $MySession
	Credential = (Get-Credential)
}

Invoke-RestMethod @Params

Kayıtlı oturumdaki özelliğin adı Kimlik Bilgileri'dir, ancak parametre adı Kimlik Bilgileri'dir. Adlar her zaman eşleşmeyecektir.

Yanıt Gövdesini Dosyaya Kaydetme

Bazen bir isteğin yanıtını bir dosyaya kaydetmek gerekebilir. Bunu yapmak için OutFile parametresini kullanın.

Eğitimin test uç noktasını sorgulamak için Invoke-RestMethod'u tekrar çalıştırın ancak bu sefer OutFile parametresini kullanın ve bir dosya yolu sağlayın.

Aşağıda Invoke-RestMethod'un uç noktayı sorguladığını, yanıtı JSON biçiminde döndürdüğünü ve ardından ham JSON'u .\my-posts.json dosyasına kaydettiğini göreceksiniz. .

Yanıtı konsola döndürmek ve yanıtı içeren bir dosyayı bir kerede kaydetmek için PassThru parametresini de kullanabilirsiniz.

# Save post items to my-posts.json in the current directory.
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -OutFile "my-posts.json"

# Print the contents of the JSON file to the console.
# ".\" in this command refers to the current working directory in your terminal session.
Get-Content -Path ".\my-posts.json"

Yanıtı bir dosyaya JSON olarak kaydettikten sonra, onu istediğiniz gibi bilgi için ayrıştırabilirsiniz. Aşağıda belirli bir kimliğe sahip bir gönderi bulmanın iyi bir örneğini bulacaksınız.

# Save the response to "my-posts.json" and also in the $Posts variable using PassThru.
$Posts = Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -OutFile "my-posts.json" -PassThru

# Filter posts with 1 as the userId into a new variable ($User1Posts).
$User1Posts = $Posts.Where({$_.userId -eq 1})

# Import all posts from the "my-posts.json" file and store them in the $AllUserPosts variable.
$AllUserPosts = Get-Content -Path ".\my-posts.json" | ConvertFrom-Json

# Print the count of both variables to the console to demonstrate that they are different.
$User1Posts.Count
$AllUserPosts.Count

SSL ve Sertifikalarla Çalışmak

Bu eğitim boyunca yalnızca HTTP ile çalıştınız. HTTPS ve SSL henüz devreye girmedi. Ancak bu, Invoke-RestMethod'un SSL ile çalışmayacağı anlamına gelmez. Aslında ihtiyacınız olan hemen hemen her şeyi yönetebilir.

Sertifika Doğrulamasını Atlama

Varsayılan olarak Invoke-RestMethod, süresinin dolmadığından, iptal edilmediğinden veya güven zincirinin sağlam olduğundan emin olmak için herhangi bir SSL sitesinin sertifikasını doğrular. Bu davranış, açık bırakmanız gereken bir güvenlik özelliği olsa da, test sırasında olduğu gibi bazı zamanlar bu özelliği devre dışı bırakmanız gerekebilir.

Sertifika doğrulamasını atlamak için SkipCertificateCheck parametresini kullanın. Bu parametre, Invoke-RestMethod'un genellikle çalıştırdığı tüm sertifika doğrulamasını kaldırır.

Bir İstek için İstemci Sertifikası Belirtme

Belirli bir istek için istemci sertifikası belirtmeniz gerekiyorsa Invoke-RestMethod'un Certificate parametresini kullanın. Bu parametre, değeri olarak bir X509Certificate nesnesini alır; bu nesneyi, Get-PfxCertificate komutunu veya Get-ChildItem komutunu kullanarak < içinden alabilirsiniz.Sertifika: PSDrive.

Örneğin, aşağıdaki komut, JSONPlaceholder API'lerinin posts uç noktasına istekte bulunmak için Cert: sürücüsündeki bir sertifikayı kullanır.

# Change location into your personal certificate store.
Set-Location "Cert:\CurrentUser\My\"

# Store the certificate with the thumbprint DDE2EC6DBFF56EE9C375A6073C97188ABAA4F5E4 in a variable ($Cert).
$Cert = Get-ChildItem | Where-Object {$_.Thumbprint -eq "DDE2EC6DBFF56EE9C375A6073C97188ABAA4F5E4"}

# Invoke the command using the client certificate.
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -Certificate $Cert

SSL/TLS Protokollerini Kısıtlama

Varsayılan olarak sisteminiz tarafından desteklenen tüm SSL/TLS protokollerine izin verilir. Ancak bir isteği belirli bir protokol sürümüyle sınırlamanız gerekiyorsa SslProtocol parametresini kullanın.

SslProtocol'ü kullanarak, v1, 1.1, 1.2 ve 1.3'ten TLS sürümüne sahip bir URI'yi dizi olarak özel olarak çağırabilirsiniz.

# Restrict the request to only allow SSL/TLS 1.2 and 1.3 protocol versions.
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -SslProtocol @("Tls12", "Tls13")

Windows dışındaki platformlarda seçenek olarak Tls veya Tls12 bulunmayabilir. Tls13 desteği tüm işletim sistemlerinde mevcut değildir ve işletim sistemi bazında doğrulanması gerekecektir. Tls13 yalnızca PowerShell 7.1+ sürümlerinde mevcuttur.

Diğer İlginç Özellikler

Bu öğreticiyi tamamlamak için bazı yararlı parametrelerle bitirelim, ancak mutlaka bir talimat bölümüne ihtiyacımız yok.

Proxy Sunucu Kullanma

Kurumsal ortamlar genellikle internet erişimini yönetmek için proxy sunucuları kullanır. Invoke-RestMethod'u isteğini bir proxy aracılığıyla proxy yapmaya zorlamak için Proxy parametresini kullanın.

Proxy'de kimlik doğrulaması yapmanız gerekiyorsa, ProxyCredential parametresine bir PSCredential nesnesi sağlayın veya şu anda günlüğe kaydedilenleri kullanmak için ProxyUseDefaultCredentials anahtar parametresini kullanın. -kullanıcının kimlik bilgilerinde.

# Invoke request using proxy server <http://10.0.10.1:8080> and the current user's credentials.
Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -Proxy "http://10.0.10.1:8080" -ProxyUseDefaultCredentials

Kontrolleri ve Doğrulamayı Atlama

Bu parametrelerin kullanılması sizi potansiyel güvenlik risklerine maruz bırakabilir. Uyarıldınız!

Invoke-RestMethod cmdlet'inin altında gerçekleştirilen birçok farklı kontrol vardır. Herhangi bir nedenle bu kontrolleri devre dışı bırakmak isterseniz birkaç parametreyle bunu yapabilirsiniz.

SkipHeaderValidation - ContentType, Headers ve UserAgent parametrelerine aktarılan değerler için doğrulamayı devre dışı bırakın.
SkipHttpErrorCheck - Tüm hatalar yok sayılacaktır. İşlem devam etmeden önce hata işlem hattına yazılacaktır.
StatusCodeVariable - SkipHttpErrorCheck'i kullanırken, başarı veya başarısızlık mesajlarını tanımlamak için HTTP yanıt durum kodunu kontrol etmeniz gerekebilir. StatusCodeVariable parametresi bu amaçla durum kodu tamsayı değerini bir değişkene atayacaktır.

Keep Alive'ı devre dışı bırakma

TCP Keep Alive, uzak bir sunucuyla (sunucu destekliyorsa) kalıcı bir bağlantı oluşturmanıza olanak tanıyan kullanışlı, ağ düzeyinde bir özelliktir. Varsayılan olarak Invoke-RestMethod Keep Alive'ı kullanmaz.

Uzak sunucunun CPU ve bellek kullanımını azaltabilecek Keep Alive'ı kullanmak istiyorsanız DisableKeepAlive parametresini $false olarak ayarlayın.

Invoke-RestMethod -Uri "https://jsonplaceholder.typicode.com/posts" -DisableKeepAlive $false

Kodlama Türünü Değiştirme

Invoke-RestMethod uzak uç noktaya bir istek gönderdiğinde, isteği bir aktarım kodlama başlığı kullanarak kodlar. Varsayılan olarak, Invoke-RestMethod ve sunucu bu kodlama yöntemini anlaşır, ancak bir kodlama türünü TransferEncoding parametresiyle açıkça tanımlayabilirsiniz.

Kodlama türünü değiştirmek isterseniz şunları kullanabilirsiniz:

Parçalanmış
Kompres
Söndür
GZip
Kimlik

Çözüm

Bu eğitimde, Invoke-RestMethod'un REST API'leriyle etkileşimi standart web istekleriyle olduğundan çok daha kolay hale getirdiğini öğrendiniz. Kimlik doğrulama, bir isteğin gövdesinde veri gönderme, oturum durumunu sürdürme, dosyaları indirme ve çok daha fazlasına ilişkin parametrelere baktınız.

Artık Invoke-RestMethod konusunda bilgi sahibi olduğunuza ve REST API'leriyle çalıştığınıza göre, bu kullanışlı cmdlet'i hangi REST API'sinde deneyeceksiniz?