Нядаўна мы выпусцілі InterSystems API Manager (IAM) – новы кампанент InterSystems IRIS Data Platform, які забяспечвае назіранне, кантроль і кіраванне трафікам у / з web API у рамках IT-інфраструктуры.
У гэтым артыкуле я пакажу як наладжваць IAM і прадэманструю некаторыя са шматлікіх магчымасцяў, якія даступныя вам з IAM. InterSystems API Manager дазваляе вам:
- Назіраць за API, разумець хто выкарыстоўвае API, якія API найболей папулярныя, а якія патрабуюць дапрацоўкі.
- Кантраляваць хто выкарыстоўвае API і абмяжоўваць выкарыстанне API ад простага абмежавання доступу да абмежаванняў у залежнасці ад запыту - у вас ёсць наладжвальны кантроль і вы можаце хутка рэагаваць на змены патэрнаў спажывання API.
- Абараняць API з дапамогай цэнтралізаваных механізмаў бяспекі, такіх як OAuth2.0, LDAP ці Key Token Authentication.
- Спрасціць працу іншых распрацоўнікаў і падаць ім выдатны досвед працы з API, адкрыўшы адмысловы партал для распрацоўнікаў.
- Маштабаваць API і забяспечыць мінімальную затрымку пры адказе.
Кіраванне API з'яўляецца неабходным для пераходу да SOA або мікрасэрвіснай архітэктуры, спрашчаючы інтэграцыю паміж асобнымі (мікра)сэрвісамі, робячы іх даступнымі для ўсіх вонкавых і ўнутраных спажыўцоў. У выніку новыя API становіцца прасцей ствараць, падтрымліваць і спажываць.
Калі вы ўжо карыстаецеся InterSystems IRIS, вы можаце дадаць да вашай ліцэнзіі опцыю IAM. Опцыя IAM бясплатная для замоўцаў InterSystems IRIS, але для пачатку выкарыстання IAM неабходна запытаць у InterSystems новы ліцэнзійны ключ.
Калі вы яшчэ не карыстаецеся InterSystems IRIS і толькі плануеце паспрабаваць InterSystems API Manager, звернецеся ў InterSystems.
Пачатак працы і ўстаноўка
Заказчыкі InterSystems дыстрыбутыў IAM могуць загрузіць з сайта раздзел "Software Distribution" і запусціць як Docker кантэйнер. Мінімальныя сістэмныя патрабаванні:
- 17.04.0 +.
- 1.12.0 +.
- InterSystems IRIS 2019.1.1+.
Першапачаткова патрабуецца загрузіць Docker выява (Важна! Архіў з WRC не з'яўляецца Docker выявай, трэба яго распакаваць, усярэдзіне Docker выява):
docker load -i iam_image.tarГэтая каманда зробіць выяву IAM даступным для наступнага выкарыстання на вашым серверы. IAM працуе як асобны кантэйнер, таму вы можаце маштабаваць яго незалежна ад InterSystems IRIS. Для запуску IAM патрабуецца доступ да InterSystems IRIS для загрузкі ліцэнзіі.
Наладзьце InterSystems IRIS:
- Уключыце вэб-дадатак
/api/IAM - Уключыце карыстальніка
IAM - Змяніце пароль карыстальніка
IAM
Цяпер запусцім кантэйнер IAM. У архіве вы знойдзеце скрыпты iam-setup для Windows і Unix (і Mac). Гэтыя скрыпты дапамогуць вам правільна наладзіць зменныя асяроддзі, дазваляючы кантэйнеру IAM ўсталяваць злучэнне з InterSystems IRIS. Вось прыклад працы скрыпту на Mac:
source ./iam-setup.sh
Welcome to the InterSystems IRIS and InterSystems API Manager (IAM) setup script.
This script sets the ISC_IRIS_URL environment variable that is used by the IAM container to get the IAM license key from InterSystems IRIS.
Enter the full image repository, name and tag for your IAM docker image: intersystems/iam:0.34-1-1
Enter the IP address for your InterSystems IRIS instance. The IP address has to be accessible from within the IAM container, therefore, do not use "localhost" or "127.0.0.1" if IRIS is running on your local machine. Instead use the public IP address of your local machine. If IRIS is running in a container, use the public IP address of the host environment, not the IP address of the IRIS container. xxx.xxx.xxx.xxx
Enter the web server port for your InterSystems IRIS instance: 52773
Enter the password for the IAM user for your InterSystems IRIS instance:
Re-enter your password:
Your inputs are:
Full image repository, name and tag for your IAM docker image: intersystems/iam:0.34-1-1
IP address for your InterSystems IRIS instance: xxx.xxx.xxx.xxx
Web server port for your InterSystems IRIS instance: 52773
Would you like to continue with these inputs (y/n)? y
Getting IAM license using your inputs...
Successfully got IAM license!
The ISC_IRIS_URL environment variable was set to: http://IAM:****************@xxx.xxx.xxx.xxx:52773/api/iam/license
WARNING: The environment variable is set for this shell only!
To start the services, run the following command in the top level directory: docker-compose up -d
To stop the services, run the following command in the top level directory: docker-compose down
URL for the IAM Manager portal: http://localhost:8002Як бачыце поўнае імя выявы, IP-адрас, порт InterSystems IRIS і пароль для карыстача IAM – усё, што трэба для пачатку працы.
Замест запуску скрыпту можна ўсталяваць зменныя асяроддзі ўручную:
ISC_IAM_IMAGE=intersystems/iam:0.34-1-1
ISC_IRIS_URL=http://IAM:<PASS>@<IP>:<PORT>/api/iam/licenseзапуск
Цяпер запусцім IAM, выканаўшы каманду:
docker-compose up -dГэтая каманда парадкуе кантэйнеры IAM і гарантуе, што ўсё запушчана ў карэктна. Стан кантэйнераў правяраецца з дапамогай каманды:
docker psАдкрыйце ў браўзэры інтэрфейс адміністратара localhost:8002.
Пакуль што тут пуста, бо гэта зусім новы вузел. Давайце гэта зменім. IAM падтрымлівае канцэпцыю працоўных месцаў (workspaces) для падзелу API на модулі і/ці каманды. Перайдзіце на працоўную вобласць "default" якую мы будзем выкарыстоўваць для нашых эксперыментаў.
Колькасць запытаў для гэтай працоўнай прасторы па-ранейшаму роўна нулю, але вы атрымаеце ўяўленне аб асноўных канцэпцыях IAM у меню злева. Першыя два элементы: Сэрвісы (Services) і Маршруты (Routes) найболей важныя:
- Сэрвіс (Service) - API, да якога мы жадаем падаць доступ спажыўцам. Такім чынам, REST API у InterSystems IRIS з'яўляецца Сэрвісам, як і, напрыклад, Google API, калі вы захочаце яго выкарыстоўваць.
- Маршрут (Route) вырашае, у які Сэрвіс павінны быць перанакіраваны ўваходныя запыты. Кожны Маршрут мае пэўны набор умоў, і калі яны выкананы, запыт накіроўваецца ў адпаведны Сэрвіс. Напрыклад, Маршрут можа супадаць з IP, даменам адпраўніка, HTTP-метадамі, часткамі URI або камбінацыяй паказаных прыкладаў.
Сэрвіс
Давайце створым Сэрвіс InterSystems IRIS, з наступнымі значэннямі:
Поле
Значэнне
Апісанне
імя
вясёлкавая абалонка
Назва Сэрвісу
гаспадар
IP
Хост ці ip сервера InterSystems IRIS
порт
52773
Вэб-порт сервера InterSystems IRIS
шлях
/api/atelier
Каранёвы шлях
пратакол
HTTP
пратакол
Астатнія значэнні пакіньце па змаўчанні. Націсніце кнопку Create і запішыце ID створанага Сэрвісу.
маршрут
Цяпер давайце створым маршрут:
Поле
Значэнне
Апісанне
шлях
/api/atelier
Каранёвы шлях
пратакол
HTTP
пратакол
service.id
guid from 3
Сэрвіс (ID з папярэдняга кроку)
Астатнія значэнні пакіньце па змаўчанні. Націсніце кнопку Create і запішыце ID створанага Маршруту. Па змаўчанні IAM слухае ўваходныя запыты на порце 8000. Цяпер запыты, якія адпраўляюцца на http://localhost:8000 і якія пачынаюцца з /api/atelier перанакіроўваюцца ў InterSystems IRIS.
Тэставанне
Давайце паспрабуем стварыць запыт у REST кліенце (я выкарыстоўваю ).
Адправім GET запыт на http://localhost:8000/api/atelier/ (не забудзьцеся / на канцы) і атрымаем адказ ад InterSystems IRIS. Кожны запыт праходзіць праз IAM які збірае метрыкі:
- Код стану HTTP.
- Затрымка.
- Маніторынг (калі настроены).
Я зрабіў яшчэ некалькі запытаў (уключаючы два запыты на неіснуючыя канчатковыя кропкі, такія як /api/atelier/est/), вынікі адразу бачныя на панэлі маніторынгу:
Праца з убудовамі
Цяпер, калі ў нас настроены Маршрут, мы можам кіраваць нашым API. Мы можам дадаваць характарыстыкі, якія дапоўняць наш сэрвіс.
Найбольш распаўсюджаным спосабам змены паводзін API з'яўляецца даданне плагіна. Убудовы ізалююць асобныя функцыянальныя магчымасці і могуць быць падлучаныя да IAM як глабальна, так і толькі да асобных сутнасцяў, такім як Карыстальнік (група карыстачоў), Сэрвіс ці Маршрут. Мы пачнем з дадання плагіна «Rate Limiting» (Абмежаванне колькасці запытаў) у Маршрут. Для ўсталявання сувязі паміж падключаемым убудовай і маршрутам нам патрэбен унікальны ідэнтыфікатар (ID) маршруту.
Абмежаванне колькасці запытаў
Націсніце Plugins (Падключаюцца модулі) у меню левай бакавой панэлі. Вы бачыце ўсе актыўныя плагіны на гэтым экране, але так як гэты сервер IAM новы, актыўных плагінаў пакуль няма. Таму пераходзіце да наступнага кроку, націснуўшы "New Plugin".
Убудова, які нам патрэбен, знаходзіцца ў катэгорыі «Traffic Control» (Кіраванне трафікам) і завецца «Rate Limiting» (Абмежаванне колькасці запытаў). Абярыце яго. Ёсць даволі шмат настроек, якія вы можаце тут задаць, але нас хвалююць толькі два палі:
Поле
Значэнне
Апісанне
маршрут_ідэнтыфікатар
ID
ID Маршруту
config.minute
5
Колькасць запытаў у хвіліну
Вось і ўсё. Убудова настроены і актыўны. Заўважу, што мы можам выбіраць розныя часавыя інтэрвалы, такія як хвіліна, гадзіна ці дзень. Настройкі можна камбінаваць (напрыклад, 1000 запытаў у гадзіну і пры гэтым 100 запытаў у хвіліну). Я абраў хвіліны, бо гэта дазваляе лёгка праверыць працу плагіна.
Калі вы зноў адправіце той жа самы запыт у Postman, вы ўбачыце, што адказ вяртаецца з 2 дадатковымі загалоўкамі:
- XRateLimit-Limit-minute: 5
- XRateLimit-Remaining-minute: 4
Гэта кажа кліенту, што ён можа здзяйсняць да 5 запытаў у хвіліну і ў бягучым часовым інтэрвале можа здзейсніць яшчэ 4 запыты.
Калі вы будзеце рабіць адзін і той жа запыт зноў і зноў, то ў рэшце рэшт у вас скончыцца даступная квота і замест гэтага вы атрымаеце код статуту HTTP 429 з наступным целам адказу:
Пачакайце хвіліну, і вы зноўку зможаце адпраўляць запыты.
Гэта зручны механізм, які дазваляе:
- Абараніць бэкэнд ад скокаў нагрузкі.
- Паведамляць кліентам, колькі запытаў яны могуць здзейсніць.
- Манетызаваць API.
Вы можаце задаваць значэння для розных часавых інтэрвалаў і такім чынам згладжваць API трафік за пэўны перыяд часу. Дапушчальны, вы дазваляеце 600 запытаў у гадзіну па вызначаным Маршруце. У сярэднім выходзіць 10 запытаў за хвіліну. Але нішто не замінае кліенту выканаць усе 600 запытаў у першую хвіліну гадзіны. Можа, гэта тое, што трэба. Магчыма, вы захочаце дасягнуць больш раўнамернай нагрузкі на працягу гадзіны. Усталяваўшы значэнне поля config.minute роўным 20, вы гарантуеце, што вашыя карыстачы здзяйсняюць не больш за 20 запытаў у хвіліну і 600 запытаў у гадзіну. Гэта дапушчае невялікія скокі на хвілінным інтэрвале ў параўнанні з цалкам асераднёным струменем у 10 запытаў у хвіліну, але карыстачы не могуць выкарыстоўваць гадзінную квоту на працягу адной хвіліны. Цяпер ім спатрэбіцца не менш за 30 хвілін, для выкарыстання ўсіх сваіх запытаў. Кліенты атрымаюць дадатковыя загалоўкі для кожнага зададзенага часавага інтэрвалу, напрыклад:
HTTP Загаловак
Значэнне
X-RateLimit-Limit-hour
600
X-RateLimit-Remaining-hour
595
X-RateLimit-Limit-minute
20
X-RateLimit-Remaining-minute
16
Вядома, існуе мноства розных спосабаў налады абмежаванняў запытаў у залежнасці ад таго, чаго вы хочаце дасягнуць.
Высновы
На гэтым я і скончу, думаю матэрыялу цалкам дастаткова для першага артыкула аб InterSystems API Manager. Мы выкарыстоўвалі толькі адзін з больш чым 40 плагінаў. Вы можаце зрабіць з IAM яшчэ шмат чаго цікавага:
- Дадайце цэнтральны механізм аўтэнтыфікацыі для ўсіх вашых API.
- Маштабуйце нагрузку з дапамогай балансавальніка да некалькіх Сэрвісам.
- Дадавайце новую функцыянальнасць і выпраўленні памылак для тэставай аўдыторыі перад поўным абнаўленнем.
- Падайце унутраным і вонкавым распрацоўнікам спецыялізаваны вэб партал, які дакументуе ўсе API.
- Кэшуйце запыты для памяншэння часу чакання адказу і зніжэння нагрузкі на бэкэнд сістэмы.
Спасылкі
Вебинар
Запрашаем Вас на вэбінар "Кіраванне API з InterSystems API Management", які адбудзецца 21 лістапада ў 10:00 па маскоўскім часе (GMT+3).
InterSystems API Manager (IAM) – новы кампанент InterSystems IRIS Data Platform, які забяспечвае маніторынг, кантроль і кіраванне трафікам у / з web API у рамках IT-інфраструктуры. На вэбінары мы прадэманструем ключавыя магчымасці InterSystems API Management:
- Сродкі маніторынгу трафіку API.
- Сродкі кантролю трафіку API, у тым ліку кантроль прапускной здольнасці, абмежаванне колькасці выклікаў API, вядзення спісаў дазволеных і забароненых спісаў IP-адрасоў і г.д.
- Сродкі налады бяспекі API.
- Партал распрацоўшчыкаў для публікацыі інтэрактыўнай дакументацыі на API.
- Адзіная кропка доступу да API.
Вебінар разлічаны на архітэктараў, распрацоўшчыкаў і сістэмных адміністратараў.
!
Крыніца: habr.com