APIs de faturamento medido do Marketplace
As APIs de faturamento limitado devem ser usadas quando o editor cria dimensões de medição personalizadas para uma oferta a ser publicada no Partner Center. A integração com as APIs de faturamento limitado é necessária para qualquer oferta comprada que tenha um ou mais planos com dimensões personalizadas para emitir eventos de uso.
Importante
Você deve acompanhar o uso em seu código e enviar eventos de uso somente para a Microsoft para o uso acima da taxa básica.
Para obter mais informações sobre como criar dimensões de medição personalizadas para SaaS, consulte Faturamento medido por SaaS.
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 seus detalhes de configuração de oferta de aplicativo do Azure.
Aplicando a nota TLS 1.2
A versão 1.2 do TLS é imposta como a versão mínima para comunicações HTTPS. Certifique-se de usar esta versão 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 utilização única de faturação com tráfego limitado
A API de eventos de uso deve ser chamada pelo editor para emitir eventos de uso em relação a um recurso ativo (inscrito) para o plano adquirido pelo cliente específico. 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, em seguida, emite-a em um único evento. Os eventos de utilização 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.
CORREIO: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 | Utilizar o comando 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. Este 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 de API. O formato é "Bearer <access_token>" quando o valor do token é recuperado pelo editor, conforme explicado para
|
Exemplo de corpo de 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 resource group IdGerenciado . Um script de exemplo para obtê-lo pode ser encontrado no uso do token de identidades gerenciado pelo Azure.
Para ofertas de SaaS, o é o resourceId ID de assinatura SaaS. Para obter mais detalhes sobre assinaturas SaaS, consulte Listar assinaturas.
Respostas
Código: 200
OK. A emissão de uso foi aceita e registrada no lado da Microsoft para processamento e faturamento posteriores.
Exemplo de carga útil de 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
Mau pedido.
- Dados de solicitação ausentes ou inválidos fornecidos.
effectiveStartTimeé mais de 24 horas no passado. O evento expirou.- A assinatura SaaS não está no status Assinado.
Exemplo de carga útil de resposta:
{
"message": "One or more errors have occurred.",
"target": "usageEventRequest",
"details": [
{
"message": "The resourceId is required.",
"target": "ResourceId",
"code": "BadArgument"
}
],
"code": "BadArgument"
}
Código: 403
Proibido. O token de autorização não é fornecido, é inválido ou expirou. Ou a solicitação está tentando acessar uma assinatura de uma oferta que foi publicada com uma ID de aplicativo Microsoft Entra diferente daquela usada para criar o token de autorização.
Código: 409
Conflito. Um evento de uso já foi relatado com êxito para a ID do recurso especificado, data de uso efetivo e hora.
Exemplo de carga útil de 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 do lote de faturamento limitado
A API de eventos de uso em lote permite que você emita eventos de uso para mais de um recurso comprado de uma só vez. Ele também permite que você emita vários eventos de uso para o mesmo recurso, desde que sejam para horas de calendário diferentes. O número máximo de eventos num único lote é 25.
PUBLICAR: 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 | Utilizar o comando 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. Este 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 de API. O formato é Bearer <access_token> quando o valor do token é recuperado pelo editor, 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 emitente do aplicativo gerenciado do Azure. O identificador de recurso para o aplicativo SaaS é resourceID. O identificador de recurso para planos de Aplicativos Gerenciados de Aplicativo do Azure é resourceUri. Para obter mais informações sobre identificadores de recursos, consulte Faturamento medido do Azure Marketplace - Escolhendo a ID correta ao enviar eventos de uso.
Para ofertas de SaaS, o é o resourceId ID de assinatura SaaS. Para obter mais detalhes sobre assinaturas SaaS, consulte Listar assinaturas.
Exemplo de corpo de solicitação para aplicativos 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 de Aplicativo do Azure, o resourceUri é o Aplicativo resourceUsageIdGerenciado . Um script de exemplo para obtê-lo pode ser encontrado no uso do token de identidades gerenciado pelo Azure.
Exemplo de corpo de solicitação para aplicativos gerenciados do 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
OK. A emissão de uso em lote foi aceita e registrada no lado da Microsoft para processamento e faturamento posteriores. A lista de respostas é retornada com o status de cada evento individual no lote. Você deve iterar através da carga útil de resposta para entender as respostas para cada evento de uso individual enviado como parte do evento em lote.
Exemplo de carga útil de 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 BatchUsageEvent resposta da API:
| Código de estado | Description |
|---|---|
Accepted |
Aceito. |
Expired |
Uso expirado. |
Duplicate |
Uso duplicado fornecido. |
Error |
Código de erro. |
ResourceNotFound |
O recurso de uso fornecido é inválido. |
ResourceNotAuthorized |
Você não está autorizado a fornecer uso para este recurso. |
ResourceNotActive |
O recurso está suspenso ou nunca foi ativado. |
InvalidDimension |
A dimensão para a qual o uso é 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
Mau pedido. O lote continha mais de 25 eventos de uso.
Código: 403
Proibido. O token de autorização não é fornecido, é inválido ou expirou. Ou a solicitação está tentando acessar uma assinatura de uma oferta que foi publicada com uma ID de aplicativo Microsoft Entra diferente daquela usada para criar o token de autorização.
Faturação limitada recuperar eventos de utilização
Você pode chamar a API de eventos de uso para obter a lista de eventos de uso. Os ISVs podem usar essa API para ver os eventos de uso que foram postados por um determinado período de tempo configurável e qual o estado desses eventos no ponto 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 disponíveis |
| planId (opcional) | Padrão = todos disponíveis |
| dimensão (opcional) | Padrão = todos disponíveis |
| azureSubscriptionId (opcional) | Padrão = todos disponíveis |
| reconStatus (opcional) | Padrão = todos disponíveis |
Valores possíveis de reconStatus:
| ReconStatus | Description |
|---|---|
| Submetido | Ainda não processado pelo PC Analytics |
| Aceite | Compatível com o PC Analytics |
| Rejeitado | Rejeitado na calha. Entre em contato com o suporte da Microsoft para investigar a causa. |
| Incompatibilidade | As quantidades do MarketplaceAPI e do Partner Center Analytics são diferentes de zero, mas não correspondem |
Cabeçalhos de solicitação:
| Tipo do conteúdo | Usar application/json |
|---|---|
| X-MS-RequestID | Valor de string exclusivo (de preferência 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. Este 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 de API. O formato é Bearer <access_token> quando o valor do token é recuperado pelo editor. Para obter mais informações, consulte:
|
Respostas
Exemplos de carga útil 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
}
]
Submetido
[
{
"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: 403 Proibido. O token de autorização não é fornecido, é inválido ou expirou. Ou a solicitação está tentando acessar uma assinatura de uma oferta que foi publicada com uma ID de aplicativo Microsoft Entra diferente daquela usada para criar o token de autorização.
Melhores práticas de desenvolvimento e teste
Para testar a emissão do medidor personalizado, implemente a integração com a API de medição, crie um plano para sua oferta SaaS publicada com dimensões personalizadas definidas nela com preço zero por unidade. E publique esta oferta como pré-visualização para que apenas utilizadores limitados possam aceder e testar a integração.
Você também pode usar o plano privado para uma oferta ao vivo existente para limitar o acesso a esse plano durante o teste para um público limitado.
Obter suporte
Siga as instruções em Suporte para o programa de mercado comercial no Partner Center para entender as opções de suporte do editor e abrir um tíquete de suporte com a Microsoft.
Conteúdos relacionados
Para obter mais informações sobre APIs de serviço de monitorização, consulte Perguntas frequentes sobre APIs de serviço de medição do Marketplace.