Поделиться через

API-интерфейсы выставления счетов в Marketplace с лимитным счетом

  • Статья

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

Важный

Необходимо отслеживать использование в коде и отправлять только события использования корпорации Майкрософт для использования, превышающего базовую плату.

Дополнительные сведения о создании пользовательских измерений для 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>" используется, когда издатель извлекает значение токена, как объяснено.

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

{
  "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 Уникальный маркер доступа, идентифицирующий независимого поставщика ПО, выполняющего этот вызов API. Формат Bearer <access_token> используется, когда значение токена извлекается издателем, как объясняется для.

Заметка

В тексте запроса идентификатор ресурса имеет разные значения для приложения 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 Используйте дату 31-08-2018.
дата начала использования DateTime в формате ISO8601. Например, 2020-12-03T15:00 или 2020-12-03
UsageEndDate (необязательно) DateTime в формате ISO8601. Default = текущая дата
offerId (необязательно) По умолчанию = все доступные
planId (необязательно) По умолчанию: все доступные
размерность (необязательно) По умолчанию = все доступные
azureSubscriptionId (необязательно) По умолчанию = все доступные
reconStatus (необязательно) По умолчанию = все доступные

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

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

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

Тип контента Используйте 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
  }
]

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

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

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

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

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

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

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

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

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

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