ѕодпишитесь на наш Telegram-канал Ѕудьте в курсе последних новостей 👇 😉 ѕодписатьс€
ѕоддержим в трудное врем€ —пециальное предложение на техническую поддержку вашей »“ - инфраструктуры силами наших экспертов ѕодобрать тариф
ѕоставка оборудовани€ √аранти€ и помощь с настройкой. —кидка дл€ наших читателей по промокоду WIKIMERIONET  упить
»нтерфейс статистики Merion Mertics показывает ключевые диаграммы и графики по звонкам, а также историю звонков в формате, который легко поймет менеджер ѕопробовать бесплатно
¬недрение
офисной телефонии
Ўаг на пути к созданию доступных унифицированных коммуникаций в вашей компании ¬недрить
»нтеграци€ с CRM ѕомогаем навести пор€док с данными
и хранить их в единой экосистеме
ѕодключить
»“ Ѕезопастность ”мна€ информационна€ безопасность дл€ вашего бизнеса «аказать
ћерион Ќетворкс

10 минут чтени€

»спользование REST API €вл€етс€ полезной функцией дл€ реализации ваших сценариев. ¬ы можете получить доступ к новым функци€м, а также расширить возможности создани€ новых, более продвинутых сценариев.

ќпыт многих пользователей показывает, что, когда начинаешь использовать REST API в скриптах, то чувствуешь себ€ довольно неуклюже и непривычно. ¬ этой заметке мы обсудим:

  • „то такое REST API
  •  ак читать документацию
  •  ак использовать API REST с PowerShell
  • Ќекоторые советы и подсказки, как облегчить и улучшить практику

„то такое "REST"?

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

 ак правило, то, что нужно сделать с данными, решаетс€ тем, какой HTTP-метод вы используете. ¬от краткий список методов HTTP и их применение в REST API:

  • GET-Read
  • POST-Create
  • PATCH-Partial update/modify
  • PUT-Update/replace
  • DELETE-Remove

ƒанные, которые возвращает API REST, обычно представл€ютс€ в формате JSON.

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


–абота с документацией

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

¬ этой статье мы используем petstore.swagger.io, так как он использует попул€рный фреймворк Swagger, который довольно часто используетс€ в разработке.

petstore.swagger.io petstore.swagger.io

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

  • HTTP-метод-GET/POST/DELETE и т.д.
  • URL-адрес, св€занный с конечной точкой REST API (Ѕазовый URL, как правило, представлен в верхней части страницы документации)
  •  раткое описание

ѕодробности

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

≈сли вы нажмете на одну из строк, то получите информацию, котора€ выгл€дит так:

HTTP POST

«десь мы представили конечную точку REST, котора€ может создать новый объект pet. «десь указываетс€, как должен выгл€деть JSON, предоставленный в теле POST, и какой тип контента он принимает. ƒругие конечные точки REST указывают, что это за параметры, каким типом данных они должны быть и т.д.

Ёто основы дл€ чтени€ документации. “еперь, когда общие принцип более-менее €сны, пора начать использовать REST API с PowerShell.


ѕолучение первых данных (GET)

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

≈сли развернуть конечную точку /pet/{ petId} в документации, можно увидеть, что {petId} на самом деле €вл€етс€ параметром, который принимает целое число.

/pet/{ petId}

Ёто делает URL-адрес дл€ выборки объекта pet с идентификатором 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

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

ќшибка 404 Not found, как правило, означает, что объект не найден или URL-адрес введен неправильно.

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


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

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

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

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

как должен выгл€деть JSON

Ќачнем с создани€ хэштаблицы, который можно преобразовать в объект JSON. Raw JSON следует избегать в скриптах PowerShell, поскольку он ограничивает его возможности.

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

≈сли вам трудно создать хештаблицу, который преобразуетс€ в нужный JSON, установите модуль PsdKit и используйте команду $ JsonString | ThreadTo-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. ћетод 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 {}        {}

ќбычно API REST возвращает объект 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 дл€ создани€ нового объекта pet в Petstore:

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.domain.com/hawk.jpg}
tags      : {@{id=0}}
status    : available

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


«аключение

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

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