По вашему запросу ничего не найдено :(
Убедитесь, что запрос написан правильно, или посмотрите другие
наши статьи:
Использование 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
Работа с документацией
Для использования различных API REST необходимо научиться читать и интерпретировать документацию. К счастью, если вы знаете, как читать один тип документации, вы сможете быстро научиться читать другие.
В этой статье мы используем petstore.swagger.io, так как он использует популярный фреймворк Swagger, который довольно часто используется в разработке.
На предыдущем рисунке показана наиболее важная информация о конечных точках REST API:
HTTP-метод-GET/POST/DELETE и т.д.
URL-адрес, связанный с конечной точкой REST API (Базовый URL, как правило, представлен в верхней части страницы документации)
Краткое описание
Подробности
Первая страница документации просто замечательная, и, как правило, с помощью этой информации можно выполнить большинство запросов, требующих использования метода HTTP GET. Но такие методы, как POST и SET, обычно требуют, чтобы вы щелкнули и развернули строку, чтобы получить больше информации.
Если вы нажмете на одну из строк, то получите информацию, которая выглядит так:
Здесь мы представили конечную точку REST, которая может создать новый объект pet. Здесь указывается, как должен выглядеть JSON, предоставленный в теле POST, и какой тип контента он принимает. Другие конечные точки REST указывают, что это за параметры, каким типом данных они должны быть и т.д.
Это основы для чтения документации. Теперь, когда общие принцип более-менее ясны, пора начать использовать REST API с PowerShell.
Получение первых данных (GET)
Используя REST API с PowerShell обычно довольно просто, используется встроенные командлеты, таким образом, нет необходимости в дополнительных модулях. Мы собираемся извлечь данные с помощью метода GET в конечной точке /pet/{ petId}.
Если развернуть конечную точку /pet/{ petId} в документации, можно увидеть, что {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. 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 в функцию может сэкономить много времени, упростить работу и очистить сценарии.
Привет всем! В сегодняшней статье мы хотим рассказать об одном крайне полезном трюке, который поможет сохранить время Вам и клиентам, позвонившим в Вашу компанию. Демонстрировать этот функционал мы будем на IP-АТС Asterisk через графический интерфейс FreePBX 14.
Данная статья будет особенно актуальна для тех, кто пользуется переадресацией входящих звонков на мобильный телефон.
Возможно, кто-то уже использует данный способ, но многие могут о нем и не знать.
Кейс
Итак, представим себе такую гипотетическую ситуацию:
К нам в компанию позвонил клиент;
Звонок поступил на ринг группу 345, в которой находится 3 внутренних номера;
Звонки с этих внутренних номеров переадресовываются на мобильные номера менеджеров;
И вот на своём мобильном телефоне звонок клиента принял менеджер Алексей;
Они общаются, и тут у клиента возникает вопрос к инженеру, клиент просит перевести его на инженера;
Алексей может находиться вне офиса и не за стационарным телефоном и не может перевести звонок клиента обратно;
Он просит клиента перезвонить на общий номер компании и донабрать внутренний номер инженера;
Ситуация вполне нормальная, но мы вынуждены просить нашего клиента звонить повторно, донабирать номер, тратить свое время и так далее.
Вот бы было здорово иметь возможность перевести звонок клиента на нужный номер прямо с мобильного? А ещё лучше, если мы сможем поговорить с человеком, на которого нужно перевести звонок и узнать не занят ли он, прежде чем делать трансфер!
Такая возможность есть и сейчас мы объясним как её реализовать.
Решение
Дело в том, что когда звонки с нашей IP-АТС переводятся на мобильный телефон, то канал между ними не разрывается. Например, если у вас включена запись, то вы можете увидеть, что такие звонки также записываются. А значит, мы можем контролировать такие звонки на любом устройстве, даже на мобильном телефоне. Делать трансфер, ставить на ожидание, парковать и так далее.
Для того, чтобы открылась возможность сделать трансфер на другой номер, находясь в звонке, нужно передать приложению Asterisk Dial() нужный аргумент. Во FreePBX это настраивается в Settings → Advanced Settings в разделе Dialplan and Operational.
Здесь есть два поля - Asterisk Dial Options, в котором можно добавить аргументы Dial() при совершении внутренних звонков и Asterisk Outbound Trunk Dial Options, который отвечает за обработку аргументов Dial() при совершении внешних звонков через транк, как раз это поле нам и нужно.
По умолчанию в данном поле всего один аргумент - большая буква T. Этот аргумент позволяет позвонившей стороне сделать трансфер используя feature code - ##
Сервисный код ## соответствует функции “слепого” трансфера -In-Call Asterisk Blind Transfer
Однако, когда мы принимаем звонок на мобильном телефоне, то являемся вызываемой стороной, поэтому нам нужен другой аргумент – маленькая буква t. С помощью данного аргумента, мы сможем делать трансфер находясь в звонке, используя всё тот же feature code - ##.
Итак, можно добавить аргумент t в поле Asterisk Outbound Trunk Dial Options, но тогда этот функционал распространится на все транки, которые созданы на вашей IP-АТС.
Есть более безопасный способ включить трансфер на принимающей стороне. Для этого переходим в Connectivity → Trunks и в настройках транка на вкладке General ищем опцию Asterisk Trunk Dial Options
По умолчанию, в данной опции мы так же увидим аргумент T, так как стоит параметр System, который просто подтягивает значения аргумента из Asterisk Outbound Trunk Dial Options в Advanced Settings
Выбрав параметр Override, мы можем записать сюда какие угодно аргументы и они будут действовать только для данного конкретного транка. Запишем сюда маленькую t.
Итак, теперь, если Вы приняли вызов на мобильном телефоне, а человек, с которым Вы разговариваете просит перевести его на другого сотрудника, Вы можете просто:
Нажать ## на своём мобильном телефоне, после чего Вы услышите в трубке сообщение “перевод”;
Набрать нужный номер (например - 529). В это время позвонивший будет слышать музыку на ожидании;
Вызов автоматически завершится, а звонок будет переадресован тому, чей номер Вы набрали;
Profit;
А помните мы говорили, что можно ещё поговорить с тем, кому нужно перевести вызов, прежде чем его переводить, чтобы уточнить не занят ли этот человек? Так вот такая возможность при принятии звонка на мобильном тоже есть!
Если мы откроем возможные сервисные коды (feature code) функций трансфера, то увидим, что их два - ## - In-Call Asterisk Blind Transfer, который мы уже знаем, и *2 - функция консультативного трансфера - In-Call Asterisk Attended Transfer.
Таким образом, можно также пользоваться консультативным трансфером, в этом случае нужно:
Нажать *2 на своём мобильном телефоне, после чего Вы услышите в трубке сообщение “перевод”;
Набрать нужный номер (например - 529). В это время позвонивший будет слышать музыку на ожидании;
Дождаться, пока человек, которому нужно перевести вызов, ответит и узнать у него можно ли делать перевод. Если он сбросит или не возьмёт трубку, то ваш разговор с ожидающим на линии абонентом возобновится и Вы сможете объяснить ему, что соединиться не удалось;
Если человек, которому нужно перевести вызов готов поговорить с ожидающим на линии абонентом, то нужно просто завершить вызов. Тогда разговор продолжится уже между ними;
Кстати! Номер, который Вы набираете после того или иного сервисного кода, не обязательно должен быть внутренним. Это может быть любой другой номер (например, мобильный - *289012345678). Главное набирать его в таком формате, чтобы Ваша IP-АТС могла до него дозвониться.
Носки бывают чрезвычайно полезны. Сейчас мы расскажем, как правильно настроить их на роутере MikroTik. Итак, поговорим о SOCKS?
Предисловие
SOCKS (SOCKet Secure) – это сетевой протокол, с помощью которого можно обеспечивать прохождение TCP пакетов в обход блокирующих правил Firewall’а. Это реализуется за счёт proxy-сервера (также называют SOCKS-сервер), который контролирует подключение внутренних клиентов и их права на доступ к внешним ресурсам или же наоборот – внешних клиентов, к ресурсам внутри сети. SOCKS работает на сеансовом уровне, поэтому с помощью него можно проксировать FTP, HTTP, Telnet и другие верхнеуровневые протоколы. В то время как HTTP-прокси, как правило, позволяет проксировать только GET и POST запросы.
Установление соединения
Когда клиент хочет получить доступ к внешнему ресурсу, который блокирует Firewall, то соединение происходит следующим образом:
Клиент подключается к proxy-серверу (обычно используется TCP порт 1080);
Сервер проверяет список доступа и выясняет, есть ли у клиента права на доступ к внешним ресурсам;
Если клиент имеет такие права, то proxy-сервер пересылает пакет на внешний ресурс, к которому хочет получить доступ клиент;
Сервер создаёт сессию между клиентом и внешним ресурсом и между ними начинается обмен пакетами верхнеуровневых протоколов. После установления соединения можно передавать и UDP пакеты.
В настоящее время, MikroTik поддерживает SOCKS версии 4 при указании внешнего ресурса он понимает только IP-адрес. Версия SOCKS4a – может резолвить доменные имена внешних ресурсов. Более поздняя версия протокола – SOCKS5 включает расширенную поддержку аутентификации, подключение по UDP и IPv6.
На сегодняшний день, протокол SOCKS5 пока не поддерживается на устройствах MikroTik. Хотя пользователи очень просят разработчиков включить поддержку SOCKS5 в новые релизы RouterOS вот уже 8 лет. Поэтому при работе с SOCKS совместно с MikroTik, клиент также должен иметь 4 версию.
Необходимо очень тщательно настроить Firewall'ьные правила и список доступа SOCKS чтобы исключить нежелательный доступ извне. Как правило, скомпрометированные через уязвимости SOCKS устройства, используются для рассылки спама и фишинговых писем.
Перейдём к настройкам SOCKS-сервера на MikroTik:
Параметры настройки через WinBox
Параметры настройки SOCKS сервера в WinBox находятся в IP → Socks:
Как только вы поставите галочку напротив Enabled сервер станет активным. Далее, необходимо настроить списки доступа, для этого нажимаем на кнопку Access:
Активные SOCKS сессии, проходящие через сервер можно отслеживать на вкладке Connections
Параметры настройки через Termial
Для того, чтобы настроить SOCKS через терминал нужно также сначала настроить параметры сервера. Настройка проводится через команду ip socks set, доступы следующие параметры:
enabled - включает функционал SOCKS proxy-сервера (yes - включен, no - выключен);
port - номер порта, на котором сервер будет слушать SOCKS запросы. По умолчанию - 1080
connection-idle-timeout - время, через которое будут сброшены неактивные сессии (по умолчанию – 2 минуты (2m));
max-connections - максимальное число одновременных подключений (по умолчанию - 200)
Посмотреть текущие или настроенные параметры можно командой:
/ip socks print
Далее необходимо настроить правила, по которым будет осуществляться контроль доступа к серверу SOCKS. Для этого вводим команду /ip socks access set, доступны следующие параметры:
action - действие, которое будет предпринято при соответствии критериев данного правила:
allow - разрешить прохождение трафика по данному правилу;
deny - запретить прохождение трафика по данному правилу.
dst-address - адрес сервера назначения;
dst-port - TCP порт назначения, на котором удаленный сервер слушает SOCKS
src-address - адрес источника пакетов (клиент);
src-port - TCP порт источника
Практическое применение
Допустим злой сисадмин заблокировал наш любимый wiki.merionet.ru, выяснил адрес и забанил.
О том, как настраивать правила Firewall в MikroTik читайте здесь
Но одному нашему сотруднику обязательно нужно иметь доступ к данному ресурсу. Поэтому сисадмин открывает активирует SOCKS сервер и настраивает список доступа.
В качестве адреса клиента указывается IP адрес компьютера сотрудника, которому нужно открыть доступ (в нашем случае 192.168.11.48), в качестве порта источника – любой TCP порт от 1024 до 65535. В качестве адреса назначения – IP адрес ресурса wiki.merionet.ru и порт 80 (http).
Та же самая настройка через терминал выглядит следующим образом:
ip socks> set enabled=yes
ip socks access> add src-address=192.168.11.48 src-port=1024-65535 dst-address=212.193.249.136 dst-port=80
... action=allow
Готово, теперь дело за клиентом, который должен настроить сотрудник. Покажем настройку на примере браузера Google Chrome. Открываем Settings → Advanced → Confidentiality and Security, крутим в самый низ до пункта System и выбираем Proxy settings. В появившемся окне выбираем LAN settings → ставим галку напротив Use a proxy server for your LAN и заходим в Advanced. В появившемся окне вбиваем параметры нашего SOCKS сервера в строку Socks (в нашем случае 192.168.11.1 и порт 1080) и применяем настройки:
Теперь обновляем страничку wiki.merionet.ru и ву-а-ля, всё заработало! В окне Connections видны соединения с нашего компьютера до IP адреса wiki.merionet.ru.
Послесловие
Данная статья носит исключительно образовательный характер и не ставит своей целью научить кого-либо обходить правила Firewall. Протокол SOCKS 4 устарел, не поддерживает аутентификацию и не может резолвить доменные адреса. В целях безопасности, мы не рекомендуем использовать этот протокол вообще и в том числе – настраивать его на MikroTik.
По умолчанию – сервер SOCKS на роутерах MikroTik отключен. Если Вы обнаружили, что он активирован, то это может быть признаком того, что Ваш роутер был скомпрометирован злоумышленниками. Об этом мы подробнее расскажем в следующих статьях.