Поделиться через

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

  • Статья

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

Заметка

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

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

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

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

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

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

Запись 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 отсутствует, неправильно сформирована, недопустимая или истекла.

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

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

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

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

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

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

Запись 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 находится в состоянии Приостановлено.

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

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

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

Код: 404 Не найден. Подписка SaaS находится в состоянии отмены подписки.

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

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

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

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

Получение 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, возвращается пустой текст ответа.

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

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

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

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

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

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

Получение 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.
  }
}

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

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

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

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

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

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

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

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

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

Получение 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 не найден.

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

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

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

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

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

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

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

Исправление 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, чтобы определить успешность или сбой запроса плана изменений. Опрос должен выполняться каждые несколько секунд до получения окончательного состояния не удалось, Успешноили Конфликт для операции. Состояние окончательной операции должно быть возвращено быстро, но в некоторых случаях может занять несколько минут.

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

заголовки ответа :

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

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

  • Запрошенный план не найден или план недоступен для пользователя.
  • Запрошенный план совпадает с подписанным планом.
  • Состояние подписки SaaS не подписки.
  • Обновляемая подписка SaaS приобретается поставщиком облачных решений (CSP). Для выполнения этого действия необходимо работать с поставщиком CSP.

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

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

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

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

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

Заметка

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

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

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

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

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

Исправление 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, чтобы определить успешность или сбой запроса на изменение количества. Опрос должен выполняться каждые несколько секунд до получения окончательного состояния не удалось, Успешноили Конфликт для операции. Состояние последней операции должно быть возвращено быстро, но в некоторых случаях может занять несколько минут.

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

заголовки ответа :

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

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

  • Новое количество не находится в допустимом диапазоне.
  • Новое количество отсутствует или 0.
  • Новое количество совпадает с текущим количеством.
  • Состояние подписки SaaS не подписано.
  • Обновляемая подписка SaaS приобретается поставщиком облачных решений (CSP). Для выполнения этого действия необходимо работать с поставщиком CSP.

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

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

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

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

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

Заметка

Одновременно можно изменить только план или количество.

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

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

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

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

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

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

Удаление 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-адрес Operation-Location, чтобы определить успешность или сбой этого запроса. Опрос должен выполняться каждые несколько секунд до получения окончательного состояния не удалось, Успешноили Конфликт для операции. Состояние последней операции должно быть возвращено быстро, но в некоторых случаях может занять несколько минут.

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

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

заголовки ответа :

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

Код: 400 Недопустимый запрос. Удаление не находится в списке allowedCustomerOperations для этой подписки SaaS.

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

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

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

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

Код: 409

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

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

Связанное содержимое