По вашему запросу ничего не найдено :(
Убедитесь, что запрос написан правильно, или посмотрите другие
наши статьи:
Мы рассказали про принципы работы протокола NAT (Network Address Translation) и теперь настало время рассмотреть его настройку на оборудовании Cisco.
Настройка статического NAT (Static NAT)
Напомним, что статический NAT представляет собой сопоставление внутреннего и внешнего адреса один к одному. Он позволяет внешним устройствам инициировать подключения к внутренним с использованием статически назначенного общего адреса.
Например, внутренний веб-сервер может быть сопоставлен с определенным внутренним глобальным адресом, чтобы он был доступен из внешних сетей.
На схеме показана внутренняя сеть, содержащая веб-сервер с частным адресом IPv4. Маршрутизатор сконфигурирован со статическим NAT, чтобы позволить устройствам из внешней сети обращаться к веб-серверу. Клиент из внешней сети обращается к веб-серверу с использованием общедоступного IPv4-адреса. Статический NAT переводит общедоступный IPv4-адрес в частный.
При настройке статических трансляций NAT выполняются две основные задачи:
Создание сопоставления между внутренним локальным (inside local) адресом и внутренними глобальными (inside global) адресами. Например, внутренний локальный адрес 192.168.1.5 и внутренний глобальный адрес 208.165.100.5 на схеме настроены как статическая NAT трансляция.
После того как сопоставление настроено, интерфейсы, участвующие в трансляции должны быть настроены как внутренние (inside) и наружные (outside) относительно NAT. На схеме интерфейс маршрутизатора Serial 0/0/0 является внутренним, а Serial 0/1/0 – внешним.
Пакеты, поступающие на внутренний интерфейс маршрутизатора Serial 0/0/0 из настроенного внутреннего локального адреса IPv4 (192.168.1.5), транслируются и затем перенаправляются во внешнюю сеть. Пакеты, поступающие на внешний интерфейс Serial 0/1/0, адресованные настроенному внутреннему глобальному адресу IPv4 (208.165.100.5), переводятся на внутренний локальный адрес (192.168.1.5) и затем перенаправляются внутрь сети.
Настройка проходит в несколько шагов:
Создать статическую трансляцию между внутренним локальным и внешним глобальным адресами. Для этого используем команду ip nat inside source static [локальный _IP глобальный_IP]. Чтобы удалить трансляцию нужно ввести команду no ip nat inside source static. Если нам нужно сделать трансляцию не адреса в адрес, а адреса в адрес интерфейса, то используется команда ip nat inside source static [локальный _IP тип_интерфейса номер_интерфейса].
Определим внутренний интерфейс. Сначала зайти в режим конфигурации интерфейса, используя команду interface[тип номер] и ввести команду ip nat inside
Таким же образом определить внешний интерфейс, используя команду ip nat outside
Пример:
Router(config)# ip nat inside source static 192.168.1.5 208.165.100.5
Router(config)# interface serial0/0/0
Router(config-if)#ip nat inside
Router(config-if)#exit
Router(config)# interface serial0/1/0
Router(config-if)#ip nat outside
В результате трансляции будут проходить так:
Клиент хочет открыть соединение с веб-сервером. Клиент отправляет пакет на веб-сервер, используя общедоступный IPv4-адрес назначения 208.165.100.5. Это внутренний глобальный адрес веб-сервера.
Первый пакет, который роутер получает от клиента на внешнем интерфейсе NAT, заставляет его проверять свою таблицу NAT. Адрес IPv4 адресата находится в таблице NAT он транслируется.
Роутер заменяет внутренний глобальный адрес назначения 208.165.100.5 внутренним локальным 192.168.1.5 и пересылает пакет к веб-серверу.
Веб-сервер получает пакет и отвечает клиенту, используя внутренний локальный адрес источника 192.168.1.5.
Роутер получает пакет с веб-сервера на свой внутренний интерфейс NAT с адресом источника внутреннего локального адреса веб-сервера, 192.168.1.5. Он проверяет NAT таблицу для перевода внутреннего локального адреса во внутренний глобальный, меняет адрес источника с 192.168.1.5 на 208.165.100.5 и отправляет его из интерфейса Serial 0/1/0 в сторону клиента
Клиент получает пакет, и обмен пакетами продолжается. Роутер выполняет предыдущие шаги для каждого пакета.
Проверка статического NAT
Полезной командой для проверки работы NAT является команда show ip nat translations. Эта команда показывает активные трансляции NAT. Статические переводы, в отличие от динамических переводов, всегда находятся в таблице NAT.
Router#show ip nat translations
Pro Inside global Inside local Outside local Outside global
--- 208.165.100.5 192.168.1.5 208.165.100.70 208.165.100.70
Другой полезной командой является команда show ip nat statistics. Она отображает информацию об общем количестве активных переводов, параметрах конфигурации NAT, количестве адресов в пуле и количестве адресов, которые были выделены.
Router#show ip nat statistics
Total active translations: 1 (1 static, 0 dynamic; 0 extended)
Peak translations: 2, occurred 00:00:21 ago
Outside interfaces:
Serial0/1/0
Inside interfaces:
Serial0/0/0
Hits:7 Misses:0
Чтобы убедиться, что трансляция NAT работает, лучше всего очистить статистику из любых прошлых переводов, используя команду clear ip nat statistics перед тестированием.
Настройка динамического NAT (Dynamic NAT)
В то время пока статический NAT постоянное сопоставление между внутренним локальным и внутренним глобальным адресом, динамический NAT позволяет автоматически сопоставлять внутренние локальные и глобальные адреса (которые обычно являются публичными IP-адресами). Динамический NAT использует группу или пул публичных адресов IPv4 для перевода. Динамический NAT, как и статический NAT, требует настройки внутреннего и внешнего интерфейсов, участвующих в NAT.
Рассмотрим на примере этой схемы. Мы тут имеем внутреннюю сеть с двумя подсетями 192.168.1.0/24 и 192.168.2.0/24 и пограничным маршрутизатором, на котором настроен динамический NAT с пулом публичных адресов 208.165.100.5 - 208.165.100.15.
Пул публичных адресов (inside global address pool) доступен для любого устройства во внутренней сети по принципу «первым пришел – первым обслужили». С динамическим NAT один внутренний адрес преобразуется в один внешний адрес. При таком типе перевода должно быть достаточно адресов в пуле для одновременного предоставления для всех внутренних устройств, которым необходим доступ к внешней сети. Если все адреса в пуле были использованы, то устройство должно ждать доступного адреса, прежде чем оно сможет получить доступ к внешней сети.
Рассмотрим настойку по шагам:
Определить пул которые будут использоваться для перевода, используя команду ip nat pool [имя начальный_ip конечный_ip]. Этот пул адресов обычно представляет собой группу публичных общедоступных адресов. Адреса определяются указанием начального IP-адреса и конечного IP-адреса пула. Ключевые слова netmask или prefix-length указывают маску.
Нужно настроить стандартный access-list (ACL), чтобы определить только те адреса, которые будут транслироваться. Введем команду access-list [номер_ACL] permit source [wildcard_маска]. Про стандартные access-list’ы можно прочитать в этой статье (а про расширенные в этой). ACL который разрешает очень много адресов может привести к непредсказуемым результатам, поэтому в конце листа есть команда deny all.
Необходимо привязать ACL к пулу, и для этого используется команду ip nat inside source list [номер_ACL] number pool [название_пула]. Эта конфигурация используется маршрутизатором для определения того, какие устройства (список) получают адреса (пул).
Определить, какие интерфейсы находятся внутри, по отношению к NAT, то есть любой интерфейс, который подключен к внутренней сети.
Определить, какие интерфейсы находятся снаружи, по отношению к NAT, то есть любой интерфейс, который подключен к внешней сети.
Пример:
Router(config)# ip nat pool MerionNetworksPool 208.165.100.5 208.165.100.15 netmask 255.255.255.0
Router(config)# access-list 1 permit 192.168.0.0 0.0.255.255
Router(config)#ip nat inside source list 1 pool MerionNetworksPool
Router(config)# interface serial0/0/0
Router(config-if)#ip nat inside
Router(config-if)#exit
Router(config)# interface serial0/1/0
Router(config-if)#ip nat outside
Как это будет работать на нашей схеме:
Компьютеры с адресами 192.168.1.10 и 192.168.2.10 отправляют пакеты в сторону сервера по публичному адресу 208.165.100.70
Маршрутизатор принимает первый пакет от хоста 192.168.1.10. Поскольку этот пакет был получен на интерфейсе, сконфигурированном как внутренний интерфейс NAT, маршрутизатор проверяет конфигурацию NAT, чтобы определить, должен ли этот пакет быть транслирован. ACL разрешает этот пакет, и роутер проверяет свою таблицу NAT. Поскольку для этого IP-адреса нет записи трансляции, роутер определяет, что исходный адрес 192.168.1.10 должен быть переведен динамически. R2 выбирает доступный глобальный адрес из пула динамических адресов и создает запись перевода, 208.165.200.5. Исходный IPv4-адрес источника (192.168.1.10) является внутренним локальным адресом, а переведенный адрес является внутренним глобальным адресом (208.165.200.5) в таблице NAT. Для второго хоста 192.168.2.10 маршрутизатор повторяет эту процедуру, выбирая следующий доступный глобальный адрес из пула динамических адресов, создает вторую запись перевода - 208.165.200.6.
После замены внутреннего локального адреса источника в пакетах маршрутизатор перенаправляет пакет.
Сервер получает пакет от первого ПК и отвечает, используя адрес назначения 208.165.200.5. Когда сервер получает пакет от второго ПК, то в ответе в адресе назначения будет стоять 208.165.200.6.
Когда роутер получает с адресом назначения 208.165.200.5, то он выполняет поиск в таблице NAT и переводит адрес назначения во внутренний локальный адрес 192.168.1.10 и направляет в сторону ПК. То же самое происходит с пакетом, направленным ко второму ПК.
Оба ПК получают пакеты, и обмен пакетами продолжается. Для каждого следующего пакета выполняются предыдущие шаги.
Проверка динамического NAT
Для проверки также используется команда show ip nat отображает все статические переводы, которые были настроены, и любые динамические переводы, которые были созданы трафиком. Добавление ключевого слова verbose отображает дополнительную информацию о каждом переводе, включая то, как давно запись была создана и использовалась. По умолчанию данные о переводах истекают через 24 часа, если таймеры не были переконфигурированы с помощью команды ip nat translation timeout [время_в_секундах] в режиме глобальной конфигурации.
Чтобы очистить динамические записи до истечения времени ожидания, можно использовать команду clear ip nat translation. Полезно очищать динамические записи при тестировании конфигурации NAT. Эту команду можно использовать с ключевыми словами и переменными, чтобы контролировать, какие записи очищаются. Конкретные записи можно очистить, чтобы не прерывать активные сеансы. Только динамические переводы удаляются из таблицы. Статические переводы не могут быть удалены из таблицы.
Также можно использовать команду show ip nat statistics которая отображает информацию об общем количестве активных переводов, параметрах конфигурации NAT, количестве адресов в пуле и количестве переведенных адресов.
Поскольку у нас здесь используются листы контроля доступа ACL, то для их проверки можно использовать команду show access-lists.
Настройка Port Address Translation (PAT)
PAT (также называемый NAT overload) сохраняет адреса во внутреннем глобальном пуле адресов, позволяя маршрутизатору использовать один внутренний глобальный адрес для многих внутренних локальных адресов. Другими словами, один открытый IPv4-адрес может использоваться для сотен и даже тысяч внутренних частных IPv4-адресов. Когда несколько внутренних локальных адресов сопоставляются с одним внутренним глобальным адресом, номера портов TCP или UDP каждого внутреннего узла различают локальные адреса.
Общее количество внутренних адресов, которые могут быть переведены на один внешний адрес, теоретически может составлять 65 536 на каждый IP-адрес. Однако на практике число внутренних адресов, которым может быть назначен один IP-адрес, составляет около 4000.
Существует два способа настройки PAT, в зависимости от того, как провайдер выделяет общедоступные IPv4-адреса. В первом случае интернет-провайдер выделяет более одного публичного IPv4-адреса организации, а в другом он выделяет один общедоступный IPv4-адрес, который требуется для организации для подключения к интернет-провайдеру.
Настройка PAT для пула публичных IP-адресов
Если нам доступно более одного общедоступного IPv4-адреса, то эти адреса могут быть частью пула, который используется PAT. Это похоже на динамический NAT, за исключением того, что в этом случае недостаточно общих адресов для взаимного сопоставления внутренних адресов. Небольшой пул адресов распределяется между большим количеством устройств.
Основное различие между этой конфигурацией и конфигурацией для динамического NAT, заключается в том, что используется ключевое слово overload, которое включает PAT.
Рассмотрим настойку PAT для пула адресов по шагам:
Определить пул адресов глобальных адресов, которые будут использоваться для PAT трансляции, используя команду ip nat pool [имя начальный_ip конечный_ip] netmask [маска] | prefix-length [длина_префикса].
Создать стандартный access-list, разрешающий адреса, которые должны быть переведены. Используется команда access-list [номер_ACL] permit source [wildcard_маска].
Включим PAT, используя волшебное слово Overload. Вводим команду ip nat inside source list [номер_ACL] number pool [название_пула] overload.
Определяем, какие интерфейсы находятся внутри, по отношению к NAT, а какие снаружи. Используем команду ip nat inside и ip nat outside
Пример настройки для схемы, что использовалась ранее, только теперь мы будем использовать PAT:
Router(config)# ip nat pool MerionNetworksPool2 208.165.100.5 208.165.100.15 netmask 255.255.255.0
Router(config)# access-list 1 permit 192.168.0.0 0.0.255.255
Router(config)#ip nat inside source list 1 pool MerionNetworksPool2 overload
Router(config)# interface serial0/0/0
Router(config-if)#ip nat inside
Router(config-if)#exit
Router(config)# interface serial0/1/0
Router(config-if)#ip nat outside
Настройка PAT для одного публичного IPv4-адреса
На схеме показана топология реализации PAT для трансляции одного IP публичного адреса. В этом примере все хосты из сети 192.168.0.0/16 (соответствующие ACL), которые отправляют трафик через маршрутизатор, будут переведены на адрес IPv4 208.165.99.225 (адрес IPv4 интерфейса S0 /1/0). Трафик будет идентифицироваться по номерам портов в таблице NAT.
Настройка:
Создать лист access-list разрешающий адреса, которые нужно транслировать – access-list [номер_ACL] permit source [wildcard_маска].
Настроить преобразование адреса источника в адрес интерфейса, через команду ip nat inside source list [номер_ACL] interface [тип номер] overload
Определить внешние и внутренние интерфейсы через команды ip nat inside и ip nat outside.
Конфигурация похожа на динамический NAT, за исключением того, что вместо пула адресов мы используем адрес интерфейса с вешним IP адресом. NAT пул не определяется.
Пример:
Router(config)# access-list 1 permit 192.168.0.0 0.0.255.255
Router(config)# ip nat source list 1 interface serial0/1/0 overload
Router(config)# interface serial0/0/0
Router(config-if)#ip nat inside
Router(config-if)#exit
Router(config)# interface serial0/1/0
Router(config-if)#ip nat outside
Процесс PAT не изменятся при использовании одного адреса, или пула адресов.
Рассмотрим процесс PAT по шагам:
На схеме два разных ПК связываются с двумя разными веб-серверами. Первый ПК имеет адрес источника 192.168.1.10 и использует TCP порт 1444, а второй ПК имеет адрес источника 192.168.2.10 и по совпадению использует то же TCP порт 1444
Пакет с первого ПК сначала достигает роутера и он, используя PAT, изменяет исходный IPv4-адрес на 208.165.99.225 (inside global address). В таблице NAT нет других устройств с портом 1444, поэтому PAT использует тот же номер порта и пакет отправляется в направлении сервера по 208.165.101.20.
Далее пакет со второго компьютера поступает в маршрутизатор, где PAT настроен на использование одного глобального IPv4-адреса для всех переводов - 208.165.99.225. Подобно процессу перевода для первого ПК, PAT изменяет исходящий адрес второго ПК на внутренний глобальный адрес 208.165.99.225. Однако второй ПК имеет тот же номер порта источника, что и текущая запись PAT первого ПК, поэтому PAT увеличивает номер порта источника до тех пор, пока он не станет уникальным в своей таблице. В этом случае запись исходного порта в таблице NAT и пакет для второго ПК получает 1445 порт. Хотя оба ПК используют один и тот же внутренний глобальный адрес 208.165.99.225 и тот же номер порта источника – 1444, измененный номер порта для второго ПК (1445) делает каждую запись в таблице NAT уникальной. Это станет очевидным при отправке пакетов с серверов обратно клиентам.
Сервера отвечают на запросы от компьютеров, и используют исходный порт из принятого пакета в качестве порта назначения и исходный адрес как адрес назначения. Может казаться, что они общаются одним и тем же хостом по адресу 208.165.99.225, однако, это не так – они имеют разные порты.
Когда пакеты возвращаются на роутер, он находит уникальную запись в своей таблице NAT с использованием адреса назначения и порта назначения каждого пакета. В случае пакета от первого сервера адрес назначения 208.165.99.255 имеет несколько записей, но только одну с портом назначения 1444. Используя эту запись в своей таблице, роутер изменяет адрес IPv4 адресата пакета на 192.168.1.10, не меняя порт назначения. Затем пакет перенаправляется на первый ПК
Когда пакет от второго сервера прилетает на маршрутизатор, он выполняет аналогичный перевод. Адрес IPv4 назначения 208.165.99.225 имеет несколько записей, однако используя порт назначения 1445, роутер может однозначно идентифицировать запись трансляции. Адрес IPv4 назначения будет изменен на 192.168.2.10 и в этом случае порт назначения также должен быть изменен до исходного значения 1444, которое хранится в таблице NAT. После этого пакет высылается на второй ПК
Проверка Port Address Translation (PAT)
Для проверки PAT используются такие же команды, что и для обычного NAT. Команда show ip nat translations отображает переводы IP адресов вместе с портами и команда show ip nat statistics показывает информацию о количестве и типе активных переводов, параметрах конфигурации NAT, количестве адресов в пуле и количестве выделенных адресов.
Router#show ip nat statistics
Total active translations: 2 (0 static, 2 dynamic; 2 extended)
Peak translations: 2, occurred 00:00:07 ago
Outside interfaces:
Serial0/1/0
Inside interfaces:
Serial0/0/0
Hits:4 Misses:0
CEF Translated packets: 4, CEF Punted packets:0
Expired translations: 0
Dynamic mappings:
-- Inside Source
[Id: 3] access-list 1 pool MerionNetworksPool2 refcount 2
pool MerionNetworksPool2: netmask 255.255.255.0
start 208.165.100.5 end 208.165.100.15
type generic, total addressers 10, allocated 1(10%),
misses 0
Total doors: 0
Appl doors: 0
Normal doors: 0
Queued Packets: 0
Также для поиска проблем можно использовать дебаг, который запускается командой debug ip nat, который отображает информацию о каждом пакете, который транслируется маршрутизатором. Также можно использовать команду debug ip nat detailed, которая генерирует описание каждого пакета. Эта команда также предоставляет информацию о различных ошибках, например, таких как неспособность выделить глобальный адрес. Однако эта команда более требовательна к ресурсам устройства.
Router#debug ip nat
IP NAT debugging is on
Router#
*Aug 24 16:20:331:670: NAT*: s=192.168.1.10->208.165.99.225 d=208.165.101.20 [3730]
*Aug 24 16:20:331:682: NAT*: s=208.165.101.20 d=208.165.99.225 ->192.168.1.10 [4156]
*Aug 24 16:20:331:698: NAT*: s=192.168.1.10->208.165.99.225 d=208.165.101.20 [3731]
*Aug 24 16:20:331:702: NAT*: s=192.168.1.10->208.165.99.225 d=208.165.101.20 [3732]
*Aug 24 16:20:331:710: NAT*: s=208.165.101.20 d=208.165.99.225 ->192.168.1.10 [4157]
В выводе используются следующие символы и значения:
* (звездочка) – звездочка с NAT указывает, что перевод происходит по пути с быстрым переключением (fast-switched path). Первый пакет в разговоре всегда медленнее, остальные пакеты проходят путь с быстрым переключением.
s= - IP адрес источника
a.b.c.d ? w.x.y.z - это значение указывает, что адрес источника a.b.c.d переводится на w.x.y.z.
d= - IP адрес назначения
[xxxx] - значение в скобках - это идентификационный номер IP.
REST API – один из самых распространенных типов доступных веб-сервисов, но проектировать их сложно. Они позволяют разным клиентам, включая браузер, настольные приложения, мобильные приложения и практически любое устройство с подключением к Интернету, взаимодействовать с сервером. Именно поэтому очень важно правильно проектировать REST API, чтобы в будущем не было проблем.
Создание API с нуля может оказать непосильной задачей из-за большого количества вещей, которые необходимо учесть – от базовой безопасности до использования правильных методов HTTP, реализации аутентификации, определения того, какие запросы и ответы среди многих других принимаются и возвращаются. В этой статье я очень постарался сжать материал в 15 пунктов с важными рекомендациями, которые позволят создать хороший API. Все рекомендации никак не зависят от языка, поэтому потенциально применимы к любой платформе или технологии.
1. Обязательно используйте имена существительные в названиях путях к конечным точкам
Вам всегда следует использовать имена существительные, которые обозначают объект, который вы извлекаете или которым вы манипулируете. В качестве имени пути всегда предпочтительнее использовать множественное число. Избегайте использования глаголов в названиях путях к конечным точкам, потому что наш метод HTTP-запроса уже является глаголом и по сути не добавляет никакой новой информации.
Действие должно быть произведено с помощью методов HTTP-запроса. Наиболее распространенными являются методы GET, POST, PATCH, PUT и DELETE.
GET извлекает ресурсы
POST отправляет новые данные на сервер
PUT/PATCH модифицируют уже существующие данные
DELETE удаляет данные
Глаголы сопоставляются с функциями CRUD (Create, read, update и delete).
Помня об этих принципах, мы должны создавать маршруты типа GET /books для получения списка книг, а не GET /get-books или GET /book. Аналогично, POST /books - для добавления новой книги, PUT /books/:id - для модификации полных данных книги с заданным идентификатором (id), а PATCH /books/:id обновляет частичные изменения в книге. И наконец, DELETE /books/:id предназначен для удаления существующей книги в заданным идентификатором.
2. JSON как основной формат отправки и получения данных
Несколько лет назад прием и ответы на запросы API выполнялись в основном в XML. Но сейчас «стандартным» форматом для отправки и получения данных API в большинстве приложений стал JSON. Поэтому наш второй пункт рекомендует убедиться, что конечные точки возвращают формат данных JSON в качестве ответа, а также при приеме информации через полезную нагрузку HTTP-сообщений.
Несмотря на то, что FormData хорошо подходит для отправки данных от клиента, особенно если нам нужно отправлять файлы, они не очень подходят для текста и чисел. Нам не нужны FormData для их передачи, так как в большинстве фреймворков можно передавать JSON непосредственно на стороне клиента. При получении данных от клиента нам необходимо убедиться, что клиент правильно интерпретирует данные JSON, и для этого при выполнении запроса в заголовке ответа Content-Type должен быть установлен на application/json.
Стоит еще раз упомянуть исключение, когда мы пытаемся отправлять и получать файлы между клиентом и сервером. В этом конкретном случае нам необходимо обрабатывать файл ответа и отправлять FormData с клиента на сервер.
3. Используйте коды состояний HTTP
Коды состояний HTTP всегда полезно использовать для того, чтобы указать на выполнение или невыполнение запроса. Не используйте слишком много кодов состояний и всегда используйте одни и те же коды для одних и тех же результатов в API. Вот некоторые примеры:
200 – общее выполнение
201 – успешное создание
400 – неверные запросы от клиента, такие как неверные параметры
401 – несанкционированные запросы
403 – отсутствие прав доступа к ресурсам
404 – отсутствуют ресурсы
429 – слишком много запросов
5хх – внутренние ошибки (их следует избегать насколько это возможно)
В зависимости от ситуаций их может быть и больше, но ограничение количества кодов состояний помогает клиенту использовать более предсказуемый API.
4. Возвращайте стандартизированные сообщения
Помимо использования кодов состояния HTTP, которые указывают на результат запроса, всегда используйте стандартизированные ответы для аналогичных конечных точек. Пользователи могут всегда рассчитывать на одинаковую структуру и действовать соответственно. Это также относится к статусу, указывающему на выполнение запроса, и сообщениях об ошибках. В случае выборки коллекций придерживайтесь определенного формата, независимо от того, включает ли тело ответа массив данных, подобный этому:
[
{
bookId: 1,
name: "The Republic"
},
{
bookId: 2,
name: "Animal Farm"
}
]
или вот такой комбинированный ответ:
{
"data": [
{
"bookId": 1,
"name": "The Republic"
},
{
"bookId": 2,
"name": "Animal Farm"
}
],
"totalDocs": 200,
"nextPageId": 3
}
Здесь рекомендация заключается в том, чтобы быть последовательным независимо от того, какой подход вы выберете для этого. Аналогичное поведение должно быть реализовано при извлечении объекта, а также при создании и модификации ресурсов, которым обычно рекомендуется возвращать последний экземпляр объекта.
// Ответ после успешного вызова POST /books
{
"bookId": 3,
"name": "Brave New World"
}
Хоть это и никак не навредит, но все же излишнем будет включать универсальное сообщение, например, «Книга успешно создана», так как это уже следует из кода состояния HTTP.
И последнее, но не менее важное: при наличии стандартного формата ответа коды ошибок также важны (и даже более важные). Это сообщение должно включать информацию, которую клиент может использовать для представления ошибок конечному пользователю, а соответственно, это должно быть не общее предупреждение, такое как «то-то пошло не так», которого следует избегать, насколько это возможно. Вот пример:
{
"code": "book/not_found",
"message": "A book with the ID 6 could not be found"
}
Опять же, нет необходимости включать код состояния в содержимое ответа, но полезно определить набор кодов ошибок, таких как book/not_found, чтобы пользователь мог сопоставить их с разными строками и создать свое собственное сообщение об ошибке для конечного пользователя. В частности, для сред разработки или промежуточных сред может показаться правильным также включить стек ошибок в ответ с целью помочь в отладке ошибок. Но не включайте те, что находятся в промышленной эксплуатации, так как это создаст угрозу безопасности, раскрывая незапланированную информацию.
5. Используйте разбиение на страницы, фильтрацию и сортировку при выборе коллекций записей
Как только будет создана конечная точка, которая возвращает список элементов, необходимо будет установить разбиение на страницы. Обычно коллекции со временем растут, поэтому важно всегда следить за тем, чтобы возвращалось ограниченное и контролируемое количество элементов. Справедливо будет позволить пользователям API выбирать, сколько объектов получить, но всегда полезно заранее определить число и установить для него максимум. Основная причина, почему нужно это сделать, заключается в том, что для возврата огромного массива данных потребуется очень много времени и большая пропускная способность.
Для реализации нумерации страниц есть два хорошо известных способа: skip/limit или keyset. Первый вариант обеспечивает более удобный для пользователя способ извлечения данных, но обычно он менее эффективен, так как базы данных сканируют множество документов для извлечения нужных записей. Мне больше нравится второй вариант. Разделения на страницы с помощью keyset получает идентификатор (id) в качестве ссылки для «вырезания» коллекции или таблицы с условием без сканирования записей.
Также API должны предоставлять фильтры и возможности сортировки, которые упрощают способы получения данных. Частью решения повышения производительности являются индексные базы данных, которые позволяют максимизировать производительность при помощи шаблонов доступа, которые применяются с фильтрами и параметрами сортировки.
При проектировании API эти свойства разбиения на страницы, фильтрации и сортировки определяются как параметры запроса в URL-адресе. Например, если вы хотим получить информацию о первых 10 книгах, принадлежащих к категории «роман», то наша конечная точка будет выглядеть вот так:
GET /books?limit=10&category=romance
6. PATCH вместо PUT
Маловероятно, что необходимо будет сразу полностью обновить всю запись, обычно есть конфиденциальные или полные записи, которые следует уберечь от манипуляций пользователя. Именно поэтому для выполнения частичных обновлений ресурса следует использовать PATCH, а вот PUT полностью меняет существующий ресурс. Они оба должны использовать тело запроса для передачи информации, подлежащей модификации. Разница лишь в том, что для PATCH это поля, а для запроса PUT – полный объект. Тем не менее, стоит отметить, что ничто не мешает нам использовать PUT для частичной модификации, нет никаких «ограничений на передачу по сети», которые бы это подтверждали. Это просто факт, которого стоит придерживаться.
7. Предоставьте более подробные ответы
Шаблоны доступа являются ключевыми при создании доступных ресурсов API и возвращаемых данных. Когда система растет, то и свойства записи также растут, но не всегда все эти свойства нужны клиентам для работы. Именно в таких ситуациях становится полезным предоставление возможности возвращать сокращенные или полные ответы для одной и той же конечной точки. Если пользователю нужны только некоторые поля, то упрощенный ответ помогает снизить расход трафика и потенциально сложность получения других вычисляемых полей.
Простой способ реализовать – предоставить дополнительный параметр запроса, чтобы включить или отключить предоставление более подробного ответа.
GET /books/:id
{
"bookId": 1,
"name": "The Republic"
}GET /books/:id?extended=true
{
"bookId": 1,
"name": "The Republic"
"tags": ["philosophy", "history", "Greece"],
"author": {
"id": 1,
"name": "Plato"
}
}
8. Обязанность конечной точки
Принцип единственной обязанности фокусируется на концепции удержания функции, метода или класса на одной обязанности, которую они выполняют хорошо. Мы можем сказать, что это наш API - хороший API, если он выполняет одну конкретную вещь и никогда не меняется. Это помогает пользователям лучше понять наш API и сделать его более предсказуемым, что облегчит общую интеграцию. Лучше всего расширить список доступных конечных точек, а не создавать очень сложные конечные точки, которые пытаются решить множество задач одновременно.
9. Предоставьте полную документацию по API
Пользователи вашего API должны понимать, как использовать доступные конечные точки и чего ожидать. Это возможно только при наличии хорошей и подробной документации. Обратите внимание на следующие аспекты, чтобы ваша документация была полной.
Доступные конечные точки с описанием их назначения
Права доступа, необходимые для выполнения конечной точки
Примеры вызовов и ответов
Сообщения о предполагаемых ошибках
Немаловажным является постоянное обновление документации после внесения изменений и дополнений в систему. Лучший способ для этого – сделать документацию по API неотъемлемой частью разработки. Двумя хорошо известными инструментами в данном вопросе являются Swagger и Postman – они доступны для большинства сред разработки API.
10. Используйте SSL для обеспечения безопасности и настройте CORS
Безопасность – еще одно очень важной свойство, которым должен обладать наш API. Настройка SSL путем установки действительного сертификата на сервер обеспечит безопасную связь с пользователями и предотвратит некоторые виды потенциальных атак.
CORS (Cross-origin resource sharing – Обмен ресурсами с запросом происхождения) – это функция безопасности браузера, которая ограничивает HTTP-запросы из различных источников, которые инициируются сценариями, запущенными в браузере. Если ресурсы вашего REST API получают непростые HTTP-запросы из разных источников, то вам нужно включить поддержку CORS для того, чтобы пользователи работали соответствующим образом.
Протокол CORS требует, чтобы браузер отправил предварительный запрос на сервер и дождался утверждения (или запрос учетных данных) с сервера перед отправкой фактического запроса. Запрос предварительной проверки отображается в API как HTTP-запрос, использующий метод OPTIONS (среди других заголовков). Значит, для поддержки CORS в ресурсе REST API необходимо реализовать метод OPTIONS, который будет отвечать на предварительный запрос, по крайней мере, со следующими заголовками ответа, предусмотренными стандартом Fetch:
Access-Control-Allow-Methods
Access-Control-Allow-Headers
Access-Control-Allow-Origin
Какие значения назначать этим ключам, зависит от того, настолько открытым и гибким должен быть наш API. Мы можем назначить определённые методы и известные источники или использовать специальные символы, чтобы иметь открытые ограничения CORS.
11. Управление версиями API
В процессе разработки конечные точки начинают меняться и перестраиваться. Но мы должны, насколько это возможно, избегать внезапного изменения конечных точек для пользователя. Рекомендуется рассматривать API как ресурс с обратной совместимость, в котором новые и обновленные конечные точки должны быть доступны, но не должны влиять на предыдущие стандарты.
Вот где управление версиями API приходит на помощь – когда клиенты должны иметь возможность выбирать, к какой версии подключаться. Есть несколько способов описать управление версиями API:
Добавление нового заголовка x-version=v2
Наличие параметра запроса ?apiVersion=2
Версия как часть URL: /v2/books/:id
12. Кэшируйте данные для повышения производительности
Чтобы повысить производительность нашего API, полезно следить за данными, которые редко меняются и к которым часто обращаются. Для таких данных мы можем рассмотреть возможность использования базы данных в памяти или кэш-памяти, которая избавит от доступа к основной базе данных. Главная проблема здесь заключается в том, что данные могут устареть, поэтому следует решить вопрос с внедрением последней версии.
Использование кэшированных данных будет полезным для пользователей для загрузки конфигураций и каталогов информации, которые не предназначены для постоянного изменения в течение долгого времени. При использовании кэширования не забудьте включить Cache-Control в заголовки. Это поможет пользователям эффективно использовать систему кэширования.
13. Используйте даты в формате UTC
Сложно представить системы, которые в какой-то момент перестает работать из-за дат. На уровне данных важно быть логичным в том, как даты отображаются на клиентских приложениях. ISO 8601 – это международный стандартный формат данных для даты и времени. Данные должны быть в формате Z или UTC, для которых пользователи могут могли бы выбрать часовой пояс в случае, если такая дата должны отображаться при любых условиях. Вот пример того, как должны выглядеть даты:
{
"createdAt": "2022-03-08T19:15:08Z"
}
14. Конечная точка проверки работоспособности
Может произойти ситуация, когда наш API перестанет работать, и для его запуска потребуется время. При таких обстоятельствах клиенты хотят знать, что службы недоступны, и быть в курсе ситуации. Для этого предоставьте конечную точку (например, GET /health), которая бы определяла работоспособность API. Эта конечная точка может вызываться и другими приложениями, такими как балансировщики нагрузки. Можно продвинуться еще дальне и сообщать о периодах технического обслуживания или работоспособности частей API.
15. Разрешите аутентификацию по ключу API
Аутентификация с помощью ключей API даст возможность сторонним приложениям легко создавать интеграцию с нашим API. Эти ключи API следует передавать с помощью пользовательского заголовка HTTP (например, Api-Key или X-Api-Key). Ключи должны иметь дату окончания срока действия, и должна быть возможность их отозвать с целью признания недействительными по соображениям безопасности.
Всем привет! В этой статье мы хотим рассказать про то, что такое Extension Mobility в Cisco Unified Communications Manager (CUCM) , и про то, как его настроить.
Cisco Extension Mobility позволяет пользователю залогиниться на любой телефон, подключенный к CUCM. Это может использоваться, когда пользователи часто перемещаются с одного рабочего места на другое. Все персональные настройки, такие как номер телефона (Directory Number) и быстрый набор (user-specific parameters) могут быть динамически настроены на телефоне, который будет использоваться, что позволит пользователю не теряя времени начать работу.
Стоит отличать Extension Mobility от Device Mobility, который позволяет перенастраивать телефоны в зависимости от их местонахождения.
Extension Mobility работает как сервис, и после того как телефон будет на него подписан, у пользователя появится возможность выбрать этот сервис и ввести свой User ID и PIN. После этого CUCM применит Device Profile и перезагрузит телефон.
Если пользователь будет пытаться залогиниться на нескольких телефонах одновременно, то есть несколько вариантов:
Allow Multiple Logins – Пользователь может войти на несколько телефонов сразу, при этом все телефоны звонят одновременно
Deny Login – Пользователь может быть залогиненным только на одном устройстве. Если он попытается войти на другое, то будет выдаваться сообщение об ошибки, до тех пор, пока он не выйдет из первого устройства.
Auto-logout - Пользователь также может быть залогиненным только на одном устройстве, но когда он вводит свой данные на втором устройстве, система отключит его на первом.
Настройка Extension Mobility
Шаг 1. Активация сервиса Cisco Extension Mobility
Первым делом нам нужно перейти в раздел Cisco Unified Serviceability и перейти во вкладку Tools – Service Activation. Тут выбираем наш сервер и ставим галочку напротив пункта Cisco Extension Mobility.
Шаг 2. Настройка EM Service параметров
Возвращаемся в раздел CM Administration и переходим во вкладку System – Service Parameters. Здесь выбираем наш сервер, и из выпадающего меню Service выбираем Cisco Extension Mobility. Ниже в разделе Clusterwide Parameters. Тут можно настроить параметры входа, такие как время работы, возможность множественного входа и другие.
Шаг 3. Добавление EM Service.
Переходим во вкладку Device – Device Settings – Phone Services и нажимаем Add New. В поле Service Name указываем желаемое имя сервиса. В поле Service URL нужно указать следующую строчку:
http://[IP_адрес_CUCM_Publisher]:8080/emapp/EMAppServlet?device=#DEVICENAME#
Перед сохранением нужно удостовериться, что галочка в пункте Enable стоит. Также можно активировать пункт Enterprise Subscription, для того чтобы все телефоны подписались на Extension Mobility Service автоматически.
Шаг 4. Создание Default Device Profile
Default Device Profile со стандартными параметрами используется если модель телефона не совпадает с моделью в Profile. Для настройки переходим во вкладку Device – Device Settings – Default Device Profile и нажимаем Add New. В строке Product Type выбираем модель телефона, которая будет использоваться, а в строке Device Protocol указываем протокол, по которому работает телефон - SCCP или SIP. Доступные настройки зависят от выбранного телефона и протокола. Здесь можно задать настройки Music on Hold, Locale, Phone Button и Softkey Template и другие, которые будут использованы в профиле.
Шаг 5. Создание Device Profile
Создадим Device Profile, который будет использоваться на телефоне, после того, как пользователь залогинится. Переходим во вкладку Device – Device Settings – Device Profile и в новом окне нажимаем Add New. Так же как и в предыдущем пункте выбираем модель телефона, протокол и задаем параметры профиля (user-specific settings). Затем нажимаем Save.
После этого в открывшемся окне в меню Association Info нажимаем на Line [1] – Add a new DN и указываем номер телефона в стоке Directory Number. При необходимости заполняем остальные поля и нажимаем Save и возвращаемся в предыдущее меню.
Шаг 6. Подписка Device Profile на EM Service
Из меню Device Profile в выпадающем меню Related Links справа сверху выбираем Subscribe/Unsubscribe Services и нажимаем Go.
В открывшемся окне в стоке Select a Service выбираем созданный нами сервис и нажимаем Next. Далее указываем имя сервиса и нажимаем Subscribe, а затем Save.
Шаг 7. Ассоциируем пользователей End User с Device Profile.
Сначала нужно создать учетную запись пользователя. Для этого идем во вкладку User Management – End User и нажимаем Add New. Здесь нужно заполнить поля User ID, Password, PIN, Last Name и остальные, если необходимо.
Затем заходим в настройки созданного пользователя и в разделе Extension Mobility из поля Available Profiles переносим созданный нами профиль в поле Controlled Profiles, путем нажатия на кнопку “вниз”. Ниже в поле Device Profile выбираем профиль для пользователя.
Шаг 8. Включение EM на телефонах
Переходим во вкладку Device – Phone и выбираем телефон, на котором хотим настроить Extension Mobility. Находим раздел Extension Mobility и ставим галочку в пункте Enable Extension Mobility.
Далее нужно подписать телефон на сервис. Как и ранее сверху справа находим меню Related Links и выбираем Subscribe/Unsubscribe Services. (этот пункт не обязателен, если при создании сервиса мы поставили галочку в пункте Enterprise Subscription). Тут снова указываем созданный нами сервис и его имя и нажимаем Save.
Шаг 9. Тестирование
После всех настроек на телефоне, на котором мы настроили EM service. Для этого на телефоне нажимаем кнопку Services.
Здесь выбираем наш сервис и вводим Used ID и PIN.
После этого телефон перезагрузится и загрузится с новым профилем и номером. Выйти из профиля можно также нажатием кнопки Services.