API de facturación según uso de Marketplace

  • Artículo

Las API de facturación según uso deben usarse cuando el publicador crea dimensiones de medición personalizadas para que una oferta se publique en el Centro de partners. La integración con las API de facturación según uso es necesaria para cualquier oferta comprada que tenga uno o más planes con dimensiones personalizadas para emitir eventos de uso.

Importante

Debe realizar un seguimiento del uso en el código y enviar solo eventos de uso a Microsoft para el uso que esté por encima del precio base.

Para obtener más información sobre cómo crear dimensiones de medición personalizadas para SaaS, consulte Facturación según uso de SaaS.

Para obtener más información sobre cómo crear dimensiones de medición personalizadas para una oferta aplicación de Azure con un plan de aplicaciones administradas, consulte Configuración de las opciones de la oferta de la aplicación de Azure.

Nota sobre la aplicación de TLS 1.2

La versión 1.2 de TLS se aplica como versión mínima para las comunicaciones HTTPS. Asegúrese de usar esta versión de TLS en el código. Las versiones 1.0 y 1.1 están en desuso y se rechazarán los intentos de conexión.

Evento de uso único de facturación según uso

El publicador debe llamar a la API de eventos de uso para emitir eventos de uso en un recurso activo (suscrito) para el plan adquirido por el cliente específico. El evento de uso se emite por separado para cada dimensión personalizada del plan definido por el publicador al publicar la oferta.

Solo se puede emitir un evento de uso durante cada hora de un día natural por recurso y dimensión. Si se consume más de una unidad en una hora, acumule todas las unidades consumidas en la hora y, a continuación, proceda a su emisión en un solo evento. Los eventos de uso solo se pueden emitir durante las últimas 24 horas. Si emite un evento de uso en cualquier momento entre las 8:00 y las 8:59:59 (y se acepta) y envía un evento adicional durante el mismo día entre las 8:00 y las 8:59:59, se rechazará como duplicado.

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

Parámetros de consulta:

Parámetro Recomendación
ApiVersion Use 2018-08-31.

Encabezados de la solicitud:

Content-type Use application/json
x-ms-requestid Valor de cadena único para el seguimiento de la solicitud del cliente, preferiblemente un GUID. Si no se proporciona este valor, se generará uno y se proporcionará en los encabezados de respuesta.
x-ms-correlationid Valor de cadena único para la operación en el cliente. Este parámetro pone en correlación todos los eventos de la operación del cliente con los eventos del servidor. Si este valor no se proporciona, se generará uno y se proporcionará en los encabezados de respuesta.
authorization Token de acceso único que identifica al ISV que realiza esta llamada API. El formato es "Bearer <access_token>" cuando el publicador recupera el valor del token, como se explica en

Ejemplo de cuerpo de la solicitud:

{
  "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
}

En los planes de aplicaciones administradas de Azure, resourceId es el valor de resource group Id de la aplicación administrada. Se puede encontrar un script de ejemplo de captura en uso del token de identidades administradas por Azure.

En el caso de las ofertas de SaaS, resourceId es el id. de suscripción de SaaS. Para obtener más información sobre las suscripciones de SaaS, consulte lista de suscripciones.

Respuestas

Código: 200
Aceptar. La emisión de uso se aceptó y registró en el lado de Microsoft para su posterior procesamiento y facturación.

Ejemplo de carga de respuesta:

{
  "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
Solicitud incorrecta.

  • Datos de la solicitud no válidos proporcionados o que faltan.
  • effectiveStartTime es más de 24 horas en el pasado. El evento ha expirado.
  • La suscripción de SaaS no está en estado suscrito.

Ejemplo de carga de respuesta:

{
  "message": "One or more errors have occurred.",
  "target": "usageEventRequest",
  "details": [
    {
      "message": "The resourceId is required.",
      "target": "ResourceId",
      "code": "BadArgument"
    }
  ],
  "code": "BadArgument"
}

Código: 403

Prohibido. El token de autorización no se ha proporcionado, no es válido o ha expirado, O bien, la solicitud intenta acceder a una suscripción para una oferta publicada con un identificador de aplicación de Microsoft Entra diferente del que se usa para crear el token de autorización.

Código: 409
Conflicto. Ya se ha notificado correctamente un evento de uso para el id. de recurso especificado, la fecha y la hora de entrada en vigor del uso.

Ejemplo de carga de respuesta:

{
  "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 por lotes de facturación según uso

La API de eventos de uso por lotes permite emitir a la vez eventos de uso para más de un recurso específico que haya comprado. También permite emitir varios eventos de uso para el mismo recurso, siempre y cuando estén durante diferentes horas naturales. El número máximo de eventos en un solo lote es 25.

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

Parámetros de consulta:

Parámetro Recomendación
ApiVersion Use 2018-08-31.

Encabezados de la solicitud:

Content-type Use application/json
x-ms-requestid Valor de cadena único para el seguimiento de la solicitud del cliente, preferiblemente un GUID. Si no se proporciona este valor, se generará uno y se proporcionará en los encabezados de respuesta.
x-ms-correlationid Valor de cadena único para la operación en el cliente. Este parámetro pone en correlación todos los eventos de la operación del cliente con los eventos del servidor. Si no se proporciona este valor, se generará uno y se proporcionará en los encabezados de respuesta.
authorization Token de acceso único que identifica al ISV que realiza esta llamada API. El formato es Bearer <access_token> cuando el publicador recupera el valor del token, como se explica en

Nota:

En el cuerpo de la solicitud, el identificador de recurso tiene significados diferentes para la aplicación SaaS y para la aplicación administrada de Azure que emite medidor el personalizado. El identificador de recurso de la aplicación SaaS es resourceID. El identificador de recurso de los planes de aplicaciones administradas de Azure es resourceUri. Para obtener más información sobre los identificadores de recursos, consulte Azure Marketplace facturación de uso medido: selección del identificador correcto al enviar eventos de uso.

En el caso de las ofertas de SaaS, resourceId es el id. de suscripción de SaaS. Para obtener más información sobre las suscripciones de SaaS, consulte lista de suscripciones.

Ejemplo de cuerpo de solicitud para aplicaciones 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
    }
  ]
}

En los planes de aplicaciones administradas de Azure, el resourceUri es la aplicación administradaresourceUsageId. Se puede encontrar un script de ejemplo de captura en uso del token de identidades administradas por Azure.

Ejemplo de cuerpo de la solicitud de aplicaciones administradas de 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
    }
  ]
}

Respuestas

Código: 200
Aceptar. La emisión de uso por lotes se aceptó y registró en el lado de Microsoft para su posterior procesamiento y facturación. La lista de respuestas se devuelve con el estado de cada evento individual del lote. Debe recorrer en iteración la carga de respuesta para comprender las respuestas de cada evento de uso individual que se envía como parte del evento por lotes.

Ejemplo de carga de respuesta:

{
  "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"
    }
  ]
}

Descripción del código de estado al que se hace referencia en respuesta de la API BatchUsageEvent:

status code Descripción
Accepted Accepted.
Expired Uso expirado.
Duplicate Se ha proporcionado un uso duplicado.
Error Código de error.
ResourceNotFound El recurso de uso proporcionado no es válido.
ResourceNotAuthorized No está autorizado a proporcionar el uso de este recurso.
ResourceNotActive El recurso está suspendido o nunca se activó.
InvalidDimension La dimensión para la que se ha pasado el uso no es válida para esta oferta o plan.
InvalidQuantity La cantidad pasada es menor o igual que 0.
BadArgument Falta la entrada o tiene un formato incorrecto.

Código: 400
Solicitud incorrecta. El lote contenía más de 25 eventos de uso.

Código: 403
Prohibido. El token de autorización no se ha proporcionado, no es válido o ha expirado, O bien, la solicitud intenta acceder a una suscripción para una oferta publicada con un identificador de aplicación de Microsoft Entra diferente del que se usa para crear el token de autorización.

Facturación medida: recuperación de eventos de uso

Puede llamar a la API de eventos de uso para obtener la lista de eventos de uso. Los ISV pueden usar esta API para ver los eventos de uso que se han publicado durante un determinado período de tiempo configurable y qué estado tienen estos eventos en el momento de llamar a la API.

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

Parámetros de consulta:

Parámetro Recomendación
ApiVersion Use 2018-08-31.
usageStartDate DateTime en formato ISO8601. Por ejemplo, 2020-12-03T15:00 o 2020-12-03
UsageEndDate (opcional) DateTime en formato ISO8601. Valor predeterminado = fecha actual
offerId (opcional) Valor predeterminado = todos los disponibles
planId (opcional) Valor predeterminado = todos los disponibles
dimension (opcional) Valor predeterminado = todos los disponibles
azureSubscriptionId (opcional) Valor predeterminado = todos los disponibles
reconStatus (opcional) Valor predeterminado = todos los disponibles

Valores posibles de ReconStatus:

ReconStatus Descripción
Enviado Aún no procesado por PC Analytics
Aceptadas Coincidencia con PC Analytics
Rechazada Rechazado en la canalización. Póngase en contacto con el soporte técnico de Microsoft para investigar la causa.
Error de coincidencia Tanto las cantidades de MarketplaceAPI como del análisis del centro de partners son diferentes de cero, pero no coinciden

Encabezados de la solicitud:

Content type Usar application/json
x-ms-requestid Valor de cadena único (preferiblemente un GUID) para el seguimiento de la solicitud del cliente. Si este valor no se proporciona, se generará uno y se proporcionará en los encabezados de respuesta.
x-ms-correlationid Valor de cadena único para la operación en el cliente. Este parámetro pone en correlación todos los eventos de la operación del cliente con los eventos del servidor. Si este valor no se proporciona, se generará uno y se proporcionará en los encabezados de respuesta.
authorization Token de acceso único que identifica al ISV que realiza esta llamada API. El formato es Bearer <access_token> cuando el publicador recupera el valor del token. Para más información, vea:

Respuestas

Ejemplos de carga de respuesta:

Aceptado*

[
  {
    "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
  }
]

Desajuste

[
  {
    "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
  }
]

Rechazada

[
  {
    "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: 403 Prohibido. El token de autorización no se ha proporcionado, no es válido o ha expirado, O bien, la solicitud intenta acceder a una suscripción para una oferta publicada con un identificador de aplicación de Microsoft Entra diferente del que se usa para crear el token de autorización.

Procedimientos recomendados de desarrollo y pruebas

Para probar la emisión del medidor personalizada, implemente la integración con la API de medición y cree un plan para la oferta de SaaS publicada con dimensiones personalizadas definidas en él con un precio de cero por unidad. Además, publique esta oferta como versión preliminar. De este modo, solo los usuarios limitados podrán acceder a la integración y probarla.

También puede usar el plan privado para que una oferta activa existente limite el acceso a este plan durante las pruebas a una audiencia limitada.

Obtención de soporte técnico

Siga las instrucciones de Soporte técnico para el programa de marketplace comercial en el Centro de partners para conocer las opciones de soporte técnico para publicadores y abrir una incidencia de soporte técnico con Microsoft.

Pasos siguientes

Para obtener más información sobre las API del servicio de medición, consulte las preguntas más frecuentes de las API del servicio de medición de Marketplace.