Настроить интеграцию что это

Проектирование интеграции с веб-сервисом

Все больше и больше аналитиков, проджектов и продактов приходят в айти из маркетинга, консалтинга, продаж и других нетехнических индустрий, да и вообще без опыта работы. И я тут не стал исключением. Существует проблема, что в первые годы на тебя падает немерено технических терминов и концепций, ты пытаешься в них разобраться, но не понимаешь до какого уровня деталей тебе надо опускаться в каждой из них. Надо ли разбираться, что значит обнаруженный тобой термин WSDL и какие бывают виды асинхронного выполнения запроса, или достаточно знать, что у веб-сервиса просто есть запрос и ответ? Статья нужна, чтобы решить эту проблему для одной из самых частых фичей – научиться работать с веб-сервисом для обмена данными, выполнения целевых действий в других системах и прочих интеграций.

На русском и английском есть куча материала про то, зачем нужны веб-сервисы, какие они бывают, как их спроектировать, есть прикольные кейсы. Но про то, как взаимодействовать с ними на практике, особенно на сложных корпоративных системах, я не нашел ничего исчерпывающего. А как показывает опыт, черт кроется именно в деталях и подпунктах, большинство из описанных в этой статье – мои собственные «шишки».

Представь, что тебе надо сделать такую штуку: в зависимости от ответа веб-сервиса, который угадывает зарплату человека, отобразить пользователю кнопку разного цвета. Скажем если зарплата до 20 тыс. рублей, ты делаешь красную кнопку, если от 20 до 100 тыс., то желтую, и если она больше 100 тыс., то зеленую. Казалось бы, что может быть проще! Но чтобы описать эту задачу для разработки и разобраться во всем самому, тебе будет не лишним обратить внимание на 15 разных вопросов, а если фича безумно важная, то еще на 8 других.

Ну чего, погнали, программа минимум:

Найди или попроси страницы с описанием веб-сервиса и задачи, в которых кто-то описывал интеграцию с ним. Проверь наличие всех пунктов ниже, чтобы не раздражать человека, спрашивая лишний раз 🙂

Продовые и тестовые ссылки / адреса (англ. Endpoints PROD, QA / TEST). Веб-сервис доступен именно по этим адресам. Ссылка на тестовый контур будет полезна, чтобы проверить работу сервиса, не внося изменений и не нагружая прод. Ссылки очень похожи на адреса обычных сайтов по формату, часто в них будет содержаться слово “api”. Можно попробовать открыть их в браузере, и иногда что-то отобразится.

Тут веб-сервис поиска в Youtube выдал ошибку, поскольку ожидал, что в запросе мы передадим ключ API (выдается на их сайте, индивидуальный для каждого)

Аутентификация. Как мы будем авторизоваться в веб-сервисе, чтобы он нам отдал нужные данные? Тут много разных вариантов: по ключу API, токену, логину и паролю в теле запроса, бывают и другие.

Запроси WSDL, если это SOAP веб-сервис. Есть два самых популярных видов веб-сервисов: SOAP и REST, обычно об этом написано в самом верху страницы с описанием сервиса. REST теоретически может поменять формат ответа в любой момент, а SOAP отвечает только в формате, который находится в схеме (XSD – XML Schema Definition). Эта схема ответа, а также ссылки содержатся в файле WSDL, который ты передаешь с запросом – то есть для SOAP ссылки можно отдельно не запрашивать, если уже есть WSDL. Соответственно на продовом и тестовом контурах WSDL разные, потому что содержат разные адреса. Также для SOAP придется делать запросы в какой-то программе, часто пользуются бесплатным SOAP UI. SOAP для запросов и ответов использует .XML файлы, а REST — .JSON, .XML, .TXT

Примеры запросов: что передавать в веб-сервис для разных случаев, чтобы получить нужные тебе данные? Все ли эти данные у тебя есть?

Запрос в Swagger

Запроси примеры релевантных успешных ответов. Если ты имеешь дело с REST, то еще часто для описания сервисов делают Swagger (файлик для приложения SwaggerUI). Попроси ссылку на него — там есть приятный интерфейс, можно отправить запрос — получить ответ, авторизоваться, посмотреть какие есть соседние с твоим сервисы на PROD и QA.

Ответ в Swagger

Что мы делаем во время ожидания ответа от сервиса? Особенно актуально, если имеем дело с сервисами, которые долго отвечают, и это заставляет ждать живого пользователя, как в примере с разноцветной кнопкой. Пользователь может не понять, почему ничего не происходит.

Таймаут (максимальное время ожидания ответа) и реакция на него. После таймаута мы перестаем ожидать ответ и происходит определенное поведение твоей системы, к примеру отправка запроса в другой сервис. Почему перестаем ожидать ответ: либо из-за того, что не можем больше ждать, надо уже как-то реагировать, либо если спешить некуда, но мы достаточно уверены, что сервис уже не ответит. Будет круто, если сможешь получить распределение времени ответа сервиса. Можно будет поставить таймаут, к примеру, как 99 перцентиль, но чаще это уже будет описано / можно спросить разработчиков сервиса.

Характеристики полей: тип поля, обязательность и длина строки.

Тип поля. Надо следить, чтобы мы передавали в запросе поля в том же формате, который ожидает получить сервис. Самые частые кейсы тут: передаем число как строку текста “2007”, вместо 2007 и разные форматы дат и времени, к примеру Date “2007-01-01” вместо DateTime “2007-01-01 11:00:00”. Когда получаем ответ от сервиса, тоже лучше следить, что данные из ответа запроса приходят в том же типе/формате, который мы ожидаем, иначе их надо будет конвертировать (переводить) в нужный тип.

Обязательность полей – есть поля, без которых запрос не будет работать, а есть те, которые можно не передавать иногда. Если ты знаешь, что поле необязательное, но тебе его надо передавать по полученному примеру запроса, то можно обсудить с разработчиками сервиса, что будет если не передавать его, возможно оно лишнее и не надо его добывать откуда-то, чтобы положить в запрос. Для SOAP можно посмотреть обязательность полей в WSDL или в примере запроса, ищи зеленый текст . Для REST это можно посмотреть в Swagger, обозначается красной звездочкой.

SOAP UI Swagger

Длина строк – лучше проверить, что строки текста, которые мы передаем в запросе не сожмутся. Для SOAP есть возможность посмотреть в WSDL мин / макс длину строк в символах, ищи поля minLenght / maxLength. Для REST длина строк определяется на стороне сервиса и обычно само собой подразумевается, что строки не сожмутся. Однако если ты делаешь важную фичу или передаешь текстовую строку длиной в абзац в поле, которое по смыслу должно быть коротким (Имя, Телефон, Адрес), лучше уточнить это у разработчиков сервиса.

Поведение твоей системы в случае ошибок от сервиса (англ. exception flow). Надо продумать, как реагировать на ошибки от сервиса, к примеру можно делать перезапросы по такому правилу: сервис запрашивается раз в 20 минут, суммарно до 10 раз, после чего забиваем.

Поведение твоей системы, если важные поля в ответе придут пустыми / с некорректным значением (к примеру, писать сообщение об этом). На практике такое случается частенько, пример: сервис начинает возвращать не валидированные данные из новых источников.

Полностью проверь работу интеграции на PROD / QA контуре, если есть такая возможность. Обрати внимание, что на QA контуре часто бывают моки или заглушки – когда сервис возвращает в ответе одно и то же подстановочное значение вместо нормальной обработки запроса. Если веб-сервис должен что-то сделать в другой системе, проверь, что это целевое действие выполнено, покажи запросы владельцу сервиса. На практике довольно часто всплывают проблемы именно на этом этапе.

Нагрузка. Обсуди с владельцем сервиса частотность вызова его сервиса, изменение нагрузки в течение суток / недели, а также ее потенциальные изменения в будущем.

Делать ли логирование запроса и ответа. Есть много плюсов: можно отслеживать баги, фрод, смотреть сколько было запросов сервиса суммарно.

интерфейс для просмотра логов Kibana

Кэширование ответа сервиса. Если есть вероятность, что в течение короткого времени потребуется вызов сервиса с такими же параметрами запроса и предполагается, что ответ не будет меняться, то можно этот ответ сохранить, чтобы не вызывать сервис еще раз. Особенно актуально, если вызов сервиса является небесплатным и небыстрым.

Левел 2. Эти моменты лучше проверить, если фича важная:

Доступность сервиса в зависимости от времени. Если у сервиса есть “часы пик” во время которых он становится менее доступным, следует это учесть во время планирования работы с ним: предупредить пользователей, внимательно продумать реакцию на таймаут и ошибки в ответах.

Алерты. Если успешный ответ от сервиса является критичным, можно настроить алерты на ошибки, доступность или резкое изменение среднего значения в ответе / доли определенных значений.

Надо ли реализовать логику обработки ответа на стороне веб-сервиса. На нашем примере с разноцветной кнопкой в зависимости от полученной в ответе зарплаты: можно сделать эту логику в твоей системе (часто самый простой вариант), однако если границы 20 и 100 тыс. предполагается часто менять, а также классификацией красный / желтый / зеленый будут пользоваться другие люди и системы, может иметь смысл доработать сервис и передавать в ответе сразу цвет кнопки. Иначе запросто может возникнуть рассинхронизация и одинаковые по зарплате люди будут с разными кнопками.

Меняется ли структура ответа в зависимости от параметров запроса? К примеру, в запросе есть параметр “strategy”, в зависимости от которого в ответе возвращается разное число параметров. Наша система должна учитывать это.

Логика обработки ответа. Если ты меняешь существующую интеграцию с веб-сервисом, не забудь о том, что на вашей системе может быть логика, которую надо обновить. К примеру, вы считываете только определенные поля из ответа и надо добавить новые.

Левел 3. Самый важный проект за год, баги недопустимы!

Примеры ошибок. Возможно, потребуются сценарии и алерты на разные ошибки. Так ошибки описаны у Яндекс.Толоки

Невыполнение целевого действия при успешных ответах. Бывают случаи, когда сервис в случае невыполнения целевого действия возвращает 200 OK (код об успешном выполнении). Пример: сервис сам передает запрос в другой сервис после нашего запроса, но не дожидается ответа от него и сразу шлет 200 OK, но на самом деле целевое действие еще могло не успеть произойти и должен быть ответ с кодом 201 Created.

Синхронное / Асинхронное выполнение запроса. При Синхронном выполнении запроса, он обрабатывается сразу при получении. При асинхронном взаимодействии запросы попадают в очередь на стороне сервиса и целевое действие сразу не выполняется. У владельцев или пользователей сервиса можно узнать, сколько в среднем событие лежит в очереди и сколько еще требуется времени на обработку запроса. Успешные коды 201 и 202 намекают на асинхронность. Если ты их получил, лучше проверить, что целевое действие выполнится.

Самые популярные HTTP статус коды

Спасибо за внимание! Делитесь в комментах своими кейсами.

Источник

Настроить интеграцию что это

13 ноября 2017 Опубликовано в разделах: Азбука терминов. 20525

Что значит API

Простейшей аналогией использования API будет процесс работы на калькуляторе для сложных вычислений. Допустим, у вас есть задача, вы можете понимать её суть, строить уравнения и графики, но не умеете совершать арифметические действия с цифрами. Рядом с вами лежит калькулятор, умеющий делать эти операции с легкостью. Вы не знаете, что происходит внутри вычислительной машины, да и знать это не обязательно. Вы отдаёте информацию в одном виде, а получаете в другом, нужном для ваших целей.

По такому принципу работает любое API. Вам все равно, как программа получает ответ, какой путь проходит запрос внутри неё, как производятся вычисления. Вы уверены только в одном – в ответ будет выдана стандартизированная информация об успехе операции или её ошибке.

API интерфейс позволяет не тратить свое время, деньги и силы на покупку «нового велосипеда». Вы получаете работающий информационный порт, получающий и отдающий необходимые объемы данных в целях вашей разработки.

Плюсы:

• Экономия на разработке своего интерфейса.
• Нет необходимости разбираться в нюансах вопроса.
• API разрабатывают профессионалы и учитывают все факторы внутренних процессов, о которых вы можете не знать, создавая свое решение.
• Позволяет общаться с закрытыми через другие протоколы сервисами.

Минусы:

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

Примеры API

API интеграция – это процесс подключения приложения к внешнему интерфейсу данных. Работа с API начинается с изучения документации и используемых протоколов, а далее непосредственной интеграции вашей программы к интерфейсу. Рассмотрим самые популярные сервисы, имеющие собственное API.

VKAPI

Внешний интерфейс взаимодействия популярной социальной сети ВКонтакте с клиентами, а также с браузерными и серверными приложениями. Позволяет управлять сообщениями сообществ, обложками групп, страницами пользователей при наличии соответствующих ключей доступа.

Все запросы осуществляются к адресу https://api.vk.com/method/

После слэша идёт наименование используемого API-метода и передаются GET-параметры запроса. Ответ так же приходит по HTTPS в формате JSON.

TELEGRAM BOT API

Одно из самых популярных API. С его помощью осуществляется контроль ботов в мессенджере Telegram. После создания бота через @botfather и получения необходимых ключей доступа, вы можете начать взаимодействие с внутренним интерфейсом.

Запросы осуществляются по адресу

Где token выражает секретный ключ.

Запросы посылаются через HTTPS соединения, название метода указывается через слэш к основному адресу. Ответ приходит в формате JSON.

OPEN WEATHER MAP API

Зачастую бывает необходимо получить информацию о погоде, не задействуя сторонние виджеты и платные приложения. На помощь приходит сервис OpenWeatherMap с открытым и бесплатным API. После регистрации и получения идентификационных данных вы можете отправлять с серверных скриптов запросы на погоду по всему миру. В ответ на ID города ресурс возвращает максимально подробную информацию о текущей погоде и дает прогноз на ближайшее время.

Формат работа: HTTP передача по api.openweathermap.org/data/2.5/weather?id= c указанием идентификационного номера желаемого города. Ответ сервера: JSON.

GOOGLE MAPS API

Что может быть приятнее, чем интерактивная карта мира на сайте? Особенно, если это не шаблонная вставка из Google Maps, а ваша персональная редакция популярной карты с личными кластерами маркеров. Карта будет взаимодействовать с другими скриптами на сайте, посылая информацию о кликах и координатах.

Подобные возможности предлагает JavaScript API Google Maps. Модуль полностью скриптовой и работает на стороне браузера, поэтому HTTP-запросы из PHP и формирование заголовков на стороне сервера, как было в других API, нам не нужно.

Например, выставление метки на карте будет выглядеть так:

var mark = new google.maps.Marker( <
position: myPOS,
map: map,
title:»Hello!»
>);

Для чего нужно и чем полезно использование API

Полезных функций довольно много.

Первый аспект

Можно наладить интерактивное взаимодействие пользователя с социальными сетями и мессенджерами, использовать возможности сторонних вычислительных систем для вывода курсов валют, погоды и другой важной информации.

С помощью API выполняется мгновенное подключение к серверам других ресурсов и программных решений, которое в обычной реализации заняло бы недели разработок. API упрощает жизнь там, где не нужна уникальная реализация, и в приоритете надежность и безопасность.

Второй аспект

Если вы владелец сложных вычислительных мощностей, популярного сервиса или хранилища данных для открытого или полуприватного доступа, то хорошим ходом будет поднять собственное API. Что это даст:

• Большой поток клиентов.
• Упрощенный доступ к вашим услугам для партнеров.
• Удобство статистического анализа использования сервиса.

Третий аспект

Почти тот же, что и второй. Но без необходимости реализовывать API для открытого доступа. Если у вас есть портал, и вы хотите создать под него мобильное приложение на Android/IOS, то переписать систему под единое API – лучшее решение. Вся структура данных систематизируется. Сайт и приложение будут работать через единые каналы данных.

– Только качественный трафик из Яндекса и Google
– Понятная отчетность о работе и о планах работ
– Полная прозрачность работ

Источник