img

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

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

icon strelka icons icons

узнай больше на курсе

DevOps-инженер с нуля
Стань DevOps-инженером с нуля и научись использовать инструменты и методы DevOps
Укажите вашу электронную почту
Неверный адрес электронной почты
Нажимая на кнопку, вы соглашаетесь на обработку персональных данных
Готово!
Отправили доступы на вашу
электронную почту
Полный курс по сетевым технологиям
Полный курс по сетевым технологиям от Мерион Нетворкс - учим с нуля сетевых инженеров и DevOPS специалистов
Укажите вашу электронную почту
Неверный адрес электронной почты
Нажимая на кнопку, вы соглашаетесь на обработку персональных данных
Готово!
Отправили доступы на вашу
электронную почту
Python программист с нуля
Стань разработчиком на одном из самых популярных языков программирования - Python
Укажите вашу электронную почту
Неверный адрес электронной почты
Нажимая на кнопку, вы соглашаетесь на обработку персональных данных
Готово!
Отправили доступы на вашу
электронную почту

Опыт многих пользователей показывает, что, когда начинаешь использовать 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


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

Для использования различных 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 в функцию может сэкономить много времени, упростить работу и очистить сценарии.

Ссылка
скопирована
Получите бесплатные уроки на наших курсах
Все курсы
icon strelka icons icons

узнай больше на курсе

DevOps-инженер с нуля
Стань DevOps-инженером с нуля и научись использовать инструменты и методы DevOps
Подробнее о курсе
Полный курс по сетевым технологиям
Полный курс по сетевым технологиям от Мерион Нетворкс - учим с нуля сетевых инженеров и DevOPS специалистов
Подробнее о курсе
Python программист с нуля
Стань разработчиком на одном из самых популярных языков программирования - Python
Подробнее о курсе
Онлайн-курс по кибербезопасности
Полный курс по кибербезопасности от Мерион Нетворкс - учим с нуля специалистов по информационной безопасности. Пора стать безопасником!
Подробнее о курсе
Java-разработчик с нуля
Освойте backend-разработку и программирование на Java, фреймворки Spring и Maven, работу с базами данных и API
Подробнее о курсе
Этичный хакинг
Научись работать с Kali Linux, изучи самые распространенные уязвимости, разверни виртуальную лабораторию для пентестинга
Подробнее о курсе
Еще по теме:
img
Git Flow - это специальная система ветвления для Git. Она помогает команде лучше контролировать и добавлять различные версии проекта. В статье рассказываем, как ее использовать.
img
Мы рассмотрим несколько простых способов, с помощью которых вы можете управлять и отслеживать логи для своих контейнеров.
img
Узнайте, как использовать Git Hooks для автоматизации задач в рабочем процессе: от проверки коммитов до автоматического тестирования, и как настроить хуки для совместной работы в команде.
img
Откройте для себя, как канареечное развертывание может минимизировать риски при обновлении ПО. Узнайте, как постепенно внедрять новые функции и обеспечивать стабильность продукта с помощью этого метода.
img
Откройте для себя GitOps — революционный подход к управлению инфраструктурой через Git. Узнайте, как этот метод упрощает развертывание приложений и повышает надежность с помощью автоматизации и масштабируемости.
Весенние скидки
30%
50%
60%
До конца акции: 30 дней 24 : 59 : 59