Comparteix a través de

API de facturación de uso medido de marketplace

  • Article

Las API de facturación de uso medido se deben usar cuando el publicador crea dimensiones de medición personalizadas para que una oferta que se va a publicar en el Centro de partners. La integración con las API de facturación de uso medido es necesaria para cualquier oferta comprada que tenga uno o varios planes con dimensiones personalizadas para emitir eventos de uso.

Importante

Debe realizar un seguimiento del uso en su código y enviar solo eventos de uso a Microsoft para el uso que supere la tarifa base.

Para más información sobre cómo crear dimensiones de medición personalizadas para SaaS, vea Facturación de uso medido de SaaS.

Para más información sobre cómo crear dimensiones de medición personalizadas para una oferta de aplicación de Azure con un plan de aplicación gestionado, consulte los detalles de configuración de la oferta de aplicación de Azure .


Aplicación de TLS 1.2 Nota

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

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

El publicador debe llamar a la API de eventos de uso para emitir eventos de uso en un recurso activo (suscrito) para el plan comprado 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 para cada hora de un día natural por recurso y dimensión. Si se consume más de una unidad en una hora, acumula todas las unidades consumidas en la hora y, a continuación, la emite 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 para 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 solicitud:

Tipo de contenido Uso de application/json
x-ms-requestid Valor de cadena único para realizar 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 correlaciona todos los eventos de la operación de cliente con eventos en el lado 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 el ISV que realiza esta llamada API. El formato es "Bearer <access_token>" cuando el publicador recupera el valor del token, como se explica para

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 el caso de los planes de Aplicaciones Administradas de Azure, resourceId es la aplicación administrada resource group Id. Puede encontrar un script de ejemplo para obtenerlo en mediante el token de identidades administradas de Azure.

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

Respuestas

Código: 200
De acuerdo. La emisión de uso fue aceptada y registrada por parte de Microsoft para su procesamiento y facturación posterior.

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.

  • Faltan datos de solicitud o son inválidos.
  • effectiveStartTime es de hace más de 24 horas. El evento ha expirado.
  • La suscripción de SaaS no está en el 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: 401 No autorizado. El token de autorización no es válido o ha expirado. La solicitud intenta acceder a una suscripción de SaaS para una oferta publicada con un identificador de aplicación de Microsoft Entra diferente del que se usa para crear el token de autenticación.

Código: 403 Prohibido. El token de autorización no es válido, no se proporcionó o se proporcionó con permisos insuficientes. Asegúrese de proporcionar un token de autorización válido.

Código: 409
Conflicto. Ya se ha notificado correctamente un evento de uso para el identificador de recurso especificado, la fecha de uso efectivo y la hora especificados.

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 de uso medido

La API de eventos de uso por lotes permite emitir eventos de uso para más de un recurso comprado a la vez. 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.

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

Parámetros de consulta:

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

Encabezados de solicitud:

Tipo de contenido Utilice application/json
x-ms-requestid Valor de cadena único para realizar 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 correlaciona todos los eventos de la operación de cliente con eventos en el lado 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 el ISV que realiza esta llamada API. El formato es Bearer <access_token> cuando el publicador recupera el valor del token, como se explica para

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 un medidor personalizado. El identificador de recursos de la aplicación SaaS es resourceID. El identificador de recursos de los planes de Azure Application Managed Apps es resourceUri. Para más información sobre los identificadores de recursos, consulte Facturación de uso medido de Azure Marketplace: selección del identificador correcto al enviar eventos de uso.

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

Ejemplo de cuerpo de la solicitud de 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 el caso de los planes de aplicaciones administradas de Azure, resourceUri es la aplicación administrada resourceUsageId. Puede encontrar un script de ejemplo para obtenerlo en mediante el token de identidades administradas de Azure.

Ejemplo del cuerpo de la solicitud para 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
De acuerdo. La emisión de uso por lotes se aceptó y registró en Microsoft para su posterior procesamiento y facturación. La lista de respuestas se devuelve con el estado de cada evento individual del lote. Debe iterar por la carga de respuesta para comprender las respuestas de cada evento de uso individual enviado 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 mencionado en la respuesta de la API BatchUsageEvent.

Código de estado Descripción
Accepted Aceptado.
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 se suspende o nunca se ha activado.
InvalidDimension La dimensión para la que se ha proporcionado el uso no es válida para esta oferta o plan.
InvalidQuantity La cantidad pasada es menor o igual a 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: 401 No autorizado. El token de autorización no es válido o ha expirado. La solicitud intenta acceder a una suscripción de SaaS para una oferta publicada con un identificador de aplicación de Microsoft Entra diferente del que se usa para crear el token de autenticación.

Código: 403 Prohibido. El token de autorización no es válido, no se proporcionó o se proporcionó con permisos insuficientes. Asegúrese de proporcionar un token de autorización válido.

Eventos de uso de recuperación de facturación de uso medido

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 una determinada duración configurable de tiempo y qué estado están 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 = todo disponible
planId (opcional) Valor predeterminado = todo disponible
dimensión (opcional) Valor predeterminado = todo disponible
azureSubscriptionId (opcional) Valor predeterminado = todo disponible
reconStatus (opcional) Valor predeterminado = todo disponible

Valores posibles de reconStatus:

ReconStatus Descripción
Presentado Aún no procesado por PC Analytics
Aceptado Coincide con PC Analytics
Rechazado Rechazado en la canalización. Póngase en contacto con el soporte técnico de Microsoft para investigar la causa.
Desajuste Las cantidades de MarketplaceAPI y Partner Center Analytics no son cero, pero no coinciden.

Encabezados de solicitud:

Tipo de contenido Uso de application/json
x-ms-requestid Valor de cadena único (preferiblemente un GUID) para realizar el seguimiento de la solicitud desde el cliente. 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 correlaciona todos los eventos de la operación de cliente con eventos en el lado servidor. Si no se proporciona este valor, se generará uno y se proporcionará en los encabezados de respuesta.
autorización Token de acceso único que identifica el ISV que realiza esta llamada API. El formato es Bearer <access_token> cuando el publicador recupera el valor del token. Para obtener más información, consulte:

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

Error de coincidencia 

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

Rechazado

[
  {
    "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 No autorizado. El token de autorización no es válido o ha expirado. La solicitud intenta acceder a una suscripción de SaaS para una oferta publicada con un identificador de aplicación de Microsoft Entra diferente del que se usa para crear el token de autenticación.

Código: 403 Prohibido. El token de autorización no es válido, no se proporcionó o se proporcionó con permisos insuficientes. Asegúrese de proporcionar un token de autorización válido.

Procedimientos recomendados de desarrollo y pruebas

Para probar la emisión de medidores personalizados, implemente la integración con la API de medición, cree un plan para la oferta de SaaS publicada con dimensiones personalizadas definidas en ella con un precio cero por unidad. Y publique esta oferta como versión preliminar para que solo los usuarios limitados puedan acceder y probar la integración.

También puede usar un plan privado para una oferta activa existente a fin de limitar el acceso a este plan durante las pruebas a un público limitado.

Obtener soporte técnico

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

Contenido relacionado

Para más información sobre las API del servicio de medición, consulte Preguntas Frecuentes sobre las API del servicio de medición de Marketplace.