API операций выполнения SaaS версии 2 в коммерческой платформе Майкрософт
Заметка
Чтобы иметь возможность вызывать API операций выполнения SaaS, необходимо создать маркер авторизации издателя с помощью правильного идентификатора ресурса. Узнайте, как получить маркер авторизации издателя
В этой статье описывается версия 2 API операций выполнения SaaS.
Операции полезны для реагирования на все запросы, поступающие через веб-перехватчик в рамках действий ChangePlan, ChangeQuantity и Восстановления. Это позволяет принять или отклонить запрос по исправлению, который выполняется операция веб-перехватчика с успехом или сбоем, используя приведенные ниже API.
Это относится только к событиям веб-перехватчика, таким как ChangePlan, ChangeQuantity и Восстановление, которое требуется ACK. Никаких действий от независимого поставщика программного обеспечения (ISV) для обновления, приостановки и отмены подписки не требуется, так как они уведомляются только о событиях.
Вывод списка невыполненных операций
Получение списка ожидающих операций для указанной подписки SaaS. Издатель должен подтвердить возвращенные операции, вызвав API исправлений операции.
Получение https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?api-version=<ApiVersion>
параметры запроса :
| Параметр | Ценность |
|---|---|
ApiVersion |
Используйте 2018-08-31. |
subscriptionId |
Уникальный идентификатор приобретенной подписки SaaS. Этот идентификатор получается после разрешения маркера авторизации коммерческой платформы с помощью API разрешения. |
заголовки запросов :
| Параметр | Ценность |
|---|---|
content-type |
application/json |
x-ms-requestid |
Уникальное строковое значение для отслеживания запроса от клиента, предпочтительно guid. Если это значение не указано, он создается и предоставляется в заголовках ответа. |
x-ms-correlationid |
Уникальное строковое значение для операции на клиенте. Этот параметр сопоставляет все события из операции клиента с событиями на стороне сервера. Если это значение не указано, он создается и предоставляется в заголовках ответа. |
authorization |
Формат "Bearer <access_token>", когда значение маркера извлекается издателем, как описано в получение маркера на основеприложения Microsoft Entra. |
коды ответа :
Код: 200 Возвращает ожидающие операции с указанной подпиской SaaS.
Пример полезных данных ответа :
{
"operations": [
{
"id": "<guid>", //Operation ID, should be provided in the operations patch API call
"activityId": "<guid>", //not relevant
"subscriptionId": "<guid>", // subscriptionId of the SaaS subscription that is being reinstated
"offerId": "offer1", // purchased offer ID
"publisherId": "contoso",
"planId": "silver", // purchased plan ID
"quantity": 20, // purchased amount of seats, will be empty is not relevant
"action": "Reinstate",
"timeStamp": "2018-12-01T00:00:00", // UTC
"status": "InProgress" // the only status that can be returned in this case
}
]
}
Возвращает пустой json, если операции не ожидаются.
Код: 400 Недопустимый запрос: сбои проверки.
Код: 401 Несанкционированный. Маркер авторизации недопустим или истек. Запрос пытается получить доступ к подписке SaaS для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера проверки подлинности.
Код: 403 Запрещено. Маркер авторизации недопустим, не предоставлен или предоставлен с недостаточными разрешениями. Убедитесь, что укажите допустимый маркер авторизации.
Эта ошибка часто является симптомом неправильного выполнения регистрации SaaS.
Код: 404 Не найден. Подписка SaaS с subscriptionId не найдена.
Код: ошибка внутреннего сервера 500. Повторите вызов API. Если ошибка не исчезнет, обратитесь в службу поддержки Майкрософт .
Получение состояния операции
Этот API позволяет издателю отслеживать состояние указанной асинхронной операции: отменить подписку, ChangePlanили ChangeQuantity.
operationId для этого вызова API можно получить из значения, возвращаемого Operation-Location, вызова ожидающего api операций или значения параметра <id>, полученного в вызове веб-перехватчика.
Получение https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
параметры запроса :
| Параметр | Ценность |
|---|---|
ApiVersion |
Используйте 2018-08-31. |
subscriptionId |
Уникальный идентификатор приобретенной подписки SaaS. Этот идентификатор получается после разрешения маркера авторизации коммерческой платформы с помощью API разрешения. |
operationId |
Уникальный идентификатор извлекаемой операции. |
заголовки запросов :
| Параметр | Ценность |
|---|---|
content-type |
application/json |
x-ms-requestid |
Уникальное строковое значение для отслеживания запроса от клиента, предпочтительно guid. Если это значение не указано, он создается и предоставляется в заголовках ответа. |
x-ms-correlationid |
Уникальное строковое значение для операции на клиенте. Этот параметр сопоставляет все события из операции клиента с событиями на стороне сервера. Если это значение не указано, он создается и предоставляется в заголовках ответа. |
authorization |
Уникальный маркер доступа, определяющий издателя, выполняющего этот вызов API. Формат "Bearer <access_token>", когда значение маркера извлекается издателем, как описано в получение маркера на основеприложения Microsoft Entra. |
коды ответа :
Код: 200 Возвращает сведения для указанной операции SaaS.
Пример полезных данных ответа :
Response body:
{
"id ": "<guid>", //Operation ID, should be provided in the patch operation API call
"activityId": "<guid>", //not relevant
"subscriptionId": "<guid>", // subscriptionId of the SaaS subscription for which this operation is relevant
"offerId": "offer1", // purchased offer ID
"publisherId": "contoso",
"planId": "silver", // purchased plan ID
"quantity": 20, // purchased amount of seats
"action": "ChangePlan", // Can be ChangePlan, ChangeQuantity or Reinstate
"timeStamp": "2018-12-01T00:00:00", // UTC
"status": "InProgress", // Possible values: NotStarted, InProgress, Failed, Succeeded, Conflict (new quantity / plan is the same as existing)
"errorStatusCode": "",
"errorMessage": ""
}
Код: 401 Несанкционированный. Маркер авторизации недопустим или истек. Запрос пытается получить доступ к подписке SaaS для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера проверки подлинности.
Код: 403 Запрещено. Маркер авторизации недопустим, не предоставлен или предоставлен с недостаточными разрешениями. Убедитесь, что укажите допустимый маркер авторизации.
Эта ошибка часто является симптомом неправильного выполнения регистрации SaaS.
Код: 404 Не найден.
- Подписка с
subscriptionIdне найдена. - Операция с
operationIdне найдена.
Код: ошибка внутреннего сервера 500. Повторите вызов API. Если ошибка не исчезнет, обратитесь в службу поддержки Майкрософт .
Обновление состояния операции
Используйте этот API для обновления состояния ожидающей операции, чтобы указать успешность или сбой операции на стороне издателя.
operationId для этого вызова API можно получить из значения, возвращаемого Operation-Location, вызова ожидающего api операций или значения параметра <id>, полученного в вызове веб-перехватчика.
Исправление https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
параметры запроса :
| Параметр | Ценность |
|---|---|
ApiVersion |
Используйте 2018-08-31. |
subscriptionId |
Уникальный идентификатор приобретенной подписки SaaS. Этот идентификатор получается после разрешения маркера авторизации коммерческой платформы с помощью API разрешения. |
operationId |
Уникальный идентификатор выполняемой операции. |
заголовки запросов :
| Параметр | Ценность |
|---|---|
content-type |
application/json |
x-ms-requestid |
Уникальное строковое значение для отслеживания запроса от клиента, предпочтительно guid. Если это значение не указано, он создается и предоставляется в заголовках ответа. |
x-ms-correlationid |
Уникальное строковое значение для операции на клиенте. Этот параметр сопоставляет все события из операции клиента с событиями на стороне сервера. Если это значение не указано, он создается и предоставляется в заголовках ответа. |
authorization |
Уникальный маркер доступа, определяющий издателя, выполняющего этот вызов API. Формат "Bearer <access_token>", когда значение маркера извлекается издателем, как описано в получение маркера на основеприложения Microsoft Entra. |
Пример полезных данных запроса :
{
"status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}
коды ответа :
Код: 200 Вызов для информирования о завершении операции на стороне партнера. Например, этот ответ может сигнализировать о завершении смены мест или планов на стороне издателя.
Код: 401 Несанкционированный. Маркер авторизации недопустим или истек. Запрос пытается получить доступ к подписке SaaS для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера проверки подлинности.
Код: 403 Запрещено. Маркер авторизации недопустим, не предоставлен или предоставлен с недостаточными разрешениями. Убедитесь, что укажите допустимый маркер авторизации.
Эта ошибка часто является симптомом неправильного выполнения регистрации SaaS.
Код: 404 Не найден.
- Подписка с
subscriptionIdне найдена. - Операция с
operationIdне найдена.
Код: конфликт 409. Например, более новое обновление уже выполнено.
Код: ошибка внутреннего сервера 500. Повторите вызов API. Если ошибка не исчезнет, обратитесь в службу поддержки Майкрософт .
Связанное содержимое
- Дополнительные возможности предложений SaaS на коммерческой платформе см. в API-интерфейсов службы измерения коммерческой платформы.
- Просмотрите и используйте клиенты для различных языков программирования и примеров.