Введение в Stripe CLI и расширение Stripe for VS Code

Введение в Stripe CLI

Stripe CLI (интерфейс командной строки) и расширение Stripe for VS Code являются необходимыми инструментами при создании, тестировании и управлении интеграцией Stripe. В этой статье вы узнаете о мощных возможностях Stripe CLI и о том, как вы можете использовать эти возможности как в командной строке, так и с помощью расширения VS Code.

Предварительные условия

Если вы хотите следовать за нами, вы можете установить Stripe CLI на различных платформах. Инструкции по установке для вашей системы находятся здесь, а расширение для VS Code можно установить через VS Code marketplace. Вы также можете следовать большей части этого руководства, используя Stripe Shell, который является Stripe CLI, доступным прямо в браузере.

Подключение к учетной записи Stripe

Чтобы подключиться к аккаунту Stripe, нам нужно войти в систему с помощью CLI:

stripe login

Нам будет выдан код сопряжения и предложено нажать Enter, чтобы открыть браузер для подтверждения кода сопряжения с нашим аккаунтом:

После подтверждения кода сопряжения мы можем разрешить доступ. Можно подключить CLI к любому из перечисленных здесь аккаунтов, но в моем случае у меня только один аккаунт под названием VS Code.

Затем мы можем закрыть браузер и вернуться в CLI, и мы увидим, что мы подключены.

Основы: CRUD

CRUD означает создание, чтение, обновление и удаление. Мы увидим, как мы можем использовать эти действия для управления ресурсами в Stripe API. Выполнив команду stripe resources, мы увидим обширный список ресурсов API, с которыми мы можем взаимодействовать.

В данный момент мы сосредоточимся на одном ресурсе — общем ресурсе, который нам понадобится при интеграции со Stripe, — объекте Customer. Давайте создадим клиента:

stripe customers create --name 'Matt Ling'

Параметр --name указывает на имя верхнего уровня объекта Customer.

Теперь мы можем получить этот ресурс из API с помощью его ID, который мы скопируем из предыдущего вывода create:

stripe customers retrieve cus_MDFfFTRXkhvNqP

Далее давайте обновим этого клиента, используя его ID:

stripe customers update cus_MDFfFTRXkhvNqP --name 'Martina Ling'

Мы видим, что имя клиента было обновлено. Наконец, мы удалим этого клиента:

stripe customers delete cus_MDFfFTRXkhvNqP -c. Здесь мы передаем сокращенный флаг -c, чтобы сказать CLI не запрашивать подтверждения удаления:

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

Но некоторые конечные точки Stripe API предназначены для выполнения действий, таких как переход объектов из одного состояния в другое, например, создание намерения платежа, а затем переход к требованию действия (для аутентификации) или к успеху. Давайте создадим более сложный вызов, используя API Payment Intents. Я хотел бы создать платеж для клиента, подтвердить его немедленно, используя предварительно токенизированную кредитную карту, и в то же время сохранить этот метод оплаты для этого клиента для использования вне сессии в будущем. Списание средств с пользователя вне сессии означает, что вы можете попытаться списать средства с платежного метода этого клиента, пока он не присутствует на вашем сайте или в приложении. С помощью CLI мы можем быстро создать этот сценарий использования, не перебирая множество объектов в приборной панели и не написав ни строчки кода:

stripe payment_intents create --customer cus_MDFjyVfH75GQ49 --amount 1111 --currency eur --confirm true --payment-method pm_card_visa --setup-future-usage off_session

Одно замечание о параметрах, которые мы передаем здесь. В то время как в аргументах API используются символы подчеркивания, CLI ожидает аргументы в «шашлычной оболочке», т.е. --payment-method. Мы также можем передавать API структурированные данные, используя -d и url-кодированную форму имени аргумента. Это очень похоже на cURL.

Давайте перейдем в приборную панель, чтобы проверить все, чего мы здесь достигли:

Мы видим, что платеж был произведен, клиент был связан с платежом, и что метод оплаты был установлен для будущих внесеансовых платежей.

Ведение журнала

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

stripe logs tail

stripe customers list

В режиме реального времени мы видим, что API получил HTTP GET запрос к конечной точке v1 customers и ответил HTTP 200 OK. Давайте выполним команду create Customer, которую мы использовали ранее:

stripe customers create --name 'Matt Ling'

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

События Webhook

При взаимодействии со Stripe через приборную панель или через API побочным эффектом этих взаимодействий является генерация событий о важных моментах. Эти события могут включать такие вещи, как создание клиентов или проведение платежей. Существует огромное количество событий, о которых вы можете получать уведомления, список которых можно посмотреть здесь. Эти события также известны как webhooks или webhook events.

Прослушивание и реагирование на эти события webhook является очень рекомендуемой и даже необходимой частью вашей интеграции Stripe. Часть вашей системы, которая должна прослушивать эти события, называется конечной точкой webhook. Давайте вспомним, что это такое на высоком уровне. Точно так же, как ваша система может совершать HTTP-вызовы к Stripe для выполнения таких действий, как создание платежей, Stripe также может совершать HTTP-вызовы к вашей системе, чтобы информировать вас о важных событиях. Поэтому Stripe необходимо знать о HTTP-маршруте в вашу систему, на который мы можем отправлять события webhook.

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

Во-первых, давайте установим соединение в реальном времени с нашей учетной записью, чтобы увидеть, какие события генерируются:

stripe listen

Теперь выполним команду, которая сгенерирует событие. Создадим еще одного клиента:

stripe customers create --name 'Matt Ling'

Мы видим, что было сгенерировано событие customer.created, которое CLI транслирует в реальном времени.

В производственной, тестовой или QA-среде ваши события webhook будут отправлены на ваши серверы для обработки. Но если вы разрабатываете конечную точку webhook на своей локальной машине, вы будете правы, если зададитесь вопросом, как можно получить события, которые вы видите в выводе stripe listen, и туннелировать их на свой локальный сервер разработки.

Ответ заключается в том, что команда listen поддерживает прослушивание и пересылку событий в конечную точку по вашему выбору. Предположим, что у вас есть тестовый сервер, запущенный на localhost:4242 с маршрутом в ваше приложение под названием /webhook-endpoint. В моем случае у меня есть простой сервер node с конечной точкой webhook, запущенный на моей локальной машине, который не делает ничего, кроме как передает эхо типа события, которое он получает, в консоль.

Теперь давайте прослушаем события на нашем аккаунте и направим их в эту конечную точку:

stripe listen --forward-to localhost:4242/webhook-endpoint

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

Отличным примером этого является событие checkout.session.completed. Для того чтобы это событие сработало в обычных условиях, должна быть создана сессия, пользователь перенаправляется туда, заполняет свои платежные данные и завершает сессию оформления заказа. Но при тестировании, если мы просто хотим получить это событие в нашей конечной точке webhook, мы можем просто «запустить» это событие с помощью CLI.

stripe trigger checkout.session.completed

Глядя на вывод CLI, мы можем предположить, что делает CLI: он создает фикстуры для каждого вызова API, необходимого для создания события завершения сеанса оформления заказа, и выполняет всю работу за вас. Мы также можем видеть события, поступающие через CLI, а в третьей панели — события, отражаемые нашим простым веб-сервером, работающим на localhost:

Если ваша система использует горячую загрузку кода, это очень быстрый и интересный способ разработать конечную точку webhook, внести изменения в код, запустить событие, протестировать и наблюдать за результатами. Давайте посмотрим, как все это поддерживается в среде разработки VS Code.

Расширение Stripe для VS Code

Расширение Stripe for VSCode поддерживает все функциональные возможности Stripe CLI, встроенного прямо в IDE, и даже больше полезных функций, давайте сначала рассмотрим их.

Защита ключей API

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

Фрагменты кода Stripe

Расширение VS Code также предоставляет полезную функцию завершения фрагментов кода, которая помогает ускорить разработку. Например, давайте начнем вводить stripe.checkout, и нам будут представлены все варианты сниппетов, которые помогут нам выполнить вызовы API checkout. Более того, выбрав сниппет, вы можете навести курсор на различные части цепочки методов и быть перенаправленными непосредственно в сопроводительную документацию.

Хвостовые журналы в VS Code

Как и в командной строке, мы можем просматривать журналы в VS Code, не выходя из IDE. Если я нажму на Start streaming API logs и вызову событие создания клиента, мы увидим, что вызов API для этого вызова создания передается в реальном времени:

Потоковая передача событий

Подобно тому, как мы видели в командной строке, мы можем транслировать события в реальном времени и в IDE. Если мы нажмем на Start streaming events и затем вызовем событие checkout.session.created, мы также увидим, что события будут перечислены здесь:

Перенаправление событий на локальный сервер

Если мы выберем Пересылать события на локальную машину:

нам будет предложено указать URL, на который мы хотим пересылать события. Также будет запрошена конечная точка connect webhook, но пока мы можем использовать ту же конечную точку, поскольку connect не входит в сферу применения данной демонстрации.

Мы также убедимся, что та же конечная точка echo webhook запущена на localhost:

Если мы запустим событие checkout.session.completed с помощью опции Trigger new default event:

Мы увидим, что события поступают через команду listen и перенаправляются на наш сервер:

Stripe CLI, лежащий в основе расширения VS Code, является чрезвычайно продуктивным способом изучения и экспериментирования с API, отслеживания логов, создания и тестирования конечной точки webhook, и все это полностью интегрировано с VS Code.

Резюме

Stripe CLI — это необходимый набор инструментов для вашего инструментария при создании интеграции Stripe. Мы будем рады услышать, что вы создаете с его помощью, будь то прием платежей, использование терминала или создание сервиса подписки. Дайте нам знать, над чем вы работаете!

Об авторе

Мэтью Линг (@mattling_dev) — представитель разработчиков в Stripe. Мэтт любит возиться с новыми технологиями, обожает Ruby и кофе, а также подрабатывает профессиональным музыкальным фотографом. Его фотосайт находится по адресу matthewling.com, а сайт разработчиков — mattling.dev.

Оставайтесь на связи

Кроме того, вы можете оставаться в курсе событий Stripe несколькими способами:

📣 Следите за нами в Twitter
💬 Присоединяйтесь к официальному серверу Discord
📺 Подпишитесь на наш канал Youtube
📧 Подпишитесь на Dev Digest