APIs de cobrança limitada do Marketplace

  • Artigo

As APIs de cobrança limitada devem ser usadas quando o publicador cria dimensões de medição personalizadas para uma oferta a ser publicada no Partner Center. A integração com essas APIs é necessária para qualquer oferta adquirida com um ou mais planos que tenham dimensões personalizadas para emitir eventos de uso.

Importante

Você precisa acompanhar o uso no código e apenas enviar eventos de uso à Microsoft em caso de uso acima do valor base.

Para obter mais informações sobre como criar dimensões de medição personalizadas para SaaS, consulte Cobrança limitada de SaaS.

Para saber mais sobre como criar dimensões de medição personalizadas para uma oferta de Aplicativo Azure com um plano de aplicativo gerenciado, consulte Configurar os detalhes de configuração da oferta de aplicativo do Azure.

Aplicando a nota TLS 1.2

A versão 1.2 do TLS é aplicada como a versão mínima para comunicações HTTPS. Use essa versão do TLS em seu código. As versões 1.0 e 1.1 do TLS são preteridas e as tentativas de conexão serão recusadas.

Evento de uso único de cobrança limitada

A API de evento de uso deve ser chamada pelo publicador para emitir eventos de uso em um recurso ativo (assinado) para o plano adquirido pelo cliente específico. O evento de uso é emitido separadamente para cada dimensão personalizada do plano definido pelo publicador ao publicar a oferta.

Somente um evento de uso pode ser emitido por hora durante um dia do calendário por recurso. Se mais de uma unidade for consumida em uma hora, acumule todas as unidades consumidas na hora e as emita em um único evento. Os eventos de uso só podem ser emitidos com relação às últimas 24 horas. Se você emitir um evento de uso a qualquer momento entre 8h00 e 8h59min59s (e ele for aceito) e enviar um evento adicional no mesmo dia entre 8h00 e 8h59min59s, ele será rejeitado como duplicado.

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:

Content-type Use application/json.
x-ms-requestid Valor de cadeia de caracteres exclusivo para acompanhamento da solicitação do cliente, preferencialmente 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 a 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, ele será gerado e fornecido nos cabeçalhos de resposta.
authorization Um token de acesso exclusivo que identifica o ISV que está fazendo a chamada à API. O formato é quando o valor do token é "Bearer <access_token>" recuperado pelo editor, 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 os planos de aplicativos gerenciados do aplicativo Azure, o resourceId é o aplicativo gerenciado resource group Id. Um script de exemplo para buscá-los pode ser encontrado em usando o token de identidades gerenciadas pelo Azure.

Para ofertas de SaaS, a resourceId é a ID de assinatura do SaaS. Para obter mais detalhes sobre assinaturas de SaaS, veja listar assinaturas.

Respostas

Código: 200
OK. A emissão de uso foi aceita e registrada no lado da Microsoft para processamento adicional 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 inválida.

  • Dados de solicitação ausentes ou inválidos foram fornecidos.
  • effectiveStartTime é mais de 24 horas no passado. O evento expirou.
  • A assinatura 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: 403

Negado. O token de autorização é inválido, expirou ou não foi fornecido. Ou a solicitação está tentando acessar uma assinatura de uma oferta que foi publicada com uma ID de aplicativo do Microsoft Entra diferente daquela usada para criar o token de autorização.

Código: 409
Conflito. Um evento de uso já foi relatado corretamente para o ID de recurso, a data e a hora de uso efetivo especificados.

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 de lote de cobrança limitada

A API de evento de uso em lote permite emitir eventos de uso para mais de um recurso adquirido por 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 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:

Content-type Use application/json.
x-ms-requestid Valor de cadeia de caracteres exclusivo para acompanhamento da solicitação do cliente, preferencialmente um GUID. Se esse valor não for fornecido, ele será gerado e fornecido nos cabeçalhos de resposta.
x-ms-correlationid Valor de cadeia de caracteres exclusivo para a 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, ele será gerado e fornecido nos cabeçalhos de resposta.
authorization Um token de acesso exclusivo que identifica o ISV que está fazendo a chamada à API. O formato é quando o valor do token é Bearer <access_token> recuperado pelo editor, conforme explicado para

Observação

No corpo da solicitação, o identificador de recurso tem significados diferentes para o aplicativo SaaS e para a emissão de medidor personalizado do aplicativo gerenciado do Azure. O identificador de recurso para o aplicativo SaaS é resourceID. O identificador de recurso para os planos de aplicativos gerenciados do Aplicativo Azure é resourceUri. Para obter mais informações sobre identificadores de recursos, consulte Cobrança limitada no Azure Marketplace: Escolher a ID correta ao enviar eventos de uso.

Para ofertas de SaaS, a resourceId é a ID de assinatura do SaaS. Para obter mais detalhes sobre assinaturas de SaaS, veja 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
    }
  ]
}

No caso dos planos de aplicativos gerenciados do aplicativo Azure, o resourceUri é o aplicativo gerenciado resourceUsageId. Um script de exemplo para buscá-los pode ser encontrado em usando o token de identidades gerenciadas pelo Azure.

Exemplo de corpo de solicitação para aplicativos gerenciados do Aplicativo 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 de lote foi aceita e registrada no lado da Microsoft para processamento adicional e cobrança. A lista de respostas é retornada com o status de cada evento individual no lote. Você deve iterar o conteúdo da resposta para entender as respostas de cada evento de uso individual enviado como parte do evento de 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 da API BatchUsageEvent:

Código de status Descrição
Accepted Aceita.
Expired Uso expirado.
Duplicate Uso duplicado fornecido.
Error Código do 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 foi passado é inválida para esta oferta/plano.
InvalidQuantity A quantidade transmitida é menor ou igual a 0.
BadArgument A entrada está ausente ou mal formulada.

Código: 400
Solicitação inválida. O lote continha mais de 25 eventos de uso.

Código: 403
Negado. O token de autorização é inválido, expirou ou não foi fornecido. Ou a solicitação está tentando acessar uma assinatura de uma oferta que foi publicada com uma ID de aplicativo do Microsoft Entra diferente daquela usada para criar o token de autorização.

Eventos de uso de recuperação de cobrança limitada

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 lançados por uma determinada duração configurável de tempo e qual estado esses eventos estão 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 os disponíveis
planId (opcional) Padrão = todos os disponíveis
dimension (opcional) Padrão = todos os disponíveis
azureSubscriptionId (opcional) Padrão = todos os disponíveis
reconStatus (opcional) Padrão = todos os disponíveis

Valores possíveis de reconStatus:

ReconStatus Descrição
Enviado Ainda não processados pela análise de PC
Accepted Correspondido com a análise de PC
Rejeitado Rejeitado no pipeline. Contate o suporte da Microsoft para investigar a causa.
Incompatibilidade As quantidades de análise do MarketplaceAPI e do Partner Center são diferentes de zero, mas não correspondem

Cabeçalhos de solicitação:

Tipo de conteúdo Usar application/json
x-ms-requestid Valor de cadeia de caracteres exclusivo (preferencialmente um GUID), para acompanhamento da solicitação do cliente. Se esse valor não for fornecido, ele será gerado e fornecido nos cabeçalhos de resposta.
x-ms-correlationid Valor de cadeia de caracteres exclusivo para a 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, ele será gerado e fornecido nos cabeçalhos de resposta.
autorização Um token de acesso exclusivo que identifica o ISV que está fazendo a chamada à API. O formato é Bearer <access_token> quando o valor do token é recuperado pelo editor. Para saber mais, veja:

Respostas

Exemplos de conteúdo da 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
  }
]

Recusado

[
  {
    "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 é inválido, expirou ou não foi fornecido. Ou a solicitação está tentando acessar uma assinatura de uma oferta que foi publicada com uma ID de aplicativo do Microsoft Entra diferente daquela usada para criar o token de autorização.

Práticas recomendadas de desenvolvimento e teste

Para testar a emissão de medidores personalizados, implemente a integração com a API de medição e crie um plano para sua oferta de SaaS publicada com dimensões personalizadas definidas com preço zero por unidade. Além disso, publique essa oferta como visualização para que apenas usuários limitados possam acessar e testar a integração.

Também é possível usar um plano privado para uma oferta dinâmica existente a fim de limitar o acesso a esse plano durante o teste para um público limitado.

Obter suporte

Siga a instrução em Suporte para o programa comercial do Marketplace no Partner Center para entender as opções de suporte do publicador e abrir o tíquete de suporte com a Microsoft.

Próximas etapas

Para obter mais informações sobre APIs de serviço de medição, consulte Perguntas frequentes sobre APIs do serviço de medição do Marketplace.