Поиск по сайту:

Изучение нового REST API с помощью PowerShell

Использование REST API для расширения ваших скриптов — полезная функция для реализации. Вы можете получить доступ к новым функциям, а возможности для создания новых более продвинутых сценариев расширяются.

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

  • Что такое REST API
  • Как читать наиболее распространенную форму документации
  • Как использовать REST API с PowerShell
  • Несколько советов и рекомендаций, как упростить и улучшить работу.

Что такое ОТДЫХ?

REST или RESTful API — это API, который использует HTTP-запросы для извлечения, добавления, удаления или управления данными в различных службах.

То, что мы хотим делать с данными, обычно определяется используемым методом HTTP. Вот краткий список HTTP-методов и того, для чего они используются в REST API:

  • ПОЛУЧИТЬ – прочитать
  • POST — Создать
  • ИСПРАВЛЕНИЕ – частичное обновление/изменение
  • PUT — обновить/заменить
  • УДАЛИТЬ — удалить

Данные, возвращаемые REST API, обычно возвращаются в формате JSON.

Теперь давайте начнем с нашего первого вызова API!

Чтение документов

Для их использования необходимо научиться читать и интерпретировать документацию по различным API REST. К счастью, если вы знаете, как читать один стиль документации, вы можете быстро научиться читать другие.

В этой статье мы используем petstore.swagger.io, так как он использует популярную среду Swagger, которая довольно часто встречается в реальном мире.

На предыдущем рисунке показана наиболее важная информация о конечных точках REST API:

  • Метод HTTP — GET/POST/DELETE и т. д.
  • Относительный URL конечной точки REST API (базовый URL обычно указан в верхней части страницы документации)
  • Краткое описание

Вникаем в детали

Первая страница документации великолепна, и вы обычно можете выполнять большинство вызовов, требующих метода HTTP GET, с этой информацией. Но такие методы, как POST и SET, обычно требуют, чтобы вы щелкнули и развернули строку, чтобы получить больше информации.

Если вы нажмете на одну из строк, вам будет представлена информация, которая выглядит следующим образом:

Здесь мы представили конечную точку REST, которая может создать новый объект питомца. Он указывает, как должен выглядеть JSON, который был предоставлен в теле POST, и какой тип контента он принимает. Другие конечные точки REST указывают, какие у них разные параметры, какой тип данных должен быть и т. д.

Это основы для чтения документации. Теперь это ясно, пора начать использовать REST API с PowerShell.

ПОЛУЧИТЕ ваши первые данные

Использование REST API с PowerShell обычно довольно простое, и вы используете встроенные командлеты, поэтому дополнительные модули не нужны. Вы собираетесь получать данные с помощью метода GET на конечной точке /pet/{petId}.

Если вы раскроете конечную точку /pet/{petId} в документации, вы увидите, что {petId} на самом деле является параметром, который принимает целое число.

Это делает URL-адрес для получения объекта питомца с идентификатором 1: https://petstore.swagger.io/v2/pet/1.

В документации SWAGGER REST API обычно указан базовый URL-адрес в верхней части страницы.

Теперь давайте начнем с PowerShell. Откройте окно терминала и введите:

PS51 > Invoke-RestMethod -Method GET -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"

id        : 1
category  : @{id=0; name=string}
name      : doggie
photoUrls : {string}
tags      : {@{id=0; name=string}}
status    : available

Invoke-RestMethod автоматически преобразует возвращенный JSON в объект, поскольку в ответе от сервера возвращается тип содержимого «application/json».

Ошибка 404 - Не найден обычно означает, что объект не может быть найден, а не опечатка в URL-адресе.

Вы успешно сделали свой первый вызов REST API. Но возможность получать только данные GET довольно ограничена, поэтому давайте создадим что-нибудь с помощью метода POST.

Создание объекта методом POST

Метод POST чаще всего используется для создания, например создания пользователей или записей и т. д. Запрос POST отправляет BODY, содержащий информацию, в конечную точку REST, обычно в формате JSON, но также может быть в виде URL-кодированной формы.

Вы узнаете, как создать объект JSON, который можно отправить в конечную точку /pet.

Вы можете увидеть, как должен выглядеть JSON, если развернете строку POST /pet в документации.

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

$Body = @{
    id = 19
    category = @{
        id = 45
        name = "Whatever"
    }
    name = "Dawg"
    photoUrls = @(
        "string"
    )
    tags = @(
        @{
            id = 0
            name = "string"
        }
    )
    status = "available"
}

Если вам сложно создать хеш-таблицу, которая преобразуется в нужный вам JSON, установите модуль PsdKit и используйте команду: $JsonString | Преобразовать в Psd

Теперь у вас есть хэш-таблица, которую вы можете преобразовать в строку JSON и отправить POST в конечную точку /pet:

$JsonBody = $Body | ConvertTo-Json
$Uri = "https://petstore.swagger.io/v2/pet"
Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method Post -Body $JsonBody

id        : 19
category  : @{id=45; name=Whatever}
name      : Dawg
photoUrls : {string}
tags      : {@{id=0; name=string}}
status    : available

Когда объект создан, вы обычно получаете объект, который был создан для подтверждения.

Использование УДАЛИТЬ

Метод DELETE удаляет данные, и способ его выполнения очень похож на метод GET, как показано здесь:

PS51 > Invoke-RestMethod -Method DELETE -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"

Просто будьте осторожны, чтобы не удалить ничего, что вам может понадобиться.

Использование PUT

Метод PUT обновляет уже существующие данные. Это делается аналогично методу POST, отправляя полный или частичный объект JSON:

PS51> $Body = [PSCustomObject]@{
    id = 19
    name = "Dawg with a new name"
}

PS51> $JsonBody = $Body | ConvertTo-Json
PS51> $Uri = "https://petstore.swagger.io/v2/pet"
PS51> Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method PUT -Body $JsonBody

id name                 photoUrls tags
-- ----                 --------- ----
19 Dawg with a new name {}        {}

Обычно REST API возвращает объект JSON с использованными и/или обновленными данными. Вы можете видеть, что объект был обновлен с помощью метода GET:

PS 51> Invoke-RestMethod -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/19"

id        : 19
category  : @{id=45; name=Whatever}
name      : Dawg with a new name
photoUrls : {string}
tags      : {@{id=0; name=string}}
status    : available

Создание функций

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

Function Get-PetstorePet {
    [cmdletbinding()]
    param(
        # Id of the pet
        [Parameter(Mandatory,ValueFromPipeline)]
        [int]$Id
    )
    Begin{}
    Process{
        $RestMethodParams = @{
            Uri = "https://petstore.swagger.io/v2/pet/$Id"
            ContentType = "application/json"
            Method = "GET"
        }
        Invoke-RestMethod @RestMethodParams
    }
    End{}
}

После создания функции вы можете вызвать ее в своем скрипте:

PS51> Get-PetstorePet -Id 1

id name    photoUrls             tags
-- ----    ---------             ----
 1 Doggie  {http://picture.url}  {}

Вы можете сделать это и для метода POST, и для создания нового питомца в зоомагазине:

Function Add-PetstorePet {
    [cmdletbinding()]
    param(
        # Id of the pet
        [Parameter(Mandatory,ValueFromPipelineByPropertyName)]
        [int]$Id,
        # Name of the pet
        [Parameter(Mandatory,ValueFromPipelineByPropertyName)]
        [string]$Name,        
        # Status of the pet (available, sold etc)
        [Parameter(Mandatory,ValueFromPipelineByPropertyName)]
        [string]$Status,        
        # Id of the pet category
        [Parameter(Mandatory,ValueFromPipelineByPropertyName)]
        [int]$CategoryId,        
        # Name of the pet category
        [Parameter(Mandatory,ValueFromPipelineByPropertyName)]
        [string]$CategoryName,        
        # URLs to photos of the pet
        [Parameter(Mandatory,ValueFromPipelineByPropertyName)]
        [string[]]$PhotoUrls,
        # Tags of the pets as hashtable array: @{Id=1;Name="Dog"}
        [Parameter(Mandatory,ValueFromPipelineByPropertyName)]
        [Hashtable[]]$Tags
    )
    Begin{}
    Process{
        $Body = @{
            id = $Id
            category = @{
                id = $CategoryId
                name = $CategoryName
            }
            name = $Name
            photoUrls = $PhotoUrls
            tags = $Tags
            status = $Status
        }
        $BodyJson = $Body | ConvertTo-Json
        $RestMethodParams = @{
            Uri = "https://petstore.swagger.io/v2/pet/"
            ContentType = "application/json"
            Method = "Post"
            Body = $BodyJson
        }
        Invoke-RestMethod @RestMethodParams
    }
    End{}
}

А последующий вызов этой функции PowerShell значительно упрощает эту довольно длинную задачу:

PS51> $AddPetStorePetsParams = @{
    Id = 44
    Name = "Birdie"
    Status = "available"
    CategoryId = 50
    CategoryName = "Hawks"
    PhotoUrls = "https://images.contoso.com/hawk.jpg"
    Tags = @(
        @{
            Id=10
            Name="Not eagles"
        }
    )
}
PS51> Add-PetStorePet @AddPetStorePetsParams

id        : 44
category  : @{id=50; name=Hawks}
name      : Birdie
photoUrls : {https://images.contoso.com/hawk.jpg}
tags      : {@{id=0}}
status    : available

Скорее всего, многие из модулей, которые вы используете ежедневно, состоят из функций, которые используют REST API только в фоновом режиме.

Краткое содержание

Изучение того, как использовать REST API, в основном связано с чтением документации. В этом посте мы использовали документацию на основе SWAGGER, поскольку она представляет, как могут выглядеть другие стили документации.

Кроме того, преобразование вызовов API в функцию может сэкономить вам много времени, упростить вашу работу и сделать ваши скрипты чище.