Partilhar via

APIs de faturamento medido do Marketplace

  • Artigo

As APIs de faturação medida devem ser usadas quando o publicador cria as dimensões de medição personalizadas para uma oferta a ser publicada no Partner Center. A integração com as APIs de faturação com medição é necessária para qualquer oferta comprada que tenha um ou mais planos com dimensões personalizadas para registar eventos de utilização.

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 faturação medida 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 medida

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 utilização 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.

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

Parâmetros de consulta:

Parâmetro Recomendação
ApiVersion Utilize 2018-08-31.

Cabeçalhos de solicitação:

Tipo de conteúdo Use application/json
x-ms-requestid Valor de string único para o acompanhamento da 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 publicador, conforme explicado para

Exemplo do 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 Aplicações Geridas do Azure, o resourceId é a Aplicação Gerida resource group Id. Um script de exemplo para obtê-lo pode ser encontrado em usando o token de identidades gerenciadas pelo Azure.

Para ofertas de SaaS, o resourceId é o ID de assinatura SaaS. Para obter mais detalhes sobre assinaturas SaaS, consulte lista de assinaturas.

Respostas

Código: 200
OK. A emissão de uso foi aceite e registada pela 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
Pedido inválido.

  • 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: 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 daquele usado para criar o token de autenticação.

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou foi fornecido com permissões insuficientes. Certifique-se de fornecer 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 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 em lote de faturamento medido

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.

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

Parâmetros de consulta:

Parâmetro Recomendação
ApiVersion Utilize 2018-08-31.

Cabeçalhos de solicitação:

Tipo de conteúdo Utilize application/json
x-ms-requestid Valor de string exclusivo para rastrear o pedido 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 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 publicador, conforme explicado.

Observação

No corpo da solicitação, o identificador de recurso tem significados diferentes para a aplicação SaaS e para a aplicação gerida do Azure que emite um medidor personalizado. O identificador de recurso para SaaS App é resourceID. O identificador de recurso para planos de Aplicações Geridas do Azure é resourceUri. Para obter mais informações sobre identificadores de recursos, consulte Cobrança com Medição do Azure Marketplace - Selecionar o ID correto ao submeter eventos de utilização.

Para ofertas de SaaS, o resourceId é o ID de assinatura SaaS. Para obter mais detalhes sobre subscrições SaaS, consulte lista de subscrições.

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 Aplicações Geridas do Azure, o resourceUri é a Aplicação Gerida resourceUsageId. Um script de exemplo para obtê-lo pode ser encontrado em usando o token de identidades gerenciadas 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 percorrer a carga útil de resposta para compreender as respostas para cada evento individual de utilização 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 resposta da API BatchUsageEvent.

Código de status Descrição
Accepted Aceito.
Expired Uso expirado.
Duplicate Fornecido uso duplicado.
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 foi atribuído é 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
Pedido inválido. 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 daquele usado para criar o token de autenticação.

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou foi fornecido com permissões insuficientes. Certifique-se de fornecer um token de autorização válido.

Faturação medida obter 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.

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

Parâmetros de consulta:

Parâmetro Recomendação
ApiVersion Use 2018-08-31.
dataDeInícioDeUso 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 = todas as opções disponíveis
planId (opcional) Padrão = todos os disponíveis
dimensão (opcional) Padrão = todos os disponíveis
azureSubscriptionId (opcional) Configuração padrão: todos disponíveis
reconStatus (opcional) Padrão = todos os disponíveis

Valores possíveis de reconStatus:

ReconStatus Descrição
Submetido Ainda não processado pelo PC Analytics
Aceito Compatível com o PC Analytics
Rejeitado Rejeitado no fluxo de trabalho. 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 maiores que zero, contudo não correspondem

Cabeçalhos de solicitação:

Tipo de conteúdo Utilizar application/json
X-MS-RequestID Valor exclusivo de cadeia de caracteres (de preferência um GUID), para identificar 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 publicador. Para 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
  }
]

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 estado

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 daquele usado para criar o token de autenticação.

Código: 403 Proibido. O token de autorização é inválido, não foi fornecido ou foi fornecido com permissões insuficientes. Certifique-se de fornecer um token de autorização válido.

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 no Suporte para o programa de mercado comercial no Partner Center para entender as opções de suporte do fornecedor e abrir um pedido de suporte com a Microsoft.

Conteúdo relacionado

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