APIs für getaktete Abrechnung im Marketplace

  • Artikel

Die APIs für getaktete Abrechnung sollten verwendet werden, wenn der Herausgeber benutzerdefinierte Messungsdimensionen für ein Angebot erstellt, das im Partner Center veröffentlicht werden soll. Für alle erworbenen Angebote, die über einen oder mehrere Pläne mit benutzerdefinierten Dimensionen zur Ausgabe von Nutzungsereignissen verfügen, ist eine Integration in die APIs für getaktete Abrechnung erforderlich.

Wichtig

Sie müssen die Nutzung in Ihrem Code nachverfolgen und nur für die Nutzung, die über der Grundgebühr liegt, Nutzungsereignisse an Microsoft senden.

Weitere Informationen zum Erstellen benutzerdefinierter Messungsdimensionen für SaaS finden Sie unter Getaktete SaaS-Abrechnung.

Weitere Informationen zum Erstellen benutzerdefinierter Messungsdimensionen für ein Azure-Anwendungsangebot mit einem Plan für verwaltete Apps finden Sie unter Konfigurieren der Details der Einrichtung Ihres Azure-Anwendungsangebots.


Hinweis zum Erzwingen von TLS 1.2

Die TLS-Version 1.2 wird als Mindestversion für die HTTPS-Kommunikation erzwungen. Stellen Sie sicher, dass Sie diese TLS-Version in Ihrem Code verwenden. TLS-Version 1.0 und 1.1 sind veraltet, und Verbindungsversuche werden abgelehnt.

Einzelnes Nutzungsereignis für getaktete Abrechnung

Die API für Nutzungsereignisse sollte vom Herausgeber aufgerufen werden, um Nutzungsereignisse für eine aktive Ressource (abonniert) für den vom jeweiligen Kunden erworbenen Plan auszugeben. Das Nutzungsereignis wird für jede benutzerdefinierte Dimension des Plans, die vom Herausgeber bei Veröffentlichung des Angebots definiert wurde, separat ausgegeben.

Für jede Stunde eines Kalendertags kann pro Ressource und Dimension nur ein Nutzungsereignis ausgegeben werden. Wenn mehr als eine Einheit in einer Stunde verwendet wird, sammeln Sie alle in dieser Stunde verwendeten Einheiten, und geben Sie diese dann in einem einzelnen Ereignis aus. Nutzungsereignisse können nur für die letzten 24 Stunden ausgegeben werden. Wenn Sie ein Nutzungsereignis zu einem Zeitpunkt zwischen 8:00 Uhr und 8:59:59 Uhr ausgeben (und es akzeptiert wird) und ein zusätzliches Ereignis für denselben Tag zwischen 8:00 und 8:59:59 senden, wird es als Duplikat zurückgewiesen.

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

Abfrageparameter:

Parameter Empfehlung
ApiVersion Verwenden Sie 2018-08-31.

Anforderungsheader:

Inhaltstyp Verwenden Sie application/json
x-ms-requestid Eindeutiger Zeichenfolgenwert für die Nachverfolgung der Anforderung vom Client, vorzugsweise eine GUID. Wenn dieser Wert nicht angegeben wird, wird einer generiert und in den Antwortheadern bereitgestellt.
x-ms-correlationid Eindeutiger Zeichenfolgenwert für den Vorgang auf dem Client. Dieser Parameter korreliert alle Ereignisse des Clientvorgangs mit serverseitigen Ereignissen. Wenn dieser Wert nicht angegeben wird, wird einer generiert und in den Antwortheadern bereitgestellt.
authorization Ein eindeutiges Zugriffstoken, das den ISV identifiziert, der diesen API-Aufruf sendet. Das Format ist "Bearer <access_token>" , wenn der Tokenwert vom Herausgeber wie erläutert abgerufen wird

Beispiel für Anforderungstext:

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

Bei von Azure-Anwendungen verwalteten App-Plänen ist resourceId die resource group Id der verwalteten App. Ein Beispielskript zum Abrufen der ID finden Sie unter Verwenden des Tokens für von Azure verwaltete Identitäten.

Bei SaaS-Angeboten ist resourceId die SaaS-Abonnement-ID. Weitere Informationen zu SaaS-Abonnements finden Sie unter Auflisten von Abonnements.

Antworten

Code: 200
OK. Die Nutzungsausgabe wurde auf Microsoft-Seite zur weiteren Verarbeitung und Abrechnung akzeptiert und aufgezeichnet.

Beispiel einer Antwortnutzlast:

{
  "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
Ungültige Anforderung.

  • Es wurden fehlende oder ungültige Anforderungsdaten bereitgestellt.
  • effectiveStartTime liegt mehr als 24 Stunden in der Vergangenheit. Das Ereignis ist abgelaufen.
  • SaaS-Abonnement befindet sich nicht im Status "Abonniert".

Beispiel einer Antwortnutzlast:

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

Code: 403

Unzulässig. Das Autorisierungstoken wurde nicht angegeben, ist ungültig oder abgelaufen. Oder die Anforderung versucht, auf ein Abonnement für ein Angebot zuzugreifen, das mit einer anderen Microsoft Entra App-ID veröffentlicht wurde als die, die zum Erstellen des Autorisierungstokens verwendet wurde.

Code: 409
Konflikt. Es wurde bereits erfolgreich ein Nutzungsereignis für die angegebene Ressourcen-ID sowie Datum und Stunde der Nutzung gemeldet.

Beispiel einer Antwortnutzlast:

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

Batchnutzungsereignis für getaktete Abrechnung

Mit der API für Batchnutzungsereignisse können Sie Nutzungsereignisse gleichzeitig für mehr als eine erworbene Ressource ausgeben. Außerdem können Sie mehrere Verwendungsereignisse für dieselbe Ressource ausgeben, solange sie sich für unterschiedliche Kalenderstunden befinden. Die maximale Anzahl von Ereignissen in einem einzelnen Batch beträgt 25.

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

Abfrageparameter:

Parameter Empfehlung
ApiVersion Verwenden Sie 2018-08-31.

Anforderungsheader:

Inhaltstyp Verwenden Sie application/json
x-ms-requestid Eindeutiger Zeichenfolgenwert für die Nachverfolgung der Anforderung vom Client, vorzugsweise eine GUID. Wenn dieser Wert nicht angegeben wird, wird einer generiert und in den Antwortheadern bereitgestellt.
x-ms-correlationid Eindeutiger Zeichenfolgenwert für den Vorgang auf dem Client. Dieser Parameter korreliert alle Ereignisse des Clientvorgangs mit serverseitigen Ereignissen. Wenn dieser Wert nicht angegeben wird, wird einer generiert und in den Antwortheadern bereitgestellt.
authorization Ein eindeutiges Zugriffstoken, das den ISV identifiziert, der diesen API-Aufruf sendet. Das Format ist Bearer <access_token> , wenn der Tokenwert vom Herausgeber wie erläutert abgerufen wird

Hinweis

Im Anforderungstext besitzt der Ressourcenbezeichner unterschiedliche Bedeutungen für SaaS-Apps und für verwaltete Azure-Apps, die eine benutzerdefinierte Verbrauchseinheit ausgeben. Der Ressourcenbezeichner für die SaaS-App lautet resourceID. Der Ressourcenbezeichner für Pläne verwalteter Azure-Anwendungs-Apps lautet resourceUri. Weitere Informationen zu Ressourcenbezeichnern finden Sie unter Getaktete Abrechnung im Azure Marketplace: Auswählen der richtigen ID beim Übermitteln von Nutzungsereignissen.

Bei SaaS-Angeboten ist resourceId die SaaS-Abonnement-ID. Weitere Informationen zu SaaS-Abonnements finden Sie unter Auflisten von Abonnements.

Beispiel für Anforderungstext für SaaS-Apps:

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

Bei Plänen verwalteter Azure-Anwendungs-Apps ist resourceUri die resourceUsageId der verwalteten Anwendung. Ein Beispielskript zum Abrufen der ID finden Sie unter Verwenden des Tokens für von Azure verwaltete Identitäten.

Beispiel für Anforderungstext für verwaltete Azure-Anwendungs-Apps:

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

Antworten

Code: 200
OK. Die Batchnutzungsausgabe wurde auf Microsoft-Seite zur weiteren Verarbeitung und Abrechnung akzeptiert und aufgezeichnet. Die Antwortliste wird mit dem Status für jedes einzelne Ereignis im Batch zurückgegeben. Sie sollten die Antwortnutzlast durchlaufen, um die Antworten für jedes einzelne Nutzungsereignis zu verstehen, das als Teil des Batchereignisses gesendet wird.

Beispiel einer Antwortnutzlast:

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

Beschreibung des Statuscodes, der in der BatchUsageEvent-API-Antwort angegeben ist:

Statuscode Beschreibung
Accepted Akzeptiert:
Expired Abgelaufene Nutzung.
Duplicate Doppelte Nutzung angegeben.
Error Fehlercode
ResourceNotFound Die angegebene Nutzungsressource ist ungültig.
ResourceNotAuthorized Sie sind nicht berechtigt, die Verwendung für diese Ressource bereitzustellen.
ResourceNotActive Die Ressource wird angehalten oder wurde nie aktiviert.
InvalidDimension Die Dimension, für die die Nutzung übergeben wird, ist für dieses Angebot bzw. diesen Plan ungültig.
InvalidQuantity Die übergebene Menge ist kleiner oder gleich 0 (null).
BadArgument Die Eingabe fehlt oder ist falsch formatiert.

Code: 400
Ungültige Anforderung. Der Batch enthielt mehr als 25 Nutzungsereignisse.

Code: 403
Unzulässig. Das Autorisierungstoken wurde nicht angegeben, ist ungültig oder abgelaufen. Oder die Anforderung versucht, auf ein Abonnement für ein Angebot zuzugreifen, das mit einer anderen Microsoft Entra App-ID veröffentlicht wurde als die, die zum Erstellen des Autorisierungstokens verwendet wurde.

Getaktete Abrechnung für das Abrufen von Nutzungsereignissen

Sie können die API für Nutzungsereignisse aufrufen, um die Liste der Nutzungsereignisse abzurufen. ISVs können diese API verwenden, um die Nutzungsereignisse anzuzeigen, die für einen bestimmten konfigurierbaren Zeitraum gesendet wurden, und welchen Status diese Ereignisse zum Zeitpunkt des Aufrufs der API aufweisen.

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

Abfrageparameter:

Parameter Empfehlung
ApiVersion Verwenden Sie 2018-08-31.
usageStartDate Ein DateTime-Wert im ISO 8601-Format. Beispiel: „2020-12-03T15:00“ oder „2020-12-03“
UsageEndDate (optional) Ein DateTime-Wert im ISO 8601-Format. Standard = Aktuelles Datum
offerId (optional) Standard = alle verfügbar
planId (optional) Standard = alle verfügbar
dimension (optional) Standard = alle verfügbar
azureSubscriptionId (optional) Standard = alle verfügbar
reconStatus (optional) Standard = alle verfügbar

Mögliche Werte von reconStatus:

ReconStatus Beschreibung
Gesendet Noch nicht von Partner Center Analytics verarbeitet
Zulässig Mit Partner Center Analytics abgeglichen
Rejected (Abgelehnt) In der Pipeline abgelehnt. Wenden Sie sich an den Microsoft-Support, um die Ursache zu untersuchen.
Konflikt MarketplaceAPI- und Partner Center Analytics-Mengen sind beide ungleich null, sind jedoch nicht aufeinander abgeglichen.

Anforderungsheader:

Inhaltstyp Verwendung von „application/json“
x-ms-requestid Eindeutiger Zeichenfolgenwert (vorzugsweise eine GUID) für die Nachverfolgung der Anforderung vom Client. Wenn dieser Wert nicht angegeben wird, wird einer generiert und in den Antwortheadern bereitgestellt.
x-ms-correlationid Eindeutiger Zeichenfolgenwert für den Vorgang auf dem Client. Dieser Parameter korreliert alle Ereignisse des Clientvorgangs mit serverseitigen Ereignissen. Wenn dieser Wert nicht angegeben wird, wird einer generiert und in den Antwortheadern bereitgestellt.
Autorisierung Ein eindeutiges Zugriffstoken, das den ISV identifiziert, der diesen API-Aufruf sendet. Das Format ist Bearer <access_token>, wenn der Tokenwert vom Herausgeber abgerufen wird. Weitere Informationen finden Sie unter:

Antworten

Beispiele einer Antwortnutzlast:

Akzeptiert*

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

Gesendet

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

Nichtübereinstimmung

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

Abgelehnt

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

Statuscodes

Code: 403 Verboten. Das Autorisierungstoken wurde nicht angegeben, ist ungültig oder abgelaufen. Oder die Anforderung versucht, auf ein Abonnement für ein Angebot zuzugreifen, das mit einer anderen Microsoft Entra App-ID veröffentlicht wurde als die, die zum Erstellen des Autorisierungstokens verwendet wurde.

Bewährte Methoden für Entwicklung und Test

Um die Ausgabe benutzerdefinierter Verbrauchseinheiten zu testen, implementieren Sie die Integration in die Messungs-API, und erstellen Sie einen Plan für Ihr veröffentlichtes SaaS-Angebot mit benutzerdefinierten Dimensionen, die mit einem Preis pro Einheit von 0 (null) definiert sind. Veröffentlichen Sie dann dieses Angebot als Vorschauversion, sodass nur eingeschränkte Benutzer auf die Integration zugreifen und diese testen können.

Sie können auch einen privaten Plan für ein vorhandenes Liveangebot verwenden, um den Zugriff auf diesen Plan während des Tests auf eine begrenzte Zielgruppe zu beschränken.

Support

Befolgen Sie die Anweisungen unter Support für das Programm „Kommerzieller Marketplace“ im Partner Center, um die Supportoptionen für Herausgeber zu verstehen und ein Supportticket für Microsoft zu öffnen.

Zugehöriger Inhalt

Weitere Informationen zu Dienst-APIs für die getaktete Abrechnung finden Sie unter Häufig gestellte Fragen zu Marketplace-Dienst-APIs für die getaktete Abrechnung.