APIs de cobrança medida do Marketplace
As APIs de cobrança medidas devem ser usadas quando o editor cria dimensões de medição personalizadas para publicar uma oferta no Partner Center. A integração com as APIs de cobrança por uso é necessária para qualquer oferta comprada que tenha um ou mais planos com dimensões personalizadas para emitir eventos de uso.
Importante
Você deve controlar o uso em seu código e enviar apenas eventos de uso para a Microsoft para o uso acima da taxa base.
Para obter mais informações sobre como criar dimensões de medição customizadas para SaaS, consulte SaaS metered billing.
Para obter mais informações sobre como criar dimensões de medição personalizadas para uma oferta de Aplicativo do Azure com um plano de aplicativo gerenciado, consulte Configurar os detalhes de instalação da oferta de aplicativo do Azure.
Nota sobre a aplicação do TLS 1.2
A versão 1.2 do TLS é imposta como a versão mínima para comunicações HTTPS. Use esta versão do TLS em seu código. As versões 1.0 e 1.1 do TLS foram preteridas e as tentativas de conexão serão recusadas.
Evento de uso individual com cobrança medida
A API de evento de uso deve ser chamada pelo fornecedor para emitir eventos de uso com relação a um recurso ativo (assinado) referente ao plano que o cliente específico adquiriu. O evento de uso é emitido separadamente para cada dimensão personalizada do plano definido pelo editor ao publicar a oferta.
Apenas um evento de uso pode ser emitido para cada hora de um dia de calendário por recurso e dimensão. Se mais de uma unidade for consumida em uma hora, acumule todas as unidades consumidas na hora e emita-a em um único evento. Os eventos de uso só podem ser emitidos nas últimas 24 horas. Se você emitir um evento de uso a qualquer momento entre 8:00 e 8:59:59 (e ele for aceito) e enviar um evento adicional para o mesmo dia entre 8:00 e 8:59:59, ele será rejeitado como uma duplicata.
POST: https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>
parâmetros de consulta:
| Parâmetro | Recomendação |
|---|---|
ApiVersion |
Use 2018-08-31. |
Cabeçalhos de solicitação:
| Tipo de conteúdo | Usar application/json |
|---|---|
x-ms-requestid |
Valor de cadeia de caracteres exclusivo para acompanhar a solicitação do cliente, de preferência, um GUID. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta. |
x-ms-correlationid |
Valor de cadeia de caracteres exclusivo para operação no cliente. Esse parâmetro correlaciona todos os eventos da operação do cliente com eventos no lado do servidor. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta. |
authorization |
Um token de acesso exclusivo que identifica o ISV que está fazendo essa chamada à API. O formato é "Bearer <access_token>" quando o valor do token é recuperado pelo publicador, conforme explicado para
|
Exemplo de corpo da solicitação:
{
"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
}
Para planos de Aplicativos Gerenciados de Aplicativo do Azure, o resourceId é o Aplicativo Gerenciado resource group Id. Um exemplo de script para buscar ele pode ser encontrado em usando o token de identidades gerenciadas pelo Azure.
Para ofertas de SaaS, o resourceId é a ID da assinatura SaaS. Para obter mais detalhes sobre assinaturas SaaS, confira lista de assinaturas.
Respostas
Código: 200
OKEY. A emissão de uso foi aceita e registrada pela Microsoft para posterior processamento e cobrança.
Exemplo de conteúdo da resposta:
{
"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
}
Código: 400
Solicitação incorreta.
- Dados de solicitação ausentes ou inválidos fornecidos.
effectiveStartTimeestá há mais de 24 horas no passado. O evento expirou.- A assinatura de SaaS não está no status "Assinado".
Exemplo de conteúdo da resposta:
{
"message": "One or more errors have occurred.",
"target": "usageEventRequest",
"details": [
{
"message": "The resourceId is required.",
"target": "ResourceId",
"code": "BadArgument"
}
],
"code": "BadArgument"
}
Código: 401 Não autorizado. O token de autorização é inválido ou expirou. A solicitação está tentando acessar uma assinatura SaaS para uma oferta que foi publicada com uma ID de aplicativo do Microsoft Entra diferente daquela usada para criar o token de autenticação.
Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou recebeu permissões insuficientes. Forneça um token de autorização válido.
Código: 409
Conflito. Um evento de uso já foi relatado com êxito para a ID do recurso especificada, data e hora de uso efetivos.
Exemplo de conteúdo da resposta:
{
"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"
}
Evento de uso em lote de cobrança medida
A API de evento de uso em lote permite que você emita eventos de uso para mais de um recurso comprado ao mesmo tempo. Ele também permite que você emita vários eventos de uso para o mesmo recurso, desde que sejam para horários de calendário diferentes. O número máximo de eventos em um único lote é 25.
POST:https://marketplaceapi.microsoft.com/api/batchUsageEvent?api-version=<ApiVersion>
Parâmetros de consulta:
| Parâmetro | Recomendação |
|---|---|
ApiVersion |
Use 2018-08-31. |
Cabeçalhos de solicitação:
| Tipo de conteúdo | Usar application/json |
|---|---|
x-ms-requestid |
Valor de cadeia de caracteres exclusivo para acompanhar a solicitação do cliente, de preferência, um GUID. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta. |
x-ms-correlationid |
Valor de cadeia de caracteres exclusivo para operação no cliente. Esse parâmetro correlaciona todos os eventos da operação do cliente com eventos no lado do servidor. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta. |
authorization |
Um token de acesso exclusivo que identifica o ISV que está fazendo essa chamada à API. O formato é Bearer <access_token> quando o valor do token é recuperado pelo publicador, conforme explicado para
|
Nota
No corpo da solicitação, o identificador de recurso tem significados diferentes para o aplicativo SaaS e para o medidor personalizado emitido pelo aplicativo Gerenciado do Azure. O identificador de recurso do aplicativo SaaS é resourceID. O identificador de recurso para planos de Aplicativos Gerenciados do Azure é resourceUri. Para obter mais informações sobre identificadores de recursos, consulte Cobrança de Consumo do Azure Marketplace: Escolhendo a ID correta ao enviar eventos de uso.
Para ofertas de SaaS, o resourceId é a ID da assinatura SaaS. Para obter mais detalhes sobre assinaturas SaaS, confira lista de assinaturas.
Exemplo do corpo da solicitação para aplicativos de 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
}
]
}
Para planos de Aplicativos Gerenciados do Azure, o resourceUri é o aplicativo gerenciado resourceUsageId. Um exemplo de script para buscar ele pode ser encontrado em usando o token de identidades gerenciadas pelo Azure.
Exemplo do corpo da solicitação para aplicativos gerenciados pelo Aplicativo do 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
}
]
}
Respostas
Código: 200
OKEY. A emissão de uso em lote foi aceita e registrada pela Microsoft para processamento e cobrança adicional. A lista de respostas é retornada com o status de cada evento individual no lote. Você deve iterar o conteúdo de resposta para entender as respostas de cada evento individual de uso enviado como parte do evento em lote.
Exemplo de conteúdo da resposta:
{
"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"
}
]
}
Descrição do código de status referenciado na resposta à API BatchUsageEvent.
| Código de status | Descrição |
|---|---|
Accepted |
Aceitado. |
Expired |
Uso expirado. |
Duplicate |
Uso duplicado detectado. |
Error |
Código de erro. |
ResourceNotFound |
O recurso de uso fornecido é inválido. |
ResourceNotAuthorized |
Você não está autorizado a fornecer uso para esse recurso. |
ResourceNotActive |
O recurso está suspenso ou nunca foi ativado. |
InvalidDimension |
A dimensão para a qual o uso foi passado é inválida para esta oferta/plano. |
InvalidQuantity |
A quantidade passada é menor ou igual a 0. |
BadArgument |
A entrada está ausente ou malformada. |
Código: 400
Solicitação incorreta. O lote continha mais de 25 eventos de uso.
Código: 401 Não autorizado. O token de autorização é inválido ou expirou. A solicitação está tentando acessar uma assinatura SaaS para uma oferta que foi publicada com um ID de aplicativo Microsoft Entra diferente do usado para criar o token de autenticação.
Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou recebeu permissões insuficientes. Forneça um token de autorização válido.
Recuperar eventos de uso para cobrança medida
Você pode chamar a API de eventos de uso para obter a lista de eventos de uso. Os ISVs podem usar essa API para visualizar os eventos de uso que foram registrados durante uma determinada duração de tempo configurável e verificar em que estado esses eventos se encontram no momento de chamar a API.
GET: https://marketplaceapi.microsoft.com/api/usageEvents
parâmetros de consulta:
| Parâmetro | Recomendação |
|---|---|
| ApiVersion | Use 2018-08-31. |
| usageStartDate | DateTime no formato ISO8601. Por exemplo, 2020-12-03T15:00 ou 2020-12-03 |
| UsageEndDate (opcional) | DateTime no formato ISO8601. Padrão = data atual |
| offerId (opcional) | Padrão = todos os disponíveis |
| planId (opcional) | Padrão = todos os disponíveis |
| dimensão (opcional) | Padrão = todos os disponíveis |
| azureSubscriptionId (opcional) | Padrão = todos os disponíveis |
| reconStatus (opcional) | Padrão = tudo disponível |
Valores possíveis de reconStatus:
| ReconStatus | Descrição |
|---|---|
| Enviado | Ainda não processado pela Análise de PC |
| Aceitado | Compatível com a análise de PC |
| Indeferido | Rejeitado na linha de produção. Entre em contato com o suporte da Microsoft para investigar a causa. |
| Incompatibilidade | As quantidades do MarketplaceAPI e do Partner Center Analytics são ambas não-zero, no entanto, não coincidem. |
Cabeçalhos de solicitação:
| Tipo de conteúdo | Usar aplicativo/json |
|---|---|
| x-ms-requestid | Valor de cadeia de caracteres exclusivo (preferencialmente um GUID) para acompanhar a solicitação do cliente. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta. |
| x-ms-correlationid | Valor de cadeia de caracteres exclusivo para operação no cliente. Esse parâmetro correlaciona todos os eventos da operação do cliente com eventos no lado do servidor. Se esse valor não for fornecido, um será gerado e fornecido nos cabeçalhos de resposta. |
| autorização | Um token de acesso exclusivo que identifica o ISV que está fazendo essa chamada à API. O formato é Bearer <access_token> quando o valor do token é recuperado pelo publicador. Para obter mais informações, consulte:
|
Respostas
Exemplos de conteúdo de resposta:
* Aceito
[
{
"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
}
]
Enviado
[
{
"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
}
]
Incompatibilidade
[
{
"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
}
]
Rejeitado
[
{
"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
}
]
códigos de status
Código: 401 Não autorizado. O token de autorização é inválido ou expirou. A solicitação está tentando acessar uma assinatura de SaaS para uma oferta publicada com uma ID do aplicativo do Microsoft Entra diferente daquela usada para criar o token de autenticação.
Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou recebeu permissões insuficientes. Forneça um token de autorização válido.
Melhores práticas de desenvolvimento e teste
Para testar a emissão de medidor personalizado, implemente a integração com a API de medição, crie um plano para sua oferta de SaaS publicada com dimensões personalizadas definidas nela com preço zero por unidade. E publique essa oferta como versão prévia para que apenas usuários limitados possam acessar e testar a integração.
Você também pode usar um plano privado para uma oferta ao vivo existente para limitar o acesso a esse plano durante a fase de teste a um público restrito.
Obter suporte
Siga as instruções em Suporte para o programa do marketplace comercial no Partner Center para entender as opções de suporte do editor e abrir um tíquete de suporte com a Microsoft.
Conteúdo relacionado
Para obter mais informações sobre APIs de serviço de medição, confira Perguntas frequentes sobre APIs de serviço de medição do Marketplace.