Обзор API отправки частных предложений
Частные предложения позволяют издателям и клиентам выполнять транзакции одного или нескольких продуктов в Azure Marketplace, создавая цены с привязкой времени с настраиваемыми условиями. API отправки частных предложений позволяют издателям программно создавать частные предложения и управлять ими для клиентов и /или партнеров CSP. Этот API использует идентификатор Microsoft Entra для проверки подлинности вызовов из приложения или службы.
Существует три основных типа частных предложений, доступных в Центре партнеров и поддерживаемых API отправки частного предложения:
- IsV для частного предложения клиента — также называется частным предложением клиента в Центре партнеров. Это настраиваемая сделка между isV и конкретным клиентом с настраиваемыми условиями и ценами на определенный продукт в Azure Marketplace. Узнайте больше о поставщиках программного обеспечения для частного предложения клиента.
- Частное предложение партнера CSP — также называется частным предложением партнеров CSP в Центре партнеров партнеров. Этот тип частного предложения позволяет поставщику программного обеспечения указать ограниченное время маржи, чтобы создать оптовую цену для своего партнера CSP. Узнайте больше о частном предложении поставщика программного обеспечения для CSP.
- Многопартийное частное предложение (MPO) — настраиваемая сделка, настраиваемая поставщиком программного обеспечения и предпочтительным партнером канала конкретного клиента с настраиваемыми условиями и ценами на определенные продукты в Azure Marketplace. Поставщик программного обеспечения определяет скидку по оптовой цене, доступной партнеру канала, а затем добавить разметку поверх оптовой цены, чтобы прибыть на окончательную цену клиента и представить клиенту предложение для принятия и покупки. Принятие и покупка MPO следует тому же потоку, что и isV для частных предложений клиента. Дополнительные сведения о многопартийном частном предложении.
Терминология
- Источник MPO — MPO — это совместная работа между поставщиком программного обеспечения и партнером канала по той же пользовательской сделке для конкретного клиента, сторона, которая сначала создает MPO, назначается "источником" предложения, как правило, поставщик программного обеспечения продуктов, включенных в MPO. Для любого заданного MPO может быть только один источник.
- Продавец MPO — партнер канала, который готовит предложение с конечной ценой клиента и представляет предложение клиенту является продавцом MPO. Для любого конкретного MPO может быть только один продавец.
- Продукт — одна единица, представляющая предложение в Azure Marketplace. Существует один продукт на страницу описания.
- План — отдельная версия определенного продукта. Для данного продукта может быть несколько планов, представляющих различные уровни цен или условий.
- Задание — задача, созданная при выполнении запроса в этом API. При использовании этого API для управления частными предложениями и несколькими частными предложениями создается задание для выполнения запроса. После завершения задания вы можете получить дополнительные сведения о соответствующем (многопартийном) частном предложении.
Поддерживаемые сценарии
- Создание частного предложения для клиента
- Создание частного предложения для торгового посредника
- Создание многопартийного частного предложения для клиента
- Удаление частного предложения
- Отзыв частного предложения
- Запрос списка многопартийных частных предложений
- Запрос списка продуктов и планов
Подготовка к использованию этого API
Прежде чем писать код для вызова API частных предложений, убедитесь, что выполнены следующие предварительные требования. Те же предварительные требования применяются ко всем партнерам публикации.
Шаг 1. Полные предварительные требования для использования API приема продуктов Майкрософт (один раз)
У вас или вашей организации должен быть каталог Microsoft Entra и разрешение глобального администратора. Если вы уже используете Microsoft 365 или другие бизнес-службы от Майкрософт, у вас уже есть каталог Microsoft Entra. Если нет, вы можете создать новый идентификатор Microsoft Entra в Центре партнеров бесплатно.
Необходимо связать приложение Идентификатора Microsoft Entra с учетной записью Центра партнеров и получить идентификатор клиента, идентификатор клиента и ключ. Эти значения необходимы для получения маркера доступа Microsoft Entra, который вы будете использовать в вызовах к API частных предложений.
Шаг 2. Получение маркера доступа Microsoft Entra (каждый раз)
Прежде чем вызывать любой из методов в API отправки в Microsoft Store, вам потребуется маркер доступа Microsoft Entra для передачи в заголовок авторизации каждого метода в API. До истечения срока действия маркера требуется 60 минут. После истечения срока действия маркер можно обновить, чтобы продолжить использовать его в дальнейших вызовах API.
Чтобы получить маркер доступа, ознакомьтесь со службой вызовов служб с использованием учетных данных клиента для отправки HTTP POST https://login.microsoftonline.com/<в конечную точку tenant_id>/oauth2/token . Ниже приведен пример запроса:
POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://graph.microsoft.com/
Для значения tenant_id в URI POST и параметрах client_id и client_secret укажите идентификатор клиента, идентификатор клиента и ключ приложения, полученного из Центра партнеров в предыдущем разделе. Для параметра ресурса необходимо указать https://graph.microsoft.com/.
Поиск идентификаторов продуктов, планов и частных предложений
| ИД | Где найти их |
|---|---|
| client_id | См . статью "Связывание приложения Microsoft Entra" с учетной записью Центра партнеров. |
| tenant_id | См . статью "Связывание приложения Microsoft Entra" с учетной записью Центра партнеров. |
| client_secret | См . статью "Связывание приложения Microsoft Entra" с учетной записью Центра партнеров. |
| productId | См. статью " Получение продуктов " в этой статье. |
| planId | См . сведения о планах извлечения определенного продукта в этой статье. |
| privateofferId | См. статью "Получение частных предложений " в этой статье. |
Получение продуктов
Частное предложение основано на существующем продукте в учетной записи Центра партнеров. Чтобы просмотреть список продуктов, связанных с учетной записью Центра партнеров, используйте этот вызов API:
GET https://graph.microsoft.com/rp/product-ingestion/product?$version=2022-07-01
Ответ отображается в следующем примере:
{
"value": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-07-01",
"id": "string",
"identity": {
"externalId": "string"
},
"type": "enum",
"alias": "string"
}
],
"@nextLink": "opaque_uri"
}
Получение планов для конкретного продукта
Для продуктов, содержащих несколько планов, может потребоваться создать частное предложение на основе одного конкретного плана. Если да, вам нужен идентификатор этого плана. Получите список планов (например, вариантов или номеров SKU) для продукта с помощью следующего вызова API:
GET https://graph.microsoft.com/rp/product-ingestion/plan?product=<product-id>&$version=2022-07-01
Ответ отображается в следующем примере:
{
"value": [
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-07-01",
"product": "string",
"id": "string",
"identity": {
"externalId": "string"
},
"alias": "string"
}
]
}
Получение частных предложений
Чтобы просмотреть список всех частных предложений, включая многопартийные частные предложения, связанные с вашей учетной записью, используйте следующий вызов API:
GET https://graph.microsoft.com/rp/product-ingestion/private-offer/query?$version=2023-07-15
Использование API
API частного предложения позволяет создавать частные предложения, связанные с продуктами и планами, в учетной записи Центра партнеров и управлять ими. Ниже приведена сводка по типичному шаблону вызова при использовании этого API.
Шаг 1. Выполнение запроса
При вызове API для создания, удаления, отзыва или обновления частного предложения создается новое задание для выполнения запрошенной задачи. Ответ API содержит идентификатор задания, связанный с заданием.
Шаг 2. Опрос состояния задания
Используя jobId из первоначального ответа API, опрос, чтобы получить состояние задания. Состояние задания будет запущено или завершено. После завершения задания результат будет выполнен успешно или неудачно. Чтобы избежать проблем с производительностью, не опрашивайте задание более одного раза в минуту.
| jobStatus | Description |
|---|---|
| NotStarted | Задание еще не запущено; это часть ответа по первоначальному запросу. |
| Выполняется | Задание по-прежнему выполняется. |
| Завершено | Задание завершено. Дополнительные сведения см . в jobResult . |
| jobResult | Description |
| Ожидает | Задание еще не завершено. |
| Выполнено | Задание успешно завершено. Это задание также возвращает URI ресурса, который ссылается на частное предложение, связанное с заданием. Используйте этот ресурс URI для получения полных сведений о частном предложении. |
| Неудачно | Задание завершилось сбоем. Это также возвращает все соответствующие ошибки, которые помогут определить причину сбоя. |
Дополнительные сведения см. в статье "Запрос состояния существующего задания".
Шаг 3. Получение сведений из завершенных заданий
Успешное задание возвращает resourceUri, ссылающийся на соответствующее частное предложение. Используйте этот URI ресурса, чтобы получить дополнительные сведения о частном предложении в будущем, например privateofferId.
Неудачное задание содержит ошибки, которые содержат подробные сведения о том, почему задание завершилось сбоем и как устранить проблему.
Дополнительные сведения см. в разделе "Получение сведений о существующем частном предложении".
Как поставщик программного обеспечения и партнер канала должны совместно использовать API для многопартийного частного предложения
Оба поставщика программного обеспечения и канала могут использовать одни и те же API для создания и управления заданным MPO. Однако ресурсы в MPO, которые могут повлиять на API, зависят от того, является ли вызывающий объект API поставщиком программного обеспечения (источником) или партнером канала (продавцом) MPO. Те же поток публикации партнеров и бизнес-правила, управляющие Центром партнеров, отражаются в API. Ниже приведен обзор:
| Операция API | ISV (источник) | Партнер канала (продавец) |
|---|---|---|
| Создание |
|
|
| Удаление |
|
|
| Отводить |
|
|