API для учета потребления в торговой площадке

API-интерфейсы тарификации должны использоваться, когда издатель создает новые параметры учета для предложения, которое будет опубликовано в Партнёрском центре. Для интеграции с метрическими биллинговыми API требуется любое приобретенное предложение, содержащее один или несколько планов с пользовательскими измерениями, для генерации событий использования.

Важный

Вы должны отслеживать использование в вашем коде и отправлять в Microsoft только события использования, связанного с превышением базовой платы.

Дополнительную информацию о создании пользовательских измерений для SaaS см. в разделе учет потребления SaaS.

Дополнительные сведения о создании пользовательских измерений потребления для предложения приложения Azure с управляемым планом см. в разделе Настройка параметров предложения вашего приложения Azure.

Примечание о применении TLS 1.2

Протокол TLS версии 1.2 применяется как минимальная версия для обмена данными HTTPS. Убедитесь, что в коде используется эта версия TLS. TLS версии 1.0 и 1.1 устарели, и попытки подключения будут отклонены.

Единичное событие использования с поминутной тарификацией

API событий использования должен быть вызван издателем для записи событий использования активного ресурса в соответствии с планом, приобретенным определенным клиентом. Событие использования генерируется отдельно для каждого пользовательского измерения плана, определенного издателем при публикации предложения.

В течение календарного дня в каждый час для каждого ресурса и измерения может быть зарегистрировано только одно событие использования. Если за час потребляется более одной единицы, то накапливайте все единицы, потребляемые в течение часа, а затем выведите их в одном событии. События использования можно генерировать только за последние 24 часа. Если вы в любое время эмитируете событие использования в период от 8:00 до 8:59:59 (и оно принимается) и отправляете дополнительное событие в тот же день в период от 8:00 до 8:59:59, оно будет отклонено как дубликат.

POST: https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>

Параметры запроса:

Параметр	Рекомендация
ApiVersion	Используйте 2018-08-31.

Заголовки запросов :

Тип контента	Используйте application/json
x-ms-requestid	Уникальное строковое значение для отслеживания запроса от клиента, предпочтительно GUID. Если это значение не указано, оно будет создано и указано в заголовках ответа.
x-ms-correlationid	Уникальное строковое значение для операции на клиенте. Этот параметр сопоставляет все события из операции клиента с событиями на стороне сервера. Если это значение не указано, оно будет создано и указано в заголовках ответа.
authorization	Уникальный токен доступа, идентифицирующий ISV (независимого поставщика программного обеспечения), осуществляющего данный вызов API. Формат "Bearer <access_token>" используется, когда издатель извлекает значение токена, как объяснено. SaaS в Получить токен с помощью HTTP POST. Управляемое приложение в стратегиях проверки подлинности .

Пример текста запроса :

{
  "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
ХОРОШО. Данные об использовании были приняты и записаны на сервере Microsoft для дальнейшей обработки и выставления счетов.

Пример полезной нагрузки ответа:

{
  "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"
}

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

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

Код: 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.

POST:https://marketplaceapi.microsoft.com/api/batchUsageEvent?api-version=<ApiVersion>

Параметры запроса:

Параметр	Рекомендация
ApiVersion	Используйте 2018-08-31.

Заголовки запросов :

Тип контента	Используйте application/json
x-ms-requestid	Уникальное строковое значение для отслеживания запроса от клиента, предпочтительно GUID. Если это значение не указано, одно будет создано и предоставлено в заголовках ответа.
x-ms-correlationid	Уникальное строковое значение для операции на клиенте. Этот параметр сопоставляет все события из операции клиента с событиями на стороне сервера. Если это значение не указано, одно будет создано и предоставлено в заголовках ответа.
authorization	Уникальный токен доступа, идентифицирующий ISV (независимого поставщика программного обеспечения), осуществляющего данный вызов API. Формат Bearer <access_token> используется, когда издатель извлекает значение токена, как объяснено. SaaS в контексте Получения токена с помощью HTTP POST. Управляемое приложение в стратегиях проверки подлинности .

Заметка

В тексте запроса идентификатор ресурса имеет разные значения для приложения SaaS и управляемого приложения Azure, создающего настраиваемый счетчик. Идентификатор ресурса для приложения SaaS resourceID. Идентификатор ресурса для планов управляемых приложений Azure resourceUri. Дополнительные сведения об идентификаторах ресурсов см. в статье Выставление счетов в 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
    }
  ]
}

В планах управляемых приложений Azure resourceUri является управляемым приложением 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
ХОРОШО. Пакетные данные об использовании были приняты и зафиксированы у Microsoft для дальнейшей обработки и выставления счетов. Список ответов возвращается с состоянием для каждого отдельного события в пакете. Необходимо выполнить итерацию по нагрузке ответа, чтобы понять ответы для каждого отдельного события использования, отправленные в составе пакетного события.

Пример полезной нагрузки ответа:

{
  "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:

Код состояния	Описание
Accepted	Принято.
Expired	Истек срок действия.
Duplicate	Повторное использование предоставлено.
Error	Код ошибки.
ResourceNotFound	Предоставленный ресурс для использования недопустим.
ResourceNotAuthorized	У вас нет разрешения использовать этот ресурс.
ResourceNotActive	Ресурс приостановлен или никогда не активирован.
InvalidDimension	Измерение, для которого передается использование, недопустимо для этого предложения или плана.
InvalidQuantity	Передаваемое количество меньше или равно 0.
BadArgument	Входные данные отсутствуют или неправильно сформированы.

Код: 400
Недопустимый запрос. Пакет содержал более 25 событий использования.

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

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

Получение событий использования в рамках тарификации по измерению услуг

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

GET: https://marketplaceapi.microsoft.com/api/usageEvents

параметры запроса:

Параметр	Рекомендация
ApiVersion	Используйте 2018-08-31.
дата начала использования	DateTime в формате ISO8601. Например, 2020-12-03T15:00 или 2020-12-03
Дата окончания использования (необязательно)	DateTime в формате ISO8601. Default = текущая дата
offerId (необязательно)	По умолчанию = все доступные
planId (необязательно)	По умолчанию = все доступные
размерность (необязательно)	По умолчанию = все доступные
azureSubscriptionId (необязательно)	По умолчанию = все доступные
reconStatus (необязательно)	По умолчанию = все доступные

возможные значения reconStatus:

ReconStatus	Описание
Отправлено	Ещё не обработано системой аналитики ПК
Принято	Соответствует аналитике персонального компьютера
Отклонено	Отклонено в конвейере. Обратитесь в службу поддержки Майкрософт, чтобы изучить причину.
Несовпадение	Количество для MarketplaceAPI и Аналитики Центра партнеров не равно нулю, однако значения не совпадают.

заголовки запросов:

Тип контента	Используйте application/json
x-ms-requestid	Уникальное строковое значение (предпочтительно GUID) для отслеживания запроса от клиента. Если это значение не указано, оно будет создано и указано в заголовках ответа.
x-ms-correlationid	Уникальное строковое значение для операции на клиенте. Этот параметр сопоставляет все события из операции клиента с событиями на стороне сервера. Если это значение не указано, оно будет создано и указано в заголовках ответа.
авторизация	Уникальный токен доступа, идентифицирующий ISV (независимого поставщика программного обеспечения), осуществляющего данный вызов API. Формат — Bearer <access_token>, когда значение токена получено издателем. Дополнительные сведения см. в следующем разделе: SaaS в Получите токен с помощью HTTP POST Управляемое приложение в стратегиях проверки подлинности

Ответы

Примеры полезных данных ответа:

принято*

[
  {
    "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
  }
]

коды состояния

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

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

Лучшие практики разработки и тестирования

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

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

Получение поддержки

Следуйте инструкциям в поддержке программы коммерческой платформы в Центре партнеров, чтобы понять варианты поддержки издателей и открыть запрос в службу поддержки майкрософт.

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

Дополнительные сведения об API-интерфейсах службы измерения см. в Часто задаваемые вопросы об API службы измерения Marketplace.