APIs de faturamento medido do Marketplace

As APIs de faturação por medida devem ser usadas quando o publicador cria dimensões personalizadas de medição 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 saber como criar dimensões de medição personalizadas para SaaS, consulte Faturamento medido por SaaS.

Para saber como configurar a medição personalizada para um aplicativo do Azure com um plano gerenciado, consulte Configurar os detalhes da configuração da oferta do 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 uso único com faturação baseada no consumo

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.

CORREIO: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	Utilize application/json
x-ms-requestid	Valor único de cadeia para rastrear a 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 string 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 SaaS em Obtenha o token com um HTTP POST. Aplicação gerida em estratégias de autenticação.

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 ocorreu há mais de 24 horas. 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.

Código: 500 Erro interno do servidor. Tente novamente a chamada de API. Se o erro persistir, contacte de suporte da Microsoft .

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 único de cadeia para rastrear a 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 string 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 SaaS em Obtenha o token com um HTTP POST. Aplicação gerida em estratégias de autenticação.

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 assinaturas SaaS, consulte lista de 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 os planos de aplicações de gestão do Azure, o resourceUri é a aplicação de gestão 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 analisar a carga de respostas para entender as respostas para cada evento de uso individual enviado como parte do lote de eventos.

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

Código: 500 Erro interno do servidor. Tente novamente a chamada de API. Se o erro persistir, contacte de suporte da Microsoft .

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?api-version=<ApiVersion>&usageStartDate=<usageStartDate>

Parâmetros de consulta:

Parâmetro	Recomendação
ApiVersion	Utilize 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 = todas as opções disponíveis
dimensão (opcional)	Padrão = todas as opções disponíveis
azureSubscriptionId (opcional)	Padrão = todas as opções disponíveis
reconStatus (opcional)	Padrão = todas as opções 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 diferentes de zero, contudo, não coincidem.

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 string 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: SaaS em Obtenha o token com HTTP POST Aplicativo gerenciado em estratégias de autenticação

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.

Código: 500 Erro interno do servidor. Tente novamente a chamada de API. Se o erro persistir, contacte de suporte da Microsoft .

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.