Как начать работать с Marketplace License Manager SaaS API

В этом разделе вы узнаете, как интегрировать SaaS-продукт c Yandex Cloud Marketplace License Manager SaaS API.

Схема взаимодействия с APIСхема взаимодействия с API

На схеме:

1. Пользователь приобретает подписку на SaaS-продукт в Marketplace.
2. Marketplace передает пользователю ссылку на SaaS-продукт. URL-параметр token в передаваемой ссылке содержит JWT-токен.
   Адрес для перехода задается при создании версии продукта в Marketplace в поле Ссылка на лендинг.
3. Пользователь переходит по ссылке, в результате SaaS-продукту передается JWT-токен.
4. Первый вариант аутентификации: у пользователя уже есть учетная запись в SaaS-продукте. В этом случае он вводит свои учетные данные и входит в систему.
5. Второй вариант аутентификации: у пользователя нет учетной записи в SaaS-продукте. В этом случае он создает новую учетную запись и входит в систему.
6. SaaS-продукт отправляет в Marketplace запрос ProductInstanceService.Claim, содержащий полученный от пользователя токен и идентификатор ресурса в SaaS-продукте.
7. В результате Marketplace привязывает подписку к ресурсу и возвращает SaaS-продукту привязку (объект Lock).
8. SaaS-продукт сохраняет полученную привязку и начинает предоставлять доступ к ресурсу.
9. SaaS-продукт периодически запрашивает привязку в Marketplace.
10. Marketplace возвращает SaaS-продукту привязку до тех пор, пока подписка активна.

Перед началом работыПеред началом работы

Чтобы начать работать c Marketplace License Manager SaaS API:

1. Станьте партнером Marketplace и зарегистрируйте аккаунт юридического лица.
2. В кабинете партнера создайте продукт и тариф с типом Subscription.
3. Создайте сервисный аккаунт, от имени которого вы будете аутентифицироваться в API.
4. Назначьте сервисному аккаунту роли license-manager.saasSubscriptionSupervisor и marketplace.productInstances.saasSupervisor на профиль партнера или на отдельный продукт.
5. Получите IAM-токен для сервисного аккаунта, от имени которого вы будете аутентифицироваться в License Manager API.

Чтобы воспользоваться примерами, установите утилиты cURL и gRPCurl (при использовании gRPC API).

Настройте интеграцию с APIНастройте интеграцию с API

Чтобы реализовать бизнес-логику продукта, самостоятельно доработайте код вашего приложения, настроив интеграцию с License Manager SaaS API и Product Instance Manager API для проверки статуса и типа подписок:

1. Аутентифицируйтесь в License Manager SaaS API и Product Instance Manager API от имени сервисного аккаунта. Для аутентификации используйте IAM-токен.

2. Создайте страницу, на которую нужно перенаправить пользователя во время привязки купленной им подписки к сервису. На этой странице пользователь должен будет аутентифицироваться.

   При перенаправлении пользователя на такую страницу в строке запроса в параметре token передается JWT-токен (token), сгенерированный Yandex Cloud. JWT-токен действует 15 минут и содержит:

   • идентификатор подписки, которую купил пользователь (license_instance_id);
   • идентификатор шаблона подписки, который вы создали в кабинете партнера (license_template_id);
   • идентификатор запущенного экземпляра продукта пользователя (product_instance_id).

3. Пока действует JWT-токен, на созданной странице авторизуйте пользователя и сохраните уникальный идентификатор экземпляра запущенного продукта (product_instance_id).

4. Привяжите уникальный идентификатор экземпляра продукта пользователя (product_instance_id) к купленной пользователем подписке (license_instance_id).

   Привязать идентификатор к подписке можно с помощью метода REST API Claim для ресурса ProductInstance или вызова gRPC API ProductService/Claim.

   Передайте в запросе:

   • JWT-токен (token);
   • (опционально) уникальный идентификатор пользователя в вашей системе (resource_id);
   • (опционально) дополнительные метаданные (resource_info).

   В ответе вы получите идентификатор привязки (lock_id) — он находится в параметре metadata. Если в ответе ошибка, значит, подписка не привязалась к сервису и нужно попросить пользователя заново пройти все шаги.

5. Организуйте периодическую проверку того, что привязка подписки активна. Используйте для этого идентификатор привязки (lock_id), полученный на предыдущем шаге.

   Получить актуальную информацию о привязке подписки можно с помощью:

   • метода REST API get для ресурса Lock или вызова gRPC API LockService/Get.

     В ответе должен возвращаться активный ресурс Lock, для которого state = LOCKED, а время окончания действия подписки end_time находится в будущем.

   • метода REST API getByResourceID для ресурса Lock или вызова gRPC API LockService/Get.

     При успешном ответе должен возвращаться активный ресурс Lock, иначе — ошибка NOT_FOUND.

   Примечание

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

6. Организуйте бизнес-логику обработки подписок: учет потребления, ограничения по времени, количеству пользователей и т.п.

Получите информацию о привязкеПолучите информацию о привязке

Чтобы получить информацию о привязке, воспользуйтесь методом REST API Get для ресурса Lock или вызовом gRPC API LockService/get:

curl \
  --request GET \
  --url 'https://marketplace.api.yandexcloud.kz/marketplace/license-manager/saas/v1/locks/<идентификатор_привязки>' \
  --header 'Authorization: Bearer <IAM-токен>' \
  --header 'Content-Type: application/json'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d '{
      "lockId": "<идентификатор_привязки>"
  }' \
  marketplace.api.yandexcloud.kz:443 yandex.cloud.marketplace.licensemanager.saas.v1.LockService/Get

В результате Marketplace вернет привязку (объект Lock), если подписка активна и привязана к экземпляру продукта пользователя.

Отследите продление подпискиОтследите продление подписки

Чтобы отслеживать продление подписки, необходимо контролировать изменение значения поля end_time в экземпляре подписки.

Чтобы получить данные об экземпляре подписки, воспользуйтесь методом REST API Get для ресурса Instance или вызовом gRPC API InstanceService/Get:

curl \
  --request GET \
  --url 'https://marketplace.api.yandexcloud.kz/marketplace/license-manager/saas/v1/instances/<идентификатор_экземпляра>' \
  --header 'Authorization: Bearer <IAM-токен>'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d '{
      "instanceId": "<идентификатор_экземпляра>"
  }' \
marketplace.api.yandexcloud.kz:443 yandex.cloud.marketplace.licensemanager.saas.v1.InstanceService/Get