Partager via

API de la marketplace pour la facturation mesurée

  • Article

Les API de facturation au compteur doivent être utilisées lorsque l’éditeur crée des dimensions de contrôle personnalisées pour qu’une offre soit publiée dans Partner Center. L’intégration avec les API de facturation limitées est requise pour toute offre achetée qui a un ou plusieurs plans avec des dimensions personnalisées pour émettre des événements d’utilisation.

Important

Vous devez suivre l’utilisation dans votre code et envoyer uniquement des événements d’utilisation à Microsoft pour l’utilisation au-dessus des frais de base.

Pour plus d’informations sur la création de dimensions de mesure personnalisées pour SaaS, consultez facturation SaaS à la consommation.

Pour plus d’informations sur la création de dimensions de contrôle personnalisées pour une offre d’application Azure avec un plan d’application managée, consultez Configurer les détails de configuration de votre offre d’application Azure.


Application de TLS 1.2 Remarque

La version 1.2 de TLS est appliquée en tant que version minimale pour les communications HTTPS. Veillez à utiliser cette version TLS dans votre code. Tls version 1.0 et 1.1 sont déconseillées et les tentatives de connexion seront refusées.

Événement d'utilisation unique de facturation au compteur

L’API d’événement d’utilisation doit être appelée par l’éditeur pour émettre des événements d’utilisation sur une ressource active (abonnée) pour le plan acheté par le client spécifique. L’événement d’utilisation est émis séparément pour chaque dimension personnalisée du plan défini par l’éditeur lors de la publication de l’offre.

Un seul événement d’utilisation peut être émis pour chaque heure d’un jour de calendrier par ressource et dimension. Si plusieurs unités sont consommées en une heure, accumulez toutes les unités consommées dans l’heure, puis émettez-la dans un seul événement. Les événements d’utilisation ne peuvent être émis que pour les 24 dernières heures. Si vous émettez un événement d’utilisation à tout moment entre 8:00 et 8:59:59 (et qu’il est accepté) et envoyez un événement supplémentaire pour le même jour entre 8:00 et 8:59:59, il sera rejeté en tant que doublon.

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

paramètres de requête :

Paramètre Recommandation
ApiVersion Utilisez 2018-08-31.

En-têtes de requête HTTP :

Type de contenu Utiliser application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur unique de chaîne pour une opération côté client. Ce paramètre met en corrélation tous les événements de l’opération cliente avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Un jeton d'accès unique qui identifie l'éditeur de logiciels indépendants effectuant cet appel d'API. Le format est "Bearer <access_token>" lorsque la valeur du jeton est récupérée par l’éditeur, comme expliqué pour

Exemple de corps de la requête :

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

Pour les plans Azure Application Managed Apps, le resourceId est l’application managée resource group Id. Vous trouverez un exemple de script pour l’extraction dans à l’aide du jeton d’identités managées Azure.

Pour les offres SaaS, le resourceId est l’ID d’abonnement SaaS. Pour plus d’informations sur les abonnements SaaS, consultez liste des abonnements.

Réponses

Code : 200
D’ACCORD. Le rapport d'utilisation a été accepté et enregistré par Microsoft pour un traitement et une facturation supplémentaires.

Exemple de charge utile de réponse :

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

Code : 400
Demande incorrecte.

  • Données de requête manquantes ou non valides fournies.
  • effectiveStartTime remonte à il y a plus de 24 heures. L’événement a expiré.
  • L’abonnement SaaS n’est pas dans l’état Abonné.

Exemple de charge utile de réponse :

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

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. La demande tente d’accéder à un abonnement SaaS pour une offre publiée avec un ID d’application Microsoft Entra différent de celui utilisé pour créer le jeton d’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou a été fourni avec des autorisations insuffisantes. Veillez à fournir un jeton d’autorisation valide.

Code : 409
Conflit. Un événement d’utilisation a déjà été signalé pour l’ID de ressource spécifié, la date et l’heure d’utilisation effectives.

Exemple de charge utile de réponse :

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

Événement d’utilisation de traitement par lots en facturation à la consommation

L’API d’événement d’utilisation par lots vous permet d’émettre des événements d’utilisation pour plusieurs ressources achetées à la fois. Il vous permet également d’émettre plusieurs événements d’utilisation pour la même ressource tant qu’ils sont pour des heures de calendrier différentes. Le nombre maximal d’événements dans un lot unique est de 25.

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

Paramètres de requête:

Paramètre Recommandation
ApiVersion Utilisez 2018-08-31.

En-têtes de requête HTTP :

Type de contenu Utiliser application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur unique de chaîne pour une opération côté client. Ce paramètre met en corrélation tous les événements de l’opération cliente avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Un jeton d'accès unique qui identifie l'éditeur de logiciels indépendants effectuant cet appel d'API. Le format est Bearer <access_token> lorsque la valeur du jeton est récupérée par l’éditeur, comme expliqué pour

Remarque

Dans le corps de la demande, l’identificateur de ressource a différentes significations pour l’application SaaS et pour l’application managée Azure qui émet un compteur personnalisé. L’identificateur de ressource pour l’application SaaS est resourceID. L’identificateur de ressource pour les plans Azure Application Managed Apps est resourceUri. Pour plus d’informations sur les identificateurs de ressources, consultez Azure Marketplace facturation mesurée : sélection de l’ID correct lors de l’envoi d’événements d’utilisation.

Pour les offres SaaS, le resourceId est l’ID d’abonnement SaaS. Pour plus d’informations sur les abonnements SaaS, consultez liste des abonnements.

exemple de corps de requête pour les applications 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
    }
  ]
}

Pour les plans Azure Application Managed Apps, le resourceUri est l’application managée resourceUsageId. Vous trouverez un exemple de script pour l’extraction dans à l’aide du jeton d’identités managées Azure.

exemple de corps de requête pour les applications gérées par l’application 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
    }
  ]
}

Réponses

Code : 200
D’ACCORD. L’émission de l'utilisation par lot a été acceptée et enregistrée par Microsoft pour un traitement et une facturation supplémentaires. La liste de réponses est retournée avec l’état de chaque événement individuel dans le lot. Vous devez itérer au sein de la charge utile de réponse pour comprendre les réponses pour chaque événement d’utilisation individuel envoyé dans le cadre de l’événement de traitement par lots.

Exemple de charge utile de réponse :

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

Description du code d’état référencé dans BatchUsageEvent réponse de l’API :

Code de statut Description
Accepted Accepté.
Expired Utilisation expirée.
Duplicate Utilisation dupliquée fournie.
Error Code d’erreur.
ResourceNotFound La ressource d’utilisation fournie n’est pas valide.
ResourceNotAuthorized Vous n’êtes pas autorisé à fournir l’utilisation de cette ressource.
ResourceNotActive La ressource est suspendue ou n’a jamais été activée.
InvalidDimension La dimension pour laquelle l’utilisation est passée n’est pas valide pour cette offre ou ce forfait.
InvalidQuantity La quantité passée est inférieure ou égale à 0.
BadArgument L’entrée est manquante ou incorrecte.

Code : 400
Demande incorrecte. Le lot contenait plus de 25 événements d’utilisation.

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. La demande tente d’accéder à un abonnement SaaS pour une offre publiée avec un ID d’application Microsoft Entra différent de celui utilisé pour créer le jeton d’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou a été fourni avec des autorisations insuffisantes. Veillez à fournir un jeton d’autorisation valide.

La facturation au compteur récupérer les événements d’utilisation

Vous pouvez appeler l’API événements d’utilisation pour obtenir la liste des événements d’utilisation. Les éditeurs de logiciels indépendants peuvent utiliser cette API pour voir les événements d’utilisation qui ont été publiés pendant une certaine durée configurable et l’état de ces événements au moment de l’appel de l’API.

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

paramètres de requête:

Paramètre Recommandation
ApiVersion Utilisez 2018-08-31.
usageStartDate DateTime au format ISO8601. Par exemple, 2020-12-03T15:00 ou 2020-12-03
UsageEndDate (facultatif) DateTime au format ISO8601. Valeur par défaut = date actuelle
offerId (facultatif) Valeur par défaut = toutes les disponibilités
planId (facultatif) Valeur par défaut = toutes les disponibilités
dimension (facultatif) Valeur par défaut = toutes les disponibilités
azureSubscriptionId (facultatif) Valeur par défaut = toutes les disponibilités
reconStatus (facultatif) Valeur par défaut = toutes les disponibilités

Valeurs possibles de reconStatus:

ReconStatus Description
Envoyé Pas encore traité par PC Analytics
Accepté Corrélé avec PC Analytics
Rejeté Rejeté dans le pipeline. Contactez le support Microsoft pour examiner la cause.
Incompatibilité Les quantités MarketplaceAPI et Partner Center Analytics ne sont pas égales à zéro, mais elles ne correspondent pas

En-têtes de requête :

Type de contenu Utiliser l’application/json
x-ms-requestid Valeur de chaîne unique (de préférence un GUID), pour le suivi de la requête du client. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération côté client. Ce paramètre met en corrélation tous les événements de l’opération cliente avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
autorisation Jeton d’accès unique qui identifie l'ISV effectuant cet appel d’API. Le format est Bearer <access_token> lorsque la valeur du jeton est récupérée par l’éditeur. Pour plus d’informations, consultez :

Réponses

Exemples de charge utile de réponse :

* accepté

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

Soumis

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

Incompatibilité

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

Rejeté

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

codes d’état

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. La demande tente d’accéder à un abonnement SaaS pour une offre publiée avec un ID d’application Microsoft Entra différent de celui utilisé pour créer le jeton d’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou a été fourni avec des autorisations insuffisantes. Veillez à fournir un jeton d’autorisation valide.

Bonnes pratiques de développement et de test

Pour tester l’émission de compteur personnalisée, implémentez l’intégration à l’API de contrôle, créez un plan pour votre offre SaaS publiée avec des dimensions personnalisées définies dans celle-ci avec un prix zéro par unité. Et publiez cette offre en préversion afin que seuls les utilisateurs limités soient en mesure d’accéder à l’intégration et de tester l’intégration.

Vous pouvez également utiliser un plan privé pour une offre en direct existante afin de limiter l'accès à ce plan à un public limité pendant les tests.

Obtenir du support

Suivez les instructions de Support pour le programme de la Place de marché commerciale dans l’Espace partenaires pour comprendre les options de support de l’éditeur et ouvrir un ticket de support auprès de Microsoft.

Contenu connexe

Pour plus d’informations sur les API de service de mesure, consultez la FAQ sur les API de service de mesure de la Marketplace.