API подписки SaaS версии 2 на коммерческой платформе Майкрософт

  • Статья

В этой статье описывается версия 2 API подписки SaaS.

Разрешение приобретенной подписки

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

Когда клиент перенаправляется на URL-адрес целевой страницы партнера, токен идентификации клиента передается в качестве параметра токена в этом вызове URL-адреса. Ожидается, что партнер будет использовать этот токен и отправит запрос на его разрешение. Ответ API разрешения содержит идентификатор подписки SaaS и другие сведения для уникальной идентификации покупки. Маркер, предоставленный при вызове URL-адреса целевой страницы, действителен в течение 24 часов. Если срок действия маркера истек, рекомендуется предоставить пользователю следующее руководство.

"Не удалось идентифицировать эту покупку. Повторно откройте эту подписку SaaS в портал Azure или в Центре Администратор Microsoft 365 и снова выберите пункт "Настройка учетной записи" или "Управление учетной записью".

Вызов API разрешения возвращает сведения о подписке и состояние подписок SaaS во всех поддерживаемых состояниях.

Post https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>

Параметры запроса.

Параметр Значение
ApiVersion Используйте версию 2018-08-31.

Заголовки запроса:

Параметр Значение
content-type application/json
x-ms-requestid Уникальное строковое значение для отслеживания запроса клиента, желательно GUID. Если это значение не указано, он создается и предоставляется в заголовках ответа.
x-ms-correlationid Уникальное строковое значение для операции на стороне клиента. Этот параметр позволяет сопоставить все события клиентской операции с событиями на стороне сервера. Если это значение не указано, он создается и предоставляется в заголовках ответа.
authorization Уникальный токен доступа, идентифицирующий издателя, совершающего вызов API. Формат заключается в "Bearer <access_token>" том, когда значение маркера извлекается издателем, как описано в разделе "Получение маркера" на основе приложения Microsoft Entra.
x-ms-marketplace-token Параметр токена идентификации покупки для разрешения. Токен передается при вызове URL-адреса целевой страницы, когда клиент перенаправляется на веб-сайт партнера SaaS (например, https://contoso.com/signup?token=<token><authorization_token>).

Значение маркера , закодированное, является частью URL-адреса целевой страницы, поэтому его необходимо декодировать перед использованием в качестве параметра в этом вызове API.

Ниже приведен пример кодированной строки в URL-адресе: contoso.com/signup?token=ab%2Bcd%2Fef, где токен имеет значение ab%2Bcd%2Fef. Один и тот же маркер декодирован: Ab+cd/ef

Коды отклика:

Код 200: возвращает уникальные идентификаторы подписки SaaS с учетом предоставленного x-ms-marketplace-token.

Пример текста отклика:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "subscriptionName": "Contoso Cloud Solution", // SaaS subscription name
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased offer's plan ID
  "quantity": 20, // number of purchased seats, might be empty if the plan is not per seat
  "subscription": { // full SaaS subscription details, see Get Subscription APIs response body for full description
    "id": "<guid>",
    "publisherId": "contoso",
    "offerId": "offer1",
    "name": "Contoso Cloud Solution",
    "saasSubscriptionStatus": " PendingFulfillmentStart ",
    "beneficiary": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "purchaser": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "planId": "silver",
    "term": {
      "termUnit": "P1M",
      "startDate": "2022-03-07T00:00:00Z", //This field is only available after the saas subscription is active.
      "endDate": "2022-04-06T00:00:00Z" //This field is only available after the saas subscription is active.
    },
      "autoRenew": true/false,
    "isTest": true/false,
    "isFreeTrial": false,
    "allowedCustomerOperations": <CSP purchases>["Read"] <All Others> ["Delete", "Update", "Read"],
      "sandboxType": "None",
      "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
      "quantity": 5,
    "sessionMode": "None"
  }
}

Код 400: недопустимый запрос. x-ms-marketplace-token отсутствует, имеет недопустимый формат, недействителен или срок действия истек.

Код 403: запрещено. Токен авторизации является недействительным, не указан или истек срок его действия. Запрос пытается получить доступ к подписке SaaS для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера авторизации.

Эта ошибка часто свидетельствует о неправильном выполнении регистрации SaaS.

Код 500: внутренняя ошибка сервера. Повторите вызов API. Если проблема сохраняется, обратитесь в службу поддержки корпорации Майкрософт.

Активация подписки

После настройки учетной записи SaaS для конечного пользователя издатель должен вызвать API активации подписки на стороне Майкрософт. Клиент не оплачивается, если этот вызов API не выполнен успешно.

Post https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>

Параметры запроса.

Параметр Значение
ApiVersion Используйте версию 2018-08-31.
subscriptionId Уникальный идентификатор приобретенной подписки SaaS. Этот идентификатор получен после разрешения токена авторизации коммерческой платформы с помощью API-интерфейса разрешения.

Заголовки запроса:

Параметр Значение
content-type application/json
x-ms-requestid Уникальное строковое значение для отслеживания запроса клиента, желательно GUID. Если это значение не указано, он создается и предоставляется в заголовках ответа.
x-ms-correlationid Уникальное строковое значение для операции на стороне клиента. Эта строка сопоставляет все события из операции клиента с событиями на стороне сервера. Если это значение не указано, он создается и предоставляется в заголовках ответа.
authorization Уникальный токен доступа, идентифицирующий издателя, совершающего вызов API. Формат заключается в "Bearer <access_token>" том, когда значение маркера извлекается издателем, как описано в разделе "Получение маркера" на основе приложения Microsoft Entra.

Коды отклика:

Код: 200 Запрос на обновление подписки и пометку как "Подписка" получен. Независимые поставщики программного обеспечения (независимые поставщики программного обеспечения) могут проверка для состояния подписки через несколько минут (чтение для операции Получения состояния подписки проверка). Это дает окончательный ответ на то, была ли подписка успешно обновлена. Сбой подписки автоматически отправляет веб-перехватчик "Отмена подписки".

Для этого вызова нет текста ответа.

Код 400: недопустимый запрос: проверка не пройдена.

  • Подписка SaaS находится в приостановленном состоянии.

Код 403: запрещено. Токен авторизации является недействительным, не указан или истек срок его действия. Запрос пытается получить доступ к подписке SaaS для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера авторизации.

Эта ошибка часто свидетельствует о неправильном выполнении регистрации SaaS.

Код 404: не найдено. Подписка SaaS имеет статус Подписка отменена.

Код 500: внутренняя ошибка сервера. Повторите вызов API. Если проблема сохраняется, обратитесь в службу поддержки корпорации Майкрософт.

Получение списка всех подписок

Этот API получает список всех приобретенных подписок SaaS для всех предложений, публикуемых издателем на коммерческой платформе. Возвращаются подписки SaaS во всех возможных состояниях. Отмена подписки SaaS также возвращается, так как эта информация не удаляется на стороне Майкрософт.

API возвращает результаты с разбивкой на страницы (100 результатов на странице).

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>

Параметры запроса.

Параметр Значение
ApiVersion Используйте версию 2018-08-31.
continuationToken Необязательный параметр. Чтобы получить первую страницу результатов, оставьте это поле пустым. Используйте значение, возвращаемое в параметре @nextLink, для получения следующей страницы.

Заголовки запроса:

Параметр Значение
content-type application/json
x-ms-requestid Уникальное строковое значение для отслеживания запроса клиента, желательно GUID. Если это значение не указано, он создается и предоставляется в заголовках ответа.
x-ms-correlationid Уникальное строковое значение для операции на стороне клиента. Этот параметр позволяет сопоставить все события клиентской операции с событиями на стороне сервера. Если это значение не указано, он создается и предоставляется в заголовках ответа.
authorization Уникальный токен доступа, идентифицирующий издателя, совершающего вызов API. Формат заключается в "Bearer <access_token>" том, когда значение маркера извлекается издателем, как описано в разделе "Получение маркера" на основе приложения Microsoft Entra.

Коды отклика:

Код 200: возвращает список всех существующих подписок для всех предложений, созданных этим издателем, с учетом токена авторизации издателя.

Пример текста отклика:

{
  "subscriptions": [
    {
      "id": "<guid>", // purchased SaaS subscription ID
      "name": "Contoso Cloud Solution", // SaaS subscription name
      "publisherId": "contoso", // publisher ID
      "offerId": "offer1", // purchased offer ID
      "planId": "silver", // purchased plan ID
      "quantity": 10, // purchased amount of seats, is empty if plan is not per seat
      "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription was purchased.
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": { // email address, user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) purchase
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": { // The period for which the subscription was purchased.
        "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
        "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
        "termUnit": "P1M" // where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values
      },
      "autoRenew": true,
      "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sessionMode": "None", // not relevant
      "isFreeTrial": true, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. (Optional field -– if not returned, the value is false.)
      "isTest": false, // not relevant
      "sandboxType": "None", // not relevant
      "saasSubscriptionStatus": "Subscribed" // Indicates the status of the operation. Can be one of the following: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
    },
    // next SaaS subscription details, might be a different offer
    {
      "id": "<guid1>",
      "name": "Contoso Cloud Solution1",
      "publisherId": "contoso",
      "offerId": "offer2",
      "planId": "gold",
      "quantity": "",
      "beneficiary": {
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": {
        "emailId": "purchase@csp.com ",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": {
        "startDate": "2019-05-31", /This field is only available after the saas subscription is active.
        "endDate": "2020-04-30",  //This field is only available after the saas subscription is active.
        "termUnit": "P1Y"
      },
      "autoRenew": false,
      "allowedCustomerOperations": ["Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Suspended"
    }
  ],
  "@nextLink": "https:// https://marketplaceapi.microsoft.com/api/saas/subscriptions/?continuationToken=%5b%7b%22token%22%3a%22%2bRID%3a%7eYeUDAIahsn22AAAAAAAAAA%3d%3d%23RT%3a1%23TRC%3a2%23ISV%3a1%23FPC%3aAgEAAAAQALEAwP8zQP9%2fFwD%2b%2f2FC%2fwc%3d%22%2c%22range%22%3a%7b%22min%22%3a%22%22%2c%22max%22%3a%2205C1C9CD673398%22%7d%7d%5d&api-version=2018-08-31" // url that contains continuation token to retrieve next page of the SaaS subscriptions list, if empty or absent, this is the last page. ISV can use this url as is to retrieve the next page or extract the value of continuation token from this url.
}

Если для этого издателя не найдены приобретенные подписки SaaS, возвращается пустой текст отклика.

Код 403: запрещено. Токен авторизации недоступен, недействителен или истек срок его действия.

Эта ошибка часто свидетельствует о неправильном выполнении регистрации SaaS.

Код 500: внутренняя ошибка сервера. Повторите вызов API. Если проблема сохраняется, обратитесь в службу поддержки корпорации Майкрософт.

Получение подписки

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

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Параметры запроса.

Параметр Значение
ApiVersion Используйте версию 2018-08-31.
subscriptionId Уникальный идентификатор приобретенной подписки SaaS. Этот идентификатор получен после разрешения токена авторизации коммерческой платформы с помощью API-интерфейса разрешения.

Заголовки запроса:

Параметр Значение
content-type application/json
x-ms-requestid Уникальное строковое значение для отслеживания запроса клиента, желательно GUID. Если это значение не указано, он создается и предоставляется в заголовках ответа.
x-ms-correlationid Уникальное строковое значение для операции на стороне клиента. Этот параметр позволяет сопоставить все события клиентской операции с событиями на стороне сервера. Если это значение не указано, он создается и предоставляется в заголовках ответа.
authorization Уникальный токен доступа, идентифицирующий издателя, совершающего вызов API. Формат заключается в "Bearer <access_token>" том, когда значение маркера извлекается издателем, как описано в разделе "Получение маркера" на основе приложения Microsoft Entra.

Коды отклика:

Код 200: возвращает сведения о подписке SaaS с учетом указанного subscriptionId.

Пример текста отклика:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "name": "Contoso Cloud Solution", // SaaS subscription name
  "publisherId": "contoso", // publisher ID
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased plan ID
  "quantity": 10, // purchased amount of seats is empty if plan is not per seat
  "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription is purchased.
    "emailId": "test@contoso.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "purchaser": { // email address ,user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) scenario
    "emailId": "test@test.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
  "sessionMode": "None", // not relevant
  "isFreeTrial": false, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. Optional field – if not returned the value is false.
  "autoRenew": true,
  "isTest": false, // not relevant
  "sandboxType": "None", // not relevant
  "created": "2022-03-01T22:59:45.5468572Z",
     "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
  "saasSubscriptionStatus": " Subscribed ", // Indicates the status of the operation: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
  "term": { // the period for which the subscription was purchased
    "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
    "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
    "termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
  }
}

Код 403: запрещено. Токен авторизации является недействительным, не указан или истек срок его действия. Запрос пытается получить доступ к подписке SaaS для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера авторизации.

Эта ошибка часто свидетельствует о неправильном выполнении регистрации SaaS.

Код 404: не найдено. Не удается найти подписку SaaS с указанными данными subscriptionId.

Код 500: внутренняя ошибка сервера. Повторите вызов API. Если проблема сохраняется, обратитесь в службу поддержки корпорации Майкрософт.

Список доступных планов

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

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

Этот API также извлекает связанный с ним идентификатор активного частного предложения (при вызове API с фильтром planId). Вызов API с фильтром planId отображает идентификаторы GUID активного частного предложения в тексте ответа в узле sourceOffers. Идентификатор плана, переданный в параметре фильтра, должен соответствовать идентификатору плана, приобретенному клиенту.

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>

Параметры запроса.

Параметр Значение
ApiVersion Используйте версию 2018-08-31.
subscriptionId Уникальный идентификатор приобретенной подписки SaaS. Этот идентификатор получен после разрешения токена авторизации коммерческой платформы с помощью API-интерфейса разрешения.
planId (Optional) Идентификатор плана определенного плана, который требуется получить. Это необязательно, и если игнорируется, возвращает все планы.

Заголовки запроса:

Параметр Значение
content-type application/json
x-ms-requestid Уникальное строковое значение для отслеживания запроса клиента, желательно GUID. Если это значение не указано, он создается и предоставляется в заголовках ответа.
x-ms-correlationid Уникальное строковое значение для операции на стороне клиента. Этот параметр позволяет сопоставить все события клиентской операции с событиями на стороне сервера. Если это значение не указано, он создается и предоставляется в заголовках ответа.
authorization Уникальный токен доступа, идентифицирующий издателя, совершающего вызов API. Формат заключается в "Bearer <access_token>" том, когда значение маркера извлекается издателем, как описано в разделе "Получение маркера" на основе приложения Microsoft Entra.

Коды отклика:

Код 200: возвращает список всех доступных планов для существующей подписки SaaS, включая ранее приобретенный план.

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

Пример текста отклика:

{
  "plans": [
    {
      "planId": "Platinum001",
      "displayName": "plan display name",
      "isPrivate": true, //returns true for private plans and customized plans created within a private offer.
      "description": "plan description",
      "minQuantity": 5,
      "maxQuantity": 100,
      "hasFreeTrials": false,
      "isPricePerSeat": true,
      "isStopSell": false,
      "market": "US",
      "planComponents": {
        "recurrentBillingTerms": [
          {
            "currency": "USD",
            "price": 1,
            "termUnit": "P1M",
            "termDescription": "term description",
            "meteredQuantityIncluded": [
              {
                "dimensionId": "Dimension001",
                "units": "Unit001"
              }
            ]
          }
        ],
        "meteringDimensions": [
          {
            "id": "MeteringDimension001",
            "currency": "USD",
            "pricePerUnit": 1,
            "unitOfMeasure": "unitOfMeasure001",
            "displayName": "unit of measure display name"
          }
        ]
      },
      "sourceOffers": [ //sourceOffers is returned when planId is passed as filter parameter (note that this is the plan that customer has purchased).
        {
          "externalId": "<guid>" //private offer id, returned when purchase is made through private offer.
        }
      ]
    }
  ]
}

Код: 404 не найден. subscriptionId не найден.

Код 403: запрещено. Токен авторизации является недействительным, не указан или истек срок его действия. Запрос может пытаться получить доступ к подписке SaaS для предложения, который отменяется или публикуется с другим идентификатором приложения Microsoft Entra, который используется для создания маркера авторизации.

Эта ошибка часто свидетельствует о неправильном выполнении регистрации SaaS.

Код 500: внутренняя ошибка сервера. Повторите вызов API. Если проблема сохраняется, обратитесь в службу поддержки корпорации Майкрософт.

Изменение плана в подписке

Используйте этот API, чтобы обновить существующий план, приобретенный для подписки SaaS, на новый план (частный или общедоступный). Издатель должен вызвать этот API при изменении плана для подписки SaaS, приобретенной на коммерческой платформе, на стороне издателя.

Этот API можно вызвать только для подписок со статусом Активно. Вместо текущего плана можно выбрать любой другой доступный план (частный или общедоступный), кроме текущего. Для частных планов необходимо определить арендатор клиента в Центре партнеров как часть аудитории плана.

Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Параметры запроса.

Параметр Значение
ApiVersion Используйте версию 2018-08-31.
subscriptionId Уникальный идентификатор приобретенной подписки SaaS. Этот идентификатор получен после разрешения токена авторизации коммерческой платформы с помощью API-интерфейса разрешения.

Заголовки запроса:

Параметр Значение
content-type application/json
x-ms-requestid Уникальное строковое значение для отслеживания запроса клиента, желательно GUID. Если это значение не указано, он создается и предоставляется в заголовках ответа.
x-ms-correlationid Уникальное строковое значение для операции на стороне клиента. Этот параметр позволяет сопоставить все события клиентской операции с событиями на стороне сервера. Если это значение не указано, он создается и предоставляется в заголовках ответа.
authorization Уникальный токен доступа, идентифицирующий издателя, совершающего вызов API. Формат заключается в "Bearer <access_token>" том, когда значение маркера извлекается издателем, как описано в разделе "Получение маркера" на основе приложения Microsoft Entra.

Пример полезных данных запроса:

{
  "planId": "gold" // the ID of the new plan to be purchased
}

Коды отклика:

Код 202: запрос на изменение плана принят и обрабатывается асинхронно. Предполагается, что партнер опрашивает URL-адрес расположения операции, чтобы определить, выполнен ли запрос на изменение плана успешно. Опрос должен выполняться раз в несколько секунд до отображения окончательного статуса Сбой, Успешно или Конфликт для операции. Окончательный статус операции должен возвращаться быстро, однако в некоторых случаях это может занять несколько минут.

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

Заголовки откликов:

Параметр Значение
Operation-Location URL-адрес для получения статуса операции. Например: https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31

Код 400: недопустимый запрос: проверка не пройдена.

  • Новый план не существует или недоступен для этой конкретной подписки SaaS.
  • Новый план совпадает с текущим планом.
  • Подписка SaaS не имеет статуса Подписка оформлена.
  • Операция обновления для подписки SaaS не включена в allowedCustomerOperations.

Код 403: запрещено. Токен авторизации является недействительным, не указан или истек срок его действия. Запрос пытается получить доступ к подписке SaaS для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера авторизации.

Эта ошибка часто свидетельствует о неправильном выполнении регистрации SaaS.

Код 404: не найдено. Подписка SaaS с параметром subscriptionId не найдена.

Код 500: внутренняя ошибка сервера. Повторите вызов API. Если проблема сохраняется, обратитесь в службу поддержки корпорации Майкрософт.

Примечание.

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

Этот API можно вызвать только после явного утверждения изменений конечным пользователем.

Изменение количества рабочих мест в подписке SaaS

Этот API используется для обновления (увеличения или уменьшения) количества рабочих мест, приобретенных в рамках подписки SaaS. Издатель должен вызвать этот API при изменении на стороне издателя количества рабочих мест для подписки SaaS, созданной на коммерческой платформе.

Количество мест не может превышать допустимое количество в текущем плане. В противном случае перед изменением количества рабочих мест издатель должен изменить план.

Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Параметры запроса.

Параметр Значение
ApiVersion Используйте версию 2018-08-31.
subscriptionId Уникальный идентификатор приобретенной подписки SaaS. Этот идентификатор получен после разрешения токена авторизации коммерческой платформы с помощью API-интерфейса разрешения.

Заголовки запроса:

Параметр Значение
content-type application/json
x-ms-requestid Уникальное строковое значение для отслеживания запроса клиента, желательно GUID. Если это значение не указано, он создается и предоставляется в заголовках ответа.
x-ms-correlationid Уникальное строковое значение для операции на стороне клиента. Этот параметр позволяет сопоставить все события клиентской операции с событиями на стороне сервера. Если это значение не указано, он создается и предоставляется в заголовках ответа.
authorization Уникальный токен доступа, идентифицирующий издателя, совершающего вызов API. Формат заключается в "Bearer <access_token>" том, когда значение маркера извлекается издателем, как описано в разделе "Получение маркера" на основе приложения Microsoft Entra.

Пример полезных данных запроса:

{
  "quantity": 5 // the new amount of seats to be purchased
}

Коды отклика:

Код 202: запрос на изменение количества рабочих мест принят и обрабатывается асинхронно. Предполагается, что партнер опрашивает URL-адрес расположения операции, чтобы определить, выполнен ли запрос на изменение количества рабочих мест успешно. Опрос должен выполняться раз в несколько секунд до отображения окончательного статуса Сбой, Успешно или Конфликт для операции. Окончательный статус операции должен возвращаться быстро, однако в некоторых случаях это может занять несколько минут.

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

Заголовки откликов:

Параметр Значение
Operation-Location Ссылка на ресурс для получения статуса операции. Например, https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Код 400: недопустимый запрос: проверка не пройдена.

  • Новое количество больше или меньше текущего ограничения для плана.
  • Не указано новое количество.
  • Новое количество совпадает с текущим количеством.
  • Подписка SaaS не имеет статуса "Подписка оформлена".
  • Операция обновления для подписки SaaS не включена в allowedCustomerOperations.

Код 403: запрещено. Токен авторизации является недействительным, не указан или истек срок его действия. Запрос пытается получить доступ к подписке, которая не принадлежит текущему издателю.

Эта ошибка часто свидетельствует о неправильном выполнении регистрации SaaS.

Код 404: не найдено. Подписка SaaS с параметром subscriptionId не найдена.

Код 500: внутренняя ошибка сервера. Повторите вызов API. Если проблема сохраняется, обратитесь в службу поддержки корпорации Майкрософт.

Примечание.

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

Этот API можно вызвать только после явного утверждения изменений конечным пользователем.

Отмена подписки

Используйте этот API, чтобы отменить указанную подписку SaaS. Издателю необязательно использовать этот API, и мы рекомендуем перенаправлять клиентов на коммерческую платформу для отмены подписок SaaS.

Издателю нужно вызвать этот API, если он решит отменить подписку SaaS, приобретенную на коммерческой платформе, на стороне издателя. После завершения этого вызова состояние подписки становится отменой подписки на стороне Майкрософт.

Клиент не оплачивается, если подписка отменена в течение 72 часов после покупки.

Клиент оплачивается, если подписка отменена после предыдущего льготного периода. Клиент теряет доступ к подписке SaaS на стороне Майкрософт сразу после отмены.

Delete https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Параметры запроса.

Параметр Значение
ApiVersion Используйте версию 2018-08-31.
subscriptionId Уникальный идентификатор приобретенной подписки SaaS. Этот идентификатор получен после разрешения токена авторизации коммерческой платформы с помощью API-интерфейса разрешения.

Заголовки запроса:

Параметр Значение
content-type application/json
x-ms-requestid Уникальное строковое значение для отслеживания запроса клиента, желательно GUID. Если это значение не указано, он создается и предоставляется в заголовках ответа.
x-ms-correlationid Уникальное строковое значение для операции на стороне клиента. Этот параметр позволяет сопоставить все события клиентской операции с событиями на стороне сервера. Если это значение не указано, он создается и предоставляется в заголовках ответа.
authorization Уникальный токен доступа, идентифицирующий издателя, совершающего вызов API. Формат заключается в "Bearer <access_token>" том, когда значение маркера извлекается издателем, как описано в разделе "Получение маркера" на основе приложения Microsoft Entra.

Коды отклика:

Код 202: запрос на отмену подписки принят и обрабатывается асинхронно. Предполагается, что партнер опрашивает URL-адрес расположения операции, чтобы определить, выполнен ли запрос успешно. Опрос должен выполняться раз в несколько секунд до отображения окончательного статуса Сбой, Успешно или Конфликт для операции. Окончательный статус операции должен возвращаться быстро, однако в некоторых случаях это может занять несколько минут.

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

Код: 200 Подписка уже находится в состоянии отмены подписки.

Заголовки откликов:

Параметр Значение
Operation-Location Ссылка на ресурс для получения статуса операции. Например, https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Код 400: недопустимый запрос. Запрос Delete не включен в список allowedCustomerOperations для этой подписки SaaS.

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

Эта ошибка часто свидетельствует о неправильном выполнении регистрации SaaS.

Код 404: не найдено. Подписка SaaS с параметром subscriptionId не найдена.

Код: 409

Удалить невозможно, так как подписка заблокирована из-за ожидающих операций.

Код 500: внутренняя ошибка сервера. Повторите вызов API. Если проблема сохраняется, обратитесь в службу поддержки корпорации Майкрософт.

Следующие шаги