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

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

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

На схеме:

1. Приложение запрашивает метаданные виртуальной машины. Для этого используется адрес сервиса метаданных, доступный изнутри ВМ.
2. В ответе приложение получает значения полей id и vendor.folderId. Эти значения используются для получения списка привязок.
3. Приложение запрашивает в Marketplace License Manager API список привязок, передавая в качестве параметров полученные значения в полях resourceId и folderId.
4. В ответе приложение получает массив привязок, выбирает нужную и активирует с ее помощью некую функциональность.
5. Периодически приложение запрашивает подтверждение привязки к ресурсу.
6. В ответе приложение получает подтверждение привязки и продолжает работу.

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

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

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

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

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

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

Запросите метаданные виртуальной машиныЗапросите метаданные виртуальной машины

1. Подключитесь к виртуальной машине с вашим продуктом.

2. В терминале ВМ выполните команду:

   curl \
     --header Metadata-Flavor:Google \
     169.254.169.254/computeMetadata/v1/instance/?recursive=true
   

   Где 169.254.169.254 — адрес сервиса метаданных, доступный изнутри виртуальной машины.

   Результат:

   {
     "attributes": {
       "install-unified-agent": "0",
       "serial-port-enable": "0",
       "ssh-keys": "user1:ssh-rsa ABC...",
       "user-data": "#cloud-config\ndatasource:\n Ec2:\n  strict_id: false\nssh_pwauth: no\nusers:\n- name: user1\n  sudo: ALL=(ALL) NOPASSWD:ALL\n  shell: /bin/bash\n  ssh_authorized_keys:\n  - ssh-rsa ABC..."
     },
     "description": "",
     "disks": [
       {
         "deviceName": "epdjv70ebov2********",
         "index": 0,
         "mode": "READ_WRITE",
         "type": "PERSISTENT"
       }
     ],
     "hostname": "compute-vm.ru-central1.internal",
     "id": "epdg9mn1pd9j********",
     "maintenanceEvent": "NONE",
     "name": "compute-vm",
     "networkInterfaces": [
       {
         "accessConfigs": [
           {
             "externalIp": "158.160.**.***",
             "type": "ONE_TO_ONE_NAT"
           }
         ],
         "forwardedIps": [],
         "ip": "10.12*.*.*",
         "mac": "d0:0d:10:4d:**:**",
         "network": "e2lb1da2dd9v********",
         "targetInstanceIps": []
       }
     ],
     "serviceAccounts": {},
     "tags": [],
     "vendor": {
       "cloudId": "b1gia87mbaom********",
       "environment": "ru-central1",
       "folderId": "b1g681qpemb4********",
       "identity": {
         "base64": "VPb...",
         "document": "{\"instanceId\":\"epdg9mn1pd9j********\",\"productCodes\":null,\"imageId\":\"fd8hp9las7k4********\",\"productIds\":[\"f2egeq0c2kd6********\"],\"createdAt\":\"2024-11-13T13:33:42Z\",\"version\":\"2023-03-01\"}",
         "dsa": "-----BEGIN PKCS7-----\nMI...\n-----END PKCS7-----\n",
         "rsa": "-----BEGIN PKCS7-----\nMI...-----END PKCS7-----\n"
       },
       "labels": {}
     },
     "virtualClock": {
       "driftToken": 0
     },
     "zone": "projects/b1g681qpemb4********/zones/ru-central1-b"
   }
   

   Сохраните значения полей id и vendor.folderId. Они потребуются для запроса списка привязок.

Получите список привязокПолучите список привязок

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

curl \
  --request GET \
  --url 'https://marketplace.api.cloud.yandex.net/marketplace/license-manager/v1/locks?folderId=<идентификатор_каталога>&resourceId=<идентификатор_ресурса>' \
  --header 'Authorization: Bearer <IAM-токен>' \
  --header 'Content-Type: application/json'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d '{
      "folderId": "<идентификатор_каталога>",
      "resourceId": "<идентификатор_ресурса>"
  }' \
  marketplace.api.cloud.yandex.net:443 yandex.cloud.marketplace.licensemanager.v1.LockService/List

Результат:

{
  "locks": [
    {
      "id": "enp0asmd9pr9********",
      "instanceId": "epdg9mn1pd9j********",
      "resourceId": "epdg9mn1pd9j********",
      "startTime": "2024-01-01T12:34:56.123456789Z",
      "endTime": "2024-01-01T13:34:56.123456789Z",
      "createdAt": "2024-01-01T12:34:56.123456789Z",
      "state": "LOCKED",
      "templateId": "enpbhhpl3vs5********"
    }
  ]
} 

Сохраните значения полей instanceId и resourceId. Они потребуются для привязки подписки к ресурсу.

Запросите привязку к ресурсуЗапросите привязку к ресурсу

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

curl \
  --request POST \
  --url 'https://marketplace.api.cloud.yandex.net/marketplace/license-manager/v1/locks/<идентификатор_инстанса>:ensure' \
  --header 'Authorization: Bearer <IAM-токен>' \
  --header 'Content-Type: application/json' \
  --data '{
      "resourceId": "<идентификатор_ресурса>"
  }'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d '{
      "instanceId": "<идентификатор_инстанса>",
      "resourceId": "<идентификатор_ресурса>"
  }' \
  marketplace.api.cloud.yandex.net:443 yandex.cloud.marketplace.licensemanager.v1.LockService/Ensure

Результат:

{
  "id": "e2371l9d5u8a********",
  "description": "lock ensured",
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.marketplace.licensemanager.v1.EnsureLockMetadata",
    "lockId": "enp0asmd9pr9********"
  },
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.marketplace.licensemanager.v1.Lock",
    "id": "enp0asmd9pr9********",
    "instanceId": "epdg9mn1pd9j********",
    "resourceId": "epdg9mn1pd9j********",
    "startTime": "2024-01-01T12:34:56.123456789Z",
    "endTime": "2024-01-01T13:34:56.123456789Z",
    "createdAt": "2024-01-01T12:34:56.123456789Z",
    "state": "LOCKED",
    "templateId": "enpbhhpl3vs5********"
  }
}

В результате сервис привяжет подписку к ресурсу. Если подписка уже привязана, сервис просто вернет подтверждение привязки.