API выставления счетов по тарифу в Marketplace
Если издатель создает собственные измерения контроля для предложения, которое должно быть опубликовано в Центре партнеров, следует использовать API выставления счетов за потребление. Интеграция с отслеживаемыми API выставления счетов за потребление требуется для любого приобретенного предложения с одним или несколькими планами с пользовательскими измерениями, чтобы создавать события потребления.
Важно!
Необходимо отслеживать использование в коде и отправлять только события использования корпорации Майкрософт для использования, превышающего базовую плату.
Дополнительные сведения о создании пользовательских измерений контроля для SaaS см. в статье Контроль потребления для SaaS.
Дополнительные сведения о создании пользовательских измерений контроля для предложения приложения Azure с помощью плана управляемого приложения см. в статье Настройка сведений о настройке предложения приложения Azure.
Примечание по принудительному применению TLS 1.2
Версия TLS 1.2 применяется в качестве минимальной версии для HTTPS-соединений. Убедитесь, что в коде используется эта версия TLS. Версии TLS 1.0 и 1.1 являются устаревшими, и попытки подключения с ними будут отклонены.
Выставление счета по тарифу за одно событие потребления
API события потребления должен вызываться издателем для отправки событий потребления в активный ресурс (с подпиской) для плана, приобретенного конкретным клиентом. Событие потребления создается отдельно для каждого пользовательского измерения плана, определенного издателем при публикации предложения.
Для каждого часа календаря и измерения можно создавать только одно событие использования. Если в течение часа использовалось более одной единицы, все единицы, потребленные в течение часа, накапливаются, а затем выдаются в одном событии. События потребления генерируются только за последние 24 часа. Если вы генерируете событие потребления в любое время между 08:00 и 08:59:59 (и оно принимается) и отправляете дополнительное событие для того же дня между 08:00 и 08:59:59, оно будет отклонено как повторяющееся.
POST:https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>
Параметры запроса.
| Параметр | Рекомендация |
|---|---|
ApiVersion |
Используйте версию 2018-08-31. |
Заголовки запроса:
| Content-type | Использование application/json |
|---|---|
x-ms-requestid |
Уникальное строковое значение для отслеживания запроса клиента, желательно GUID. Если это значение не указано, оно создается случайным образом и возвращается в заголовке ответа. |
x-ms-correlationid |
Уникальное строковое значение для операции на стороне клиента. Этот параметр позволяет сопоставить все события клиентской операции с событиями на стороне сервера. Если это значение не указано, оно создается и возвращается в заголовках ответа. |
authorization |
Уникальный маркер доступа, определяющий независимого поставщика программного обеспечения, совершающего вызов API. Формат заключается "Bearer <access_token>" в том, когда значение маркера извлекается издателем, как описано ниже.
|
Пример текста запроса:
{
"resourceId": <guid>, // unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
}
Для планов управляемых приложений Azure параметр resourceId является параметром resource group Id управляемого приложения. Пример скрипта для его получения приведен в разделе Использование токена удостоверений, управляемых Azure.
Для предложений SaaS resourceId содержит идентификатор подписки SaaS. Дополнительные сведения о подписках SaaS см. в этом списке.
Отклики
Код: 200
ОК. Эмиссия потребления была принята и записана на стороне Майкрософт для дальнейшей обработки и выставления счетов.
Пример полезных данных ответа:
{
"usageEventId": <guid>, // unique identifier associated with the usage event in Microsoft records
"status": "Accepted" // this is the only value in case of single usage event
"messageTime": "2020-01-12T13:19:35.3458658Z", // time in UTC this event was accepted
"resourceId": <guid>, // unique identifier of the resource against which usage is emitted. For SaaS it's the subscriptionId.
"quantity": 5.0, // amount of emitted units as recorded by Microsoft
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, as sent by the ISV
"planId": "plan1", // id of the plan purchased for the offer
}
Код: 400
Недопустимый запрос.
- Указаны отсутствующие или недопустимые данные запроса.
- Время
effectiveStartTimeбыло более чем 24 назад. Срок действия события истек. - Подписка SaaS не отображается в состоянии подписки.
Пример полезных данных ответа:
{
"message": "One or more errors have occurred.",
"target": "usageEventRequest",
"details": [
{
"message": "The resourceId is required.",
"target": "ResourceId",
"code": "BadArgument"
}
],
"code": "BadArgument"
}
Код: 403
Запрещено. Маркер авторизации не указан, является недопустимым или срок его действия истек. Или запрос пытается получить доступ к подписке для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера авторизации.
Код: 409
Конфликта. Событие использования уже успешно отправлено для указанного идентификатора ресурса, настоящей даты и часа потребления.
Пример полезных данных ответа:
{
"additionalInfo": {
"acceptedMessage": {
"usageEventId": "<guid>", //unique identifier associated with the usage event in Microsoft records
"status": "Duplicate",
"messageTime": "2020-01-12T13:19:35.3458658Z",
"resourceId": "<guid>", //unique identifier of the resource against which usage is emitted.
"quantity": 1.0,
"dimension": "dim1",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "plan1"
}
},
"message": "This usage event already exist.",
"code": "Conflict"
}
Событие потребления пакетного выставления счетов
API пакетных событий потребления позволяет одновременно создавать события потребления для нескольких приобретенных ресурсов. Кроме того, он позволяет выдавать несколько событий использования для одного ресурса, если они в течение разных календарных часов. Максимальное число событий в одном пакете: 25.
POSThttps://marketplaceapi.microsoft.com/api/batchUsageEvent?api-version=<ApiVersion>:
Параметры запроса.
| Параметр | Рекомендация |
|---|---|
ApiVersion |
Используйте версию 2018-08-31. |
Заголовки запроса:
| Content-type | Использование application/json |
|---|---|
x-ms-requestid |
Уникальное строковое значение для отслеживания запроса клиента, желательно GUID. Если это значение не указано, оно создается и возвращается в заголовках ответа. |
x-ms-correlationid |
Уникальное строковое значение для операции на стороне клиента. Этот параметр позволяет сопоставить все события клиентской операции с событиями на стороне сервера. Если это значение не указано, оно создается и возвращается в заголовках ответа. |
authorization |
Уникальный маркер доступа, определяющий независимого поставщика программного обеспечения, совершающего вызов API. Формат заключается Bearer <access_token> в том, когда значение маркера извлекается издателем, как описано ниже.
|
Примечание.
В тексте запроса идентификатор ресурса имеет разные значения для приложения SaaS и управляемого приложения Azure, создающего настраиваемый счетчик. Идентификатор ресурса для приложения SaaS resourceID. Идентификатор ресурса для планов resourceUriуправляемых приложений приложение Azure. Дополнительные сведения об идентификаторах ресурсов см. в статье о выставлении счетов в Azure Marketplace с использованием счетчиков. Выбор правильного идентификатора при отправке событий использования.
Для предложений SaaS resourceId содержит идентификатор подписки SaaS. Дополнительные сведения о подписках SaaS см. в этом списке.
Пример текста запроса для приложений SaaS:
{
"request": [ // list of usage events for the same or different resources of the publisher
{ // first event
"resourceId": "<guid1>", // Unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", //Custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
},
{ // next event
"resourceId": "<guid2>",
"quantity": 39.0,
"dimension": "email",
"effectiveStartTime": "2018-11-01T23:33:10
"planId": "gold", // id of the plan purchased for the offer
}
]
}
Для планов resourceUri приложение Azure управляемых приложений используется управляемое приложениеresourceUsageId. Пример скрипта для его получения приведен в разделе Использование токена удостоверений, управляемых Azure.
Пример текста запроса для управляемых приложений приложение Azure:
{
"request": [ // list of usage events for the same or different resources of the publisher
{ // first event
"resourceUri": "<fullyqualifiedname>", // Unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", //Custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
}
]
}
Отклики
Код: 200
ОК. Эмиссия пакетного потребления была принята и записана на стороне Майкрософт для дальнейшей обработки и выставления счетов. Список ответов возвращается с состоянием каждого отдельного события в пакете. Необходимо выполнить итерацию полезных данных ответа, чтобы понять ответы для каждого отдельного события потребления, отправляемого как часть события пакетной службы.
Пример полезных данных ответа:
{
"count": 2, // number of records in the response
"result": [
{ // first response
"usageEventId": "<guid>", // unique identifier associated with the usage event in Microsoft records
"status": "Accepted" // see list of possible statuses below,
"messageTime": "2020-01-12T13:19:35.3458658Z", // Time in UTC this event was accepted by Microsoft,
"resourceId": "<guid1>", // unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // amount of emitted units as recorded by Microsoft
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",// time in UTC when the usage event occurred, as sent by the ISV
"planId": "plan1", // id of the plan purchased for the offer
},
{ // second response
"status": "Duplicate",
"messageTime": "0001-01-01T00:00:00",
"error": {
"additionalInfo": {
"acceptedMessage": {
"usageEventId": "<guid>",
"status": "Duplicate",
"messageTime": "2020-01-12T13:19:35.3458658Z",
"resourceId": "<guid2>",
"quantity": 1.0,
"dimension": "email",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "gold"
}
},
"message": "This usage event already exist.",
"code": "Conflict"
},
"resourceId": "<guid2>",
"quantity": 1.0,
"dimension": "email",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "gold"
}
]
}
Описание кода состояния, указанного в ответе API BatchUsageEvent:
| Код состояния | Description |
|---|---|
Accepted |
Принято. |
Expired |
Потребление с истекшим сроком действия. |
Duplicate |
Предоставлен дубликат сведений о потреблении. |
Error |
Код ошибки. |
ResourceNotFound |
Указан недопустимый ресурс потребления. |
ResourceNotAuthorized |
Вы не авторизованы для предоставления использования этого ресурса. |
ResourceNotActive |
Ресурс приостановлен или не был активирован. |
InvalidDimension |
Измерение, для которого предоставлены сведения о потреблении, недопустимо для этого предложения или плана. |
InvalidQuantity |
Переданное количество меньше или равно 0. |
BadArgument |
Входное значение отсутствует или является недопустимым. |
Код: 400
Недопустимый запрос. Пакет содержал более 25 событий потребления.
Код: 403
Запрещено. Маркер авторизации не указан, является недопустимым или срок его действия истек. Или запрос пытается получить доступ к подписке для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера авторизации.
Измерение выставления счетов извлекает события использования
Вы можете вызвать API событий использования, чтобы получить список событий использования. Поставщики программного обеспечения могут использовать этот API для просмотра событий использования, которые были размещены в течение определенного настраиваемого периода времени и состояния этих событий в точке вызова API.
GET: https://marketplaceapi.microsoft.com/api/usageEvents
Параметры запроса.
| Параметр | Рекомендация |
|---|---|
| ApiVersion | Используйте версию 2018-08-31. |
| usageStartDate | DateTime в формате ISO8601. Например, 2020-12-03T15:00 или 2020-12-03 |
| UsageEndDate (необязательно) | DateTime в формате ISO8601. Default = текущая дата |
| offerId (необязательно) | Default = все доступные |
| planId (необязательно) | Default = все доступные |
| измерение (необязательно) | Default = все доступные |
| azureSubscriptionId (необязательно) | Default = все доступные |
| reconStatus (необязательно) | Default = все доступные |
Возможные значения reconStatus:
| ReconStatus | Description |
|---|---|
| Отправлено | Пока не обработано аналитикой КОМПЬЮТЕРов |
| Акцептировано | Соответствует аналитике компьютеров |
| Аннулировано | Отклонено в конвейере. Обратитесь в службу поддержки Майкрософт, чтобы изучить причину. |
| Несоответствие | Количество Аналитики MarketplaceAPI и Центра партнеров не равно нулю, но не соответствует |
Заголовки запроса:
| Content type | Использование application/json |
|---|---|
| x-ms-requestid | Уникальное строковое значение (предпочтительно GUID) для отслеживания запроса от клиента. Если это значение не указано, оно создается и возвращается в заголовках ответа. |
| x-ms-correlationid | Уникальное строковое значение для операции на стороне клиента. Этот параметр позволяет сопоставить все события клиентской операции с событиями на стороне сервера. Если это значение не указано, оно создается и возвращается в заголовках ответа. |
| авторизации | Уникальный маркер доступа, определяющий независимого поставщика программного обеспечения, совершающего вызов API. Формат заключается в Bearer <access_token> том, что значение маркера извлекается издателем. Дополнительные сведения см. в разделе:
|
Отклики
Примеры полезных данных ответа:
Принято*
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "Silver",
"offerId": "mycooloffer",
"offerName": "My Cool Offer",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Accepted",
"submittedQuantity": 17.0,
"processedQuantity": 17.0,
"submittedCount": 17
}
]
Отправлено
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "",
"offerId": "mycooloffer",
"offerName": "",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Submitted",
"submittedQuantity": 17.0,
"processedQuantity": 0.0,
"submittedCount": 17
}
]
Несоответствие
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "Silver",
"offerId": "mycooloffer",
"offerName": "My Cool Offer",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Mismatch",
"submittedQuantity": 17.0,
"processedQuantity": 16.0,
"submittedCount": 17
}
]
Аннулировано
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "",
"offerId": "mycooloffer",
"offerName": "",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Rejected",
"submittedQuantity": 17.0,
"processedQuantity": 0.0,
"submittedCount": 17
}
]
Коды состояния
Код 403: запрещено. Маркер авторизации не указан, является недопустимым или срок его действия истек. Или запрос пытается получить доступ к подписке для предложения, опубликованного с другим идентификатором приложения Microsoft Entra, который использовался для создания маркера авторизации.
Рекомендации по разработке и тестированию
Чтобы протестировать эмиссию пользовательских единиц, реализуйте интеграцию с API контроля потребления, создав план для опубликованного предложения SaaS с пользовательскими измерениями, определенными в нем, с нулевой ценой за единицу. Опубликуйте это предложение в предварительной версии, чтобы только некоторые пользователи могли получить доступ к интеграции и проверить ее.
Вы также можете использовать частный план для существующего действующего предложения, чтобы ограничить доступ к этому плану во время тестирования для ограниченной аудитории.
Поддержка
Следуйте инструкциям на странице технической поддержки программы коммерческой платформы в Центре партнеров, чтобы ознакомиться с вариантами поддержки издателя и открыть запрос в службу поддержки корпорации Майкрософт.
Следующие шаги
Дополнительные сведения об API-интерфейсах служб измерения см. в статьях API службы измерения Marketplace.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по