PowerShell'de Invoke RestMethod nasıl kullanılır?

PowerShell'de bir REST API ile etkileşim kurmanız gerektiğinde Invoke RestMethod cmdlet'ini kullanmanız gerekecektir. Bu cmdlet, komut satırınızdan veya PowerShell betiğinizden bir REST web hizmetine HTTP(S) istekleri göndermenizi sağlar.

REST API'ler her türlü hizmeti yönetmek veya bunlardan veri çekmek için kullanılabilir. Ancak Azure, Graph, GitHub vb. gibi popüler hizmetler için genellikle PowerShell Modüllerinin bulunduğunu unutmayın. Bu nedenle, başlamadan önce bunu kontrol ettiğinizden emin olun!

Bu yazımızda Invoke-RestMethod cmdlet'i ile PowerShell'den REST API çağrılarının nasıl yapılacağına bakacağız.

PowerShell Invoke-RestMethod

PowerShell Invoke-RestMethod cmdlet'i REST API'leriyle çalışmanıza olanak tanır. Get, Post, Put vb. gibi gerekli tüm HTTP yöntemlerini ve kimlik doğrulamayı destekler. Cmdlet'in bir avantajı, JSON veya XML yanıtlarını PowerShell'deki pscustomobjects nesnelerine otomatik olarak dönüştürmesidir.

Bir REST API çağrısı yapmak için isteği göndereceğiniz URI'ye, muhtemelen kimlik doğrulama yöntemine ve elbette hangi yöntemi kullanacağınızı bilmeniz gerekir. Varsayılan olarak cmdlet GET yöntemini kullanır ancak yaygın olarak kullanılan diğer yöntemler şunlardır:

• GET - Belirli bir uç noktadan veri alır.
• POST - Yeni bir kaynak oluşturmak için verileri sunucuya gönderir
• PUT - Sunucudaki mevcut bir kaynağı günceller.
• PATCH - PUT'a benzer, ancak yalnızca sunucuya değiştirilen verileri gönderir
• DELETE - Kaynakları sunucudan kaldırır

Veri Alma

Bir API'den veri alarak temel bilgilerle başlayacağız. Verileri almak için hangi URI'yi (uç nokta) kullanacağımızı bilmemiz gerekecek. Hemen hemen tüm API'lerin, kullanabileceğiniz farklı URI'lere bakabileceğiniz belgeleri vardır.

Not

Aşağıdaki örnekler için bu ücretsiz REST API'sini https://restful-api.dev/ kullanacağız. Bu API herhangi bir kimlik doğrulama gerektirmez ve aynı zamanda öğrenme için harika olan koyma isteği yapmanıza da olanak tanır.

API'den tüm nesneleri almak için yalnızca verileri almak istediğimiz URI ile Invoke-RestMethod cmdlet'ini kullanmamız gerekir. Bu açık bir API olduğundan kimlik doğrulamaya gerek yoktur.

Invoke-RestMethod -Uri 'https://api.restful-api.dev/objects'

API, Invoke-RestMethod cmdlet'i tarafından otomatik olarak bir PowerShell nesnesine dönüştürülen JSON'u döndürür. Ancak API birden fazla nesne döndürdüğünde nesneler bir dizi olarak alınır.

REST API'sinden belirli nesnelerin seçilmesi genellikle bir sorgu kullanılarak veya nesne kimliği belirtilerek yapılır. Örneğin, nesnelerden Google Pixel 6'yı seçmek için 1 kimliğini belirtebiliriz:

https://api.restful-api.dev/objects/1

Artık yalnızca tek bir nesne döndürüldüğü için, yalnızca nesnenin adını döndürmek için select-object cmdlet'ini doğrudan kullanabiliriz:

https://api.restful-api.dev/objects/1 | Select name

# Result
name
----
Google Pixel 6 Pro

Sorgu Parametrelerini Kullanma

Bir API'den belirli nesneleri seçmek için sorgu parametrelerini kullanmanız gerekir. Bu parametreler Invoke-RestMethod cmdlet'indeki URI'nin parçası olabilir veya bir JSON gövdesi kullanabiliriz. Hangi parametreleri kullanabileceğiniz gerçekten API'ye bağlıdır.

Hangi sorgu parametrelerini kullandığınızı görmek için API belgelerine bakmanız gerekecektir. Örneğin, bu örnekte kullandığımız uç nokta yalnızca kimlikleri sorgu parametresi olarak kabul eder:

Invoke-RestMethod -uri 'https://api.restful-api.dev/objects?id=3&id=5'

# result
id name                    data
-- ----                    ----
3  Apple iPhone 12 Pro Max @{color=Cloudy White; capacity GB=512}
5  Samsung Galaxy Z Fold2  @{price=689,99; color=Brown}

Size başka bir örnek vermek gerekirse, rastgele kullanıcı verileri üreten randomuser.me API'sini kullanabiliriz. Bu API, ne tür kullanıcı verileri oluşturmak istediğinizi belirtmenize olanak tanıyan birden çok parametreyi kabul eder.

Örneğin, cinsiyeti erkek ve Hollanda vatandaşı olan 5 kullanıcı oluşturabiliriz:

Invoke-RestMethod -Uri 'https://randomuser.me/api/?gender=male&results=5&nat=nl' | select -ExpandProperty results | ft

JSON Gövdesi Kullanma

URI'de tüm parametrelerin belirtilmesi kodunuzun okunmasını zorlaştırabilir. Dolayısıyla birden fazla parametre belirtmeniz gerektiğinde bunun yerine JSON gövdesini kullanmak genellikle daha iyidir.

JSON gövdesinin avantajı, okunmasının daha kolay olması ve istekteki parametreleri hızlı bir şekilde eklemenize veya değiştirmenize izin vermesidir.

Yukarıdaki örnekte olduğu gibi aynı isteği yapmak için Invoke-RestMethod için basit bir hashtable ile bir gövde oluşturabiliriz. Örneği biraz daha okunabilir hale getirmek için URI'yi bir değişkende de sakladım:

$uri = 'https://randomuser.me/api/'
$body = @{
    gender = 'male'
    nat = 'nl'
    results = '5'
}

Invoke-RestMethod -Uri $uri -Body $body | select -ExpandProperty results | ft

Splatting tekniğini kullanarak tüm parametreleri bir hash tablosunda bile saklayabiliriz. Bu durumda istek yöntemini de belirtmek her zaman iyi bir fikirdir. Ben gövdeyi hashtable'ın içine dahil ettim ama isterseniz gövdeyi ayrı olarak da oluşturabilirsiniz.

$parameters = @{
    Method = 'GET'
    Uri = 'https://randomuser.me/api/'
    Body =  @{
            gender = 'male'
            nat = 'nl'
            results = '5'
        }
    }

Invoke-RestMethod @parameters | select -ExpandProperty results | ft

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

Bazı REST API'leri ilişki bağlantılarının kullanımını destekler. İlişki bağlantıları genellikle sayfalandırma için kullanılır, bu nedenle tek çağrıda 1000'lerce nesne talep edersiniz. İlişki bağlantıları sonucun başlığında belirtilmiştir.

Invoke RestMethod cmdlet'ini kullanırken FollowRelLink parametresini kullanarak bu ilişki bağlantılarına erişebilirsiniz. MaximumFollowRelLink parametresi, kaç sayfa istemek istediğinizi de belirlemenize olanak tanır.

$url = 'https://api.github.com/repos/ruudmens/lazyadmin/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

Veri Gönderme

Verileri bir REST API'ye göndermek için PowerShell Invoke-RestMethod'u da kullanabiliriz. Bunu yapmak için göndermek istediğimiz verilerle bir JSON gövdesi oluşturmamız gerekecek. Ayrıca uç nokta URI'sini bilmeniz ve doğru yöntemi kullanmamız gerekecek.

Yeni bir nesne/kaynak oluşturmak istiyorsanız POST yöntemini kullanmanız gerekecektir. Mevcut bir kaynağı güncellemek için PUT veya PATH yöntemini kullanmanız gerekecektir.

İlk adım, API'ye POST yapmak istediğiniz öğenin gövdesini oluşturmaktır. Kullandığımız örnek REST API, veri özelliğinin de bir JSON nesnesi olmasını gerektirir, ancak çoğu zaman nitelikleri iç içe hash tablosu olmadan doğrudan belirtebilirsiniz:

$body = @{
    name = 'LazyPhone'
    data = @{
       year = 2024
       price = 399.99
       'Screen size' = 6.2
    }
}

Yeni nesneyi POST yapmadan önce gövdenin bir JSON nesnesine dönüştürüldüğünden emin olmamız gerekecek. Bunu ConvertTo-JSON cmdlet'iyle yapabiliriz. Ayrıca gönderdiğimiz ContentType'ı ve elbette POST yöntemini de belirtmemiz gerekiyor:

$parameters = @{
    Method = 'POST'
    Uri = 'https://api.restful-api.dev/objects'
    Body =  ConvertTo-JSON($body)
    ContentType = 'application/json'
}

Invoke-RestMethod @parameters

Çoğu API, başarıyla POST yaptıktan sonra nesneyi döndürür. Sonuçları bir değişkende saklayabilir veya konsola çıkmasını istemiyorsanız null değerine yönlendirebilirsiniz.

Invoke-RestMethod @parameters | Out-Null

Dosyaları ve Karma İçeriği Yükleme

PowerShell ile bir API'ye bir dosya veya resim yüklemeniz gerektiğinde, nesnenizi göndermek için genellikle multipart/formdata kullanmanız gerekecektir. Bunun için en az PowerShell 6 kullanmanız gerekecek çünkü bu -Form parametresini kullanmanıza olanak sağlıyor.

Tıpkı body parametresini kullanırken olduğu gibi form parametresi için de bir karma tablosu oluşturmamız gerekir:

$form = @{
    brand = 'LazyPhone'
    model = 'Snap 2'
    released = '2024-01-22'
    image = Get-Item -Path "c:\marketing\LazyPhone\"
}

$parameters = @{
    Method = 'POST'
    Uri = 'https://api.example.dev/phones'
    Form = ConvertTo-JSON($form)
    ContentType = 'application/json'
}

Invoke-RestMethod @parameters

Bir Nesneyi Güncelleme

Bir nesnenin güncellenmesi, hemen hemen bir nesnenin oluşturulmasıyla aynı şekilde yapılır. Buradaki tek fark, güncellemek istediğiniz nesneyi belirtmenizin gerekmesidir.

Bir nesneyi güncellemek için kullanabileceğiniz iki yöntem vardır: PUT ve PATCH. Birincisi nesnenin tüm niteliklerini değiştirirken ikincisi yalnızca gönderdiğiniz niteliklerin yerini alır.

$body = @{
    name = 'LazyPhone'
    data = @{
        color = 'Cloudy White'
        'capacity GB' = 512
    }
}

$parameters = @{
    Method = 'POST'
    Uri = 'https://api.restful-api.dev/objects/3'
    Body =  ConvertTo-JSON($body)
    ContentType = 'application/json'
}

Kimlik doğrulama

Şu ana kadar örneğimizde herhangi bir kimlik doğrulama gerektirmeyen REST API'leri kullandık. Ancak çoğu REST API'si, onunla etkileşim kurabilmeniz için önce kimlik doğrulamanızı gerektirir. Yaygın olarak üç kimlik doğrulama yöntemi kullanılır:

• Temel - Basit kullanıcı adı/şifre tabanlı kimlik doğrulama
• Taşıyıcı - Jeton parametresi gerektirir
• API Anahtarı - Erişim anahtarı ve gizli anahtarın birleşimi

Kimlik doğrulama ayrıntıları aramanın başlığında sağlanır. Bunu Invoke-RestMethod cmdlet'iyle -headers parametresini kullanarak yaparsınız.

Temel Kimlik Doğrulama

Temel kimlik doğrulama, base64 ile kodlanmış bir kullanıcı adı ve şifreden oluşur. Bu günlerde kullanmak için en güvenli seçenek değiller, bu yüzden onlarla pek karşılaşmayacaksınız. Temel kimlik doğrulamayı kullanmak için öncelikle PowerShell'de bir kimlik bilgisi nesnesi oluşturmanız gerekir.

$cred = Get-Credential

Daha sonra kimlik bilgisi nesnesini REST API isteğinin başlığına ekleyebiliriz. PowerShell 6 veya üstünü kullanıyorsanız -authentication ve -credential parametresini kullanabilirsiniz:

Invoke-RestMethod -uri 'https://api.restful-api.dev/objects/' -Credential $cred -Authentication Basic

PowerShell 5'i kullanırken yalnızca kimlik bilgisi nesnesini kullanabilirsiniz ve başlığı bir JSON nesnesiyle oluşturmanız gerekir:

$headers = @{
    Authorization = "Basic"
}

Invoke-RestMethod -uri 'https://api.restful-api.dev/objects/' -Headers $header -Credential $cred

Taşıyıcı

Taşıyıcı belirteci daha yaygın olarak kullanılan bir kimlik doğrulama yöntemidir. Genellikle ilk önce REST API'sinden istemeniz gereken bir belirteci kullanır. Belirtecin nasıl talep edildiğine ve belirtecin ne kadar süreyle geçerli olduğuna ilişkin API'ye bağlıdır.

Belirteci kullanmak için -Token parametresini kullanabiliriz (PowerShell 6 veya üzeri sürümlerde) veya belirteci başlığa ekleyebiliriz.

$token = 'token-from-api'

Invoke-RestMethod -Uri $uri -Authentication Bearer -Token $token

Veya PowerShell 5.x kullanırken:

$headers = @{
    'Authorization' = "Bearer $Token"
}

Invoke-RestMethod -Uri $uri -Headers $header

API Anahtarı - Gizli

Size göstermek istediğim son kimlik doğrulama seçeneği API Anahtarı/Gizli yöntemidir. Günümüzde pek çok API, uygulamanız için kullanabileceğiniz benzersiz bir anahtar/gizli kombinasyonu oluşturmanıza olanak tanıyor.

Kimlik doğrulama amacıyla anahtarı ve sırrı kullanmak için X-ApiKeys başlığını kullanmamız gerekecek. Tıpkı diğer başlıkta olduğu gibi, X-ApiKeys başlık kuralıyla bir başlık nesnesi oluşturmanız gerekecektir:

$parameters = @{
    Method = 'PUT'
    Uri = 'https://api.restful-api.dev/objects/'
    Headers = @{
        "X-ApiKeys" = "accessKey=$($accessKey); secretKey=$($secretKey)"
    }
    ContentType = 'application/json'
}

Invoke-RestMethod @parameters

Kapanış

REST API'leri diğer sistemlerle bilgi alışverişinde bulunmanın harika bir yoludur. Birçok popüler hizmet için PowerShell Modüllerinin mevcut olduğunu unutmayın. Bu yüzden başlamadan önce bunu kontrol ettiğinizden emin olun.

PowerShell Invoke RestMethod cmdlet'inin PowerShell 7.x'te kullanımı daha kolaydır, bu nedenle bir REST API ile çalışırken gerçekten en son sürümü kullanmanızı öneririm.

Umarım bu makaleyi faydalı bulmuşsunuzdur. Herhangi bir sorunuz varsa aşağıya bir yorum bırakmanız yeterli.