Как использовать Invoke-RestMethod в PowerShell

Когда вам нужно взаимодействовать с REST API в PowerShell, вам потребуется использовать командлет Invoke RestMethod. Этот командлет позволяет отправлять HTTP(S) запросы к REST веб-сервису из командной строки или скрипта PowerShell.

REST API могут быть использованы для управления всеми видами сервисов или для извлечения данных из них. Но имейте в виду, что часто доступны модули PowerShell для популярных сервисов, таких как Azure, Graph, GitHub и т. д. Поэтому убедитесь, что вы проверили это, прежде чем начать!

В этой статье мы рассмотрим, как выполнять REST API вызовы из PowerShell с помощью команды Invoke-RestMethod.

Метод Invoke-Rest на PowerShell

Командлет PowerShell Invoke-RestMethod позволяет работать с REST API. Он поддерживает все необходимые HTTP-методы, такие как Get, Post, Put и т. д., а также аутентификацию. Преимуществом командлета является то, что он автоматически преобразует ответы в формате JSON или XML в объекты pscustomobjects в PowerShell.

Чтобы сделать REST API вызов, вам понадобится URI для отправки запроса, вероятно, метод аутентификации и, конечно, знать, какой метод использовать. По умолчанию cmdlet будет использовать метод GET, но другие часто используемые методы это:

• GET – Получает данные из определенной конечной точки.
• ПОСЛАТЬ – Отправляет данные на сервер для создания нового ресурса
• PUT – Обновляет существующий ресурс на сервере.
• PATCH – Похоже на PUT, но отправляет только измененные данные на сервер.
• УДАЛИТЬ – Удаляет ресурсы с сервера

Получение данных

Мы начнем с основ, извлекая данные из API. Чтобы извлечь данные, нам нужно знать, какой URI (конечная точка) использовать. Практически все API имеют документацию, где можно ознакомиться с различными URI, которые можно использовать.

Заметка

Для примеров ниже мы будем использовать этот бесплатный REST API https://restful-api.dev/. Этот API не требует никакой аутентификации и также позволяет выполнять PUT-запросы, что отлично подходит для обучения.

Чтобы получить все объекты из API, нам необходимо использовать командлет Invoke-RestMethod с URI, из которого мы хотим получить данные. Это открытый API, поэтому аутентификация не требуется.

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

API возвращает JSON, который автоматически преобразуется в объект PowerShell с помощью командлета Invoke-RestMethod. Но когда API возвращает несколько объектов, объекты получаются в виде массива.

Выбор конкретных объектов из REST API часто осуществляется либо с помощью запроса, либо с указанием идентификатора объекта. Например, для выбора Google Pixel 6 из объектов мы можем указать идентификатор 1:

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

И поскольку теперь возвращается только один объект, мы также можем напрямую использовать командлет select-object, чтобы вернуть только имя объекта:

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

Result
name
----
Google Pixel 6 Pro

Использование параметров запроса

Чтобы выбрать конкретные объекты из API, вам нужно использовать параметры запроса. Эти параметры могут быть частью URI в команде Invoke-RestMethod или мы можем использовать JSON-тело. Какие параметры вы можете использовать, действительно зависит от API.

Вам нужно обратиться к документации API, чтобы узнать, какие параметры запроса вы можете использовать. Например, конечная точка, которую мы используем в этом примере, принимает только идентификаторы в качестве параметра запроса:

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}

Чтобы привести ещё один пример, мы можем использовать API randomuser.me, который генерирует случайные данные пользователей. Этот API принимает несколько параметров, которые позволяют вам указать, какие данные пользователя вы хотите сгенерировать.

Итак, например, мы можем сгенерировать 5 пользователей, все из которых имеют мужской пол и голландское гражданство:

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

Используя тело JSON

Указание всех параметров в URI может сделать ваш код трудночитаемым. Поэтому, когда вам нужно указать несколько параметров, часто лучше использовать JSON-объект вместо этого.

Преимущество тела JSON заключается в том, что его легче читать, и это позволяет вам быстро добавлять или изменять параметры в запросе.

Чтобы сделать тот же запрос, что и в приведенном выше примере, мы можем создать тело для Invoke-RestMethod с помощью простого хэш-таблицы. Я также сохранил URI в переменной, чтобы сделать пример немного более читаемым:

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

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

Мы даже можем сохранить все параметры внутри хеш-таблицы, используя технику сплаттинга. В этом случае всегда полезно указывать метод запроса. Я включил тело запроса в хеш-таблицу, но вы также можете создать тело отдельно, если вам это удобнее.

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

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

Следуйте по ссылкам отношений

Некоторые REST API поддерживают использование ссылок на отношения. Ссылки на отношения обычно используются для постраничной навигации, поэтому вы можете запрашивать тысячи объектов за один вызов. Ссылки на отношения указаны в заголовке результата.

При использовании командлета Invoke RestMethod вы можете получить доступ к этим связующим ссылкам, используя параметр FollowRelLink. Параметр MaximumFollowRelLink позволяет вам определить, сколько страниц вы хотите запросить.

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

Отправка данных

Мы также можем использовать PowerShell Invoke-RestMethod для отправки данных на REST API. Для этого нам нужно создать JSON-объект с данными, которые мы хотим отправить. Также вам нужно знать URI конечной точки, и мы должны использовать правильный метод.

Если вы хотите создать новый объект/ресурс, вам нужно будет использовать метод POST. Для обновления существующего ресурса вам нужно будет использовать метод PUT или PATCH.

Первый шаг - создать тело с элементом, который вы хотите отправить на API. Пример REST API, который мы используем, также требует, чтобы атрибут данных был объектом JSON, но часто вы можете указать атрибуты напрямую без вложенной таблицы:

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

Прежде чем мы сможем отправить новый объект с помощью POST, нам нужно убедиться, что тело преобразовано в объект JSON. Мы можем сделать это с помощью команды ConvertTo-JSON. Нам также нужно указать ContentType, который мы отправляем, и, конечно, метод POST:

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

Invoke-RestMethod @parameters

Большинство API вернут объект после успешной отправки POST-запроса. Вы можете либо сохранить результаты в переменной, либо перенаправить их в null, если не хотите, чтобы они выводились в консоль.

Invoke-RestMethod @parameters | Out-Null

Загрузка файлов и смешанного контента

Когда вам нужно загрузить файл или изображение в API с помощью PowerShell, вам часто нужно будет использовать multipart/formdata, чтобы отправить ваш объект. Для этого вам потребуется использовать как минимум PowerShell 6, так как это позволяет вам использовать параметр -Form.

Так же, как и при использовании параметра тела, нам необходимо создать хэш-таблицу для параметра формы:

$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

Обновление объекта

Обновление объекта осуществляется практически так же, как и его создание. Единственное отличие заключается в том, что вам нужно будет указать объект, который вы хотите обновить.

Существует два метода, которые вы можете использовать для обновления объекта: PUT и PATCH. Первый заменит все атрибуты объекта, в то время как последний заменяет только те атрибуты, которые вы отправляете.

$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'
}

Аутентификация

До сих пор в нашем примере мы использовали REST API, которые не требуют никакой аутентификации. Но большинство REST API требуют, чтобы вы аутентифицировались, прежде чем сможете с ними взаимодействовать. Три метода аутентификации обычно используются:

• Базовая – Простой вход с использованием имени пользователя и пароля
• Токен – требуется параметр токена
• API ключ – комбинация ключа доступа и секретного ключа

Данные аутентификации предоставляются в заголовке запроса. Вы можете сделать это с помощью команды Invoke-RestMethod, используя параметр -header.

Базовая аутентификация

Базовая аутентификация состоит из имени пользователя и пароля, которые кодируются с помощью base64. В наши дни это не самый безопасный вариант, поэтому вы не встретите их часто. Чтобы использовать базовую аутентификацию, вам сначала нужно создать объект учетных данных в PowerShell.

$cred = Get-Credential

Затем мы можем добавить объект учетных данных в заголовок запроса REST API. Если вы используете PowerShell 6 или выше, вы можете использовать параметры -authentication и -credential:

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

При использовании PowerShell 5 вы можете использовать только объект учетных данных, и вам нужно будет создать заголовок с помощью JSON-объекта:

$headers = @{
    Authorization = "Basic"
}

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

Держатель

Токен-носитель является более распространенным методом аутентификации. Он использует токен, который вы часто сначала должны запросить у REST API. Это зависит от API, как токен запрашивается и как долго токен действителен.

Чтобы использовать токен, мы можем либо использовать параметр -Token (в PowerShell 6 или выше), либо добавить токен в заголовок.

$token = 'token-from-api'

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

Или при использовании PowerShell 5.x:

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

Invoke-RestMethod -Uri $uri -Headers $header

API ключ – секрет

Последний метод аутентификации, который я хочу вам показать, это метод API Key/Secret. Многие API в наши дни позволяют вам создать уникальную комбинацию ключа и секрета, которую вы можете использовать для вашего приложения.

Чтобы использовать ключ и секрет для аутентификации, нам нужно будет использовать заголовок X-ApiKeys. Так же, как и с другим заголовком, вам нужно будет создать объект заголовка с правилом заголовка X-ApiKeys:

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

Invoke-RestMethod @parameters

Заключение

REST API - это отличный способ обмена информацией с другими системами. Имейте в виду, что для многих популярных сервисов доступны модули PowerShell. Поэтому убедитесь, что вы проверили это в первую очередь, прежде чем начинать.

Команда Invoke RestMethod в PowerShell проще в использовании в PowerShell 7.x, поэтому я действительно рекомендую использовать последнюю версию при работе с REST API.

Надеюсь, вы нашли эту статью полезной. Если у вас есть вопросы, просто оставьте комментарий ниже.