API операций выполнения SaaS версии 2 в коммерческой платформе Майкрософт
В этой статье описывается версия 2 API операций выполнения SaaS.
Операции полезны для реагирования на все запросы, поступающие через веб-перехватчик в рамках действий ChangePlan, ChangeQuantity и Восстановления. Это позволяет принять или отклонить запрос по исправлению, который выполняется операция веб-перехватчика с успехом или сбоем, используя приведенные ниже API.
Это относится только к событиям веб-перехватчика, таким как ChangePlan, ChangeQuantity и Восстановление, которое требуется ACK. Никаких действий от независимого поставщика программного обеспечения (ISV) для обновления, приостановки и отмены подписки не требуется, так как они уведомляются только о событиях.
Список невыполненных операций
Получение списка операций, ожидающих выполнения, для указанной подписки SaaS. Издатель должен подтвердить возвращаемые операции, вызвав API исправления операции.
Get 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: недопустимый запрос: проверка не пройдена.
Код 403: запрещено. Токен авторизации является недействительным, не указан или истек срок его действия. Запрос пытается получить доступ к подписке SaaS для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера авторизации.
Эта ошибка часто свидетельствует о неправильном выполнении регистрации SaaS.
Код 404: не найдено. Подписка subscriptionId SaaS с не найдена.
Код 500: внутренняя ошибка сервера. Повторите вызов API. Если проблема сохраняется, обратитесь в службу поддержки корпорации Майкрософт.
Получение статуса операции
Этот API позволяет издателю отслеживать статус указанной асинхронной операции: Unsubscribe, ChangePlan или ChangeQuantity.
operationId для этого вызова API можно получить из значения, возвращаемого по расположению операции, вызову API получения ожидающих операций или по значению параметра <id>, полученному в вызове веб-перехватчика.
Get 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": ""
}
Код 403: запрещено. Токен авторизации является недействительным, не указан или истек срок его действия. Запрос пытается получить доступ к подписке SaaS для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера авторизации.
Эта ошибка часто свидетельствует о неправильном выполнении регистрации SaaS.
Код 404: не найдено.
- Подписка с
subscriptionIdней не найдена. - Операция с
operationIdне найдена.
Код 500: внутренняя ошибка сервера. Повторите вызов API. Если проблема сохраняется, обратитесь в службу поддержки корпорации Майкрософт.
Обновление статуса операции
Используйте этот API для обновления статуса ожидающей обработки операции, чтобы указать, выполнена ли операция успешно на стороне издателя.
operationId для этого вызова API можно получить из значения, возвращаемого по расположению операции, вызову API получения ожидающих операций или по значению параметра <id>, полученному в вызове веб-перехватчика.
Patch 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: вызов, сообщающий о выполнении операции на стороне партнера. Например, этот отклик может сообщать о завершении изменения количества рабочих мест или планов на стороне издателя.
Код: 403
- Запрещено. Маркер авторизации недоступен, недопустим или истек. Запрос может пытаться получить доступ к подписке, которая не принадлежит текущему издателю.
- Запрещено. Токен авторизации является недействительным, не указан или истек срок его действия. Запрос пытается получить доступ к подписке SaaS для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера авторизации.
Эта ошибка часто свидетельствует о неправильном выполнении регистрации SaaS.
Код 404: не найдено.
- Подписка с
subscriptionIdней не найдена. - Операция с
operationIdне найдена.
Код 409: конфликт. Например, уже выполнено более актуальное обновление.
Код 500: внутренняя ошибка сервера. Повторите вызов API. Если проблема сохраняется, обратитесь в службу поддержки корпорации Майкрософт.
Следующие шаги
- Дополнительные варианты предложений SaaS на коммерческой платформе см. в разделе API-интерфейсы службы оценки показателей коммерческой платформы.
- Ознакомьтесь с разделом Клиенты для различных языков программирования и примеры.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по