APIs für getaktete Abrechnung in Marketplace

Die APIs für getaktete Abrechnung sollten verwendet werden, wenn der Herausgeber benutzerdefinierte Messgrößen für ein Angebot erstellt, das in Partner Center veröffentlicht wird. Die Integration in die APIs für die getaktete Abrechnung ist für jedes erworbene Angebot erforderlich, das über mindestens einen Plan mit benutzerdefinierten Messgrößen zur Ausgabe von Verwendungsereignissen verfügt.

Wichtig

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

Weitere Informationen zum Erstellen von benutzerdefinierten Messgrößen für SaaS finden Sie unter Getaktete Abrechnung für SaaS mithilfe des Nutzungserfassungsdiensts für den kommerziellen Marketplace.

Weitere Informationen zum Erstellen von benutzerdefinierten Meteringdimensionen für ein Azure-Anwendungsangebot mit einem verwalteten App-Plan finden Sie unter Konfigurieren Ihrer Azure-Anwendung Einrichtungsdetails.

Hinweis zur Durchsetzung von TLS 1.2

TLS Version 1.2 wird als minimale Version für 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 Verwendungsereignis bei getakteter Abrechnung

Die Nutzungsereignis-API sollte vom Herausgeber aufgerufen werden, um Nutzungsereignisse für eine aktive (abonnierte) Ressource gegen den vom jeweiligen Kunden erworbenen Plan auszugeben. Das Nutzungsereignis wird separat für jede benutzerdefinierte Dimension des Plans ausgegeben, der vom Herausgeber beim Veröffentlichen des Angebots definiert wird.

Nur ein Verwendungsereignis kann für jede Stunde eines Kalendertags pro Ressource und Dimension ausgelöst werden. Wenn mehr als eine Einheit in einer Stunde verbraucht wird, sammeln Sie alle einheiten, die in der Stunde verbraucht werden, und geben Sie sie dann in einem einzigen Ereignis aus. Verwendungsereignisse können nur für die letzten 24 Stunden ausgegeben werden. Wenn Sie ein Nutzungsereignis jederzeit zwischen 8:00 und 8:59:59 ausgeben (und es akzeptiert wird) und ein zusätzliches Ereignis für den gleichen Tag zwischen 8:00 und 8:59:59 senden, wird es als Duplikat abgelehnt.

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

Abfrageparameter:

Parameter	Empfehlung
ApiVersion	Verwenden Sie den 31.08.2018.

Anforderungsheader:

Inhaltstyp	Verwende application/json
x-ms-requestid	Eindeutiger Zeichenfolgenwert zum Nachverfolgen der Anforderung vom Client, vorzugsweise eine GUID. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
x-ms-correlationid	Eindeutiger Zeichenfolgenwert für den Vorgang auf dem Client. Dieser Parameter korreliert alle Ereignisse vom Clientvorgang mit Ereignissen auf der Serverseite. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
authorization	Ein eindeutiges Zugriffstoken, das den ISV identifiziert, der diesen API-Aufruf vornimmt. Das Format ist "Bearer <access_token>", wenn der Tokenwert wie für folgende Fälle erläutert vom Herausgeber abgerufen wird: SaaS: Abrufen eines Tokens mit HTTP POST Verwaltete Anwendung: Authentifizierungsstrategien

Beispiel für einen 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
}

resourceId entspricht in Azure Managed Applications-Plänen resource group Id in der verwalteten Anwendung. Ein Beispielskript zum Abrufen finden Sie in mithilfe des Tokens für Azure-verwaltete Identitäten.

Für SaaS-Angebote ist die resourceId die SaaS-Abonnement-ID. Weitere Informationen zu SaaS-Abonnements finden Sie unter Listenabonnements.

Antworten

Code: 200
OKAY. Die Nutzungsemissionen wurden zur weiteren Verarbeitung und Abrechnung auf Microsoft-Seite akzeptiert und aufgezeichnet.

Beispiel für Antwortnutzdaten:

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

• Fehlende oder ungültige Anforderungsdaten.
• effectiveStartTime liegt mehr als 24 Stunden zurück. Das Ereignis ist abgelaufen.
• SaaS-Abonnement befindet sich nicht im Status "Abonniert".

Beispiel für Antwortnutzdaten:

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

Code: 401 Nicht autorisiert. Das Autorisierungstoken ist ungültig oder abgelaufen. Die Anforderung versucht, auf ein SaaS-Abonnement für ein Angebot zuzugreifen, das mit einer anderen Microsoft Entra-App-ID veröffentlicht wurde, die zum Erstellen des Authentifizierungstokens verwendet wurde.

Code: 403 Verboten. Das Autorisierungstoken ist ungültig, wurde nicht bereitgestellt oder mit unzureichenden Berechtigungen bereitgestellt. Stellen Sie sicher, dass Sie ein gültiges Autorisierungstoken angeben.

Code: 409
Konflikt. Ein Verwendungsereignis wurde bereits für die angegebene Ressourcen-ID, das effektive Nutzungsdatum und die Angegebene Stunde erfolgreich gemeldet.

Beispiel für Antwortnutzdaten:

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

Batchverwendungsereignis bei getakteter Abrechnung

Mit der Batchverwendungsereignis-API können Sie Nutzungsereignisse für mehrere erworbene Ressourcen gleichzeitig 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 zum Nachverfolgen der Anforderung vom Client, vorzugsweise eine GUID. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
x-ms-correlationid	Eindeutiger Zeichenfolgenwert für den Vorgang auf dem Client. Dieser Parameter korreliert alle Ereignisse vom Clientvorgang mit Ereignissen auf der Serverseite. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
authorization	Ein eindeutiges Zugriffstoken, das den ISV identifiziert, der diesen API-Aufruf vornimmt. Das Format ist Bearer <access_token>, wenn der Tokenwert wie für folgende Fälle erläutert vom Herausgeber abgerufen wird: SaaS: Abrufen eines Tokens mit HTTP POST Verwaltete Anwendung: Authentifizierungsstrategien

Anmerkung

Im Anforderungstext hat der Ressourcenbezeichner unterschiedliche Bedeutungen für SaaS-App und für azure Managed App, die benutzerdefinierte Meter aussendet. Der Ressourcenbezeichner für SaaS-App ist resourceID. Der Ressourcenbezeichner für Azure Application Managed Apps-Pläne ist resourceUri. Weitere Informationen zu Ressourcenbezeichnern finden Sie unter Getaktete Abrechnung von Azure Marketplace– Auswählen der richtigen ID beim Übermitteln von Nutzungsereignissen.

Für SaaS-Angebote ist die resourceId die SaaS-Abonnement-ID. Weitere Informationen zu SaaS-Abonnements finden Sie unter Listenabonnements.

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

resourceUri entspricht in Azure Managed Applications-Plänen resourceUsageId in der verwalteten Anwendung. Ein Beispielskript zum Abrufen finden Sie unter Verwenden des Tokens für von Azure verwaltete Identitäten.

Anforderungstextbeispiel für verwaltete Azure-Anwendungen:

{
  "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
OKAY. Die Batchausgabe der Nutzungsdaten wurde zur weiteren Verarbeitung und Abrechnung von Microsoft akzeptiert und aufgezeichnet. Die Antwortliste wird mit dem Status für jedes einzelne Ereignis im Batch zurückgegeben. Gehen Sie die Antwortnutzdaten durch, um die Antworten auf jedes einzelne Verwendungsereignis zu verstehen, die als Teil des Batchereignisses gesendet werden.

Beispiel für Antwortnutzdaten:

{
  "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, auf den in BatchUsageEvent API-Antwort verwiesen wird:

Statuscode	Beschreibung
Accepted	Angenommen.
Expired	Abgelaufene Nutzungsdauer
Duplicate	Doppelte Verwendung angegeben.
Error	Fehlercode.
ResourceNotFound	Die bereitgestellte Verwendungsressource ist ungültig.
ResourceNotAuthorized	Sie sind nicht berechtigt, diese Ressource zu nutzen.
ResourceNotActive	Die Ressource wird angehalten oder wurde nie aktiviert.
InvalidDimension	Die Messgröße, anhand derer die Nutzung erfasst wird, ist für dieses Angebot bzw. diesen Plan ungültig.
InvalidQuantity	Die übergebene Menge ist niedriger oder gleich 0.
BadArgument	Die Eingabe fehlt oder ist fehlerhaft.

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

Code: 401 Nicht autorisiert. Das Autorisierungstoken ist ungültig oder abgelaufen. Die Anforderung versucht, auf ein SaaS-Abonnement für ein Angebot zuzugreifen, das mit einer anderen Microsoft Entra-App-ID veröffentlicht wurde, die zum Erstellen des Authentifizierungstokens verwendet wurde.

Code: 403 Verboten. Das Autorisierungstoken ist ungültig, wurde nicht bereitgestellt oder mit unzureichenden Berechtigungen bereitgestellt. Stellen Sie sicher, dass Sie ein gültiges Autorisierungstoken angeben.

Abrufen von Verwendungsereignissen bei getakteter Abrechnung

Sie können die Api für Verwendungsereignisse aufrufen, um die Liste der Verwendungsereignisse abzurufen. ISVs können diese API verwenden, um die Nutzungsereignisse anzuzeigen, die für eine bestimmte konfigurierbare Dauer bereitgestellt wurden und welchen Status diese Ereignisse zum Zeitpunkt des Aufrufs der API haben.

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

Abfrageparameter:

Parameter	Empfehlung
ApiVersion	Verwenden Sie den 31.08.2018.
NutzungsbeginnDatum	DateTime im ISO8601 Format. Beispiel: 2020-12-03T15:00 oder 2020-12-03
UsageEndDate (optional)	DateTime im ISO8601 Format. Standard = aktuelles Datum
Angebots-ID (optional)	Standard = alle verfügbaren
planId (optional)	Standard = alle verfügbaren
dimension (optional)	Standard = alle verfügbaren
azureSubscriptionId (optional)	Standard = alle verfügbaren
reconStatus (wahlweise)	Standard = alle verfügbaren

Mögliche Werte von reconStatus:

ReconStatus	Beschreibung
Vorgelegt	Noch nicht von PC Analytics verarbeitet
Angenommen	Mit PC Analytics abgeglichen
Zurückgewiesen	In der Pipeline abgelehnt. Wenden Sie sich an den Microsoft-Support, um die Ursache zu untersuchen.
Nichtübereinstimmung	Die MarketplaceAPI- und Partner Center Analytics-Mengen sind zwar beide ungleich Null, stimmen jedoch nicht überein.

Anforderungsheader:

Inhaltstyp	Verwenden von Application/json
x-ms-requestid	Eindeutiger Zeichenfolgenwert (vorzugsweise eine GUID) zum Nachverfolgen der Anforderung vom Client. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
x-ms-correlationid	Eindeutiger Zeichenfolgenwert für den Vorgang auf dem Client. Dieser Parameter korreliert alle Ereignisse vom Clientvorgang mit Ereignissen auf der Serverseite. Wenn dieser Wert nicht angegeben wird, wird ein Wert generiert und in den Antwortheadern bereitgestellt.
Ermächtigung	Ein eindeutiges Zugriffstoken, das den ISV identifiziert, der diesen API-Aufruf vornimmt. Das Format ist Bearer <access_token>, wenn der Tokenwert vom Herausgeber abgerufen wird. Weitere Informationen finden Sie unter: SaaS in Das Token mit einem HTTP-POST abrufen Verwaltete Anwendung: Authentifizierungsstrategien

Antworten

Beispiele für Antwortnutzdaten:

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

Übermittelt

[
  {
    "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: 401 Nicht autorisiert. Das Autorisierungstoken ist ungültig oder abgelaufen. Die Anforderung versucht, auf ein SaaS-Abonnement für ein Angebot zuzugreifen, das mit einer anderen Microsoft Entra-App-ID veröffentlicht wurde, die zum Erstellen des Authentifizierungstokens verwendet wurde.

Code: 403 Verboten. Das Autorisierungstoken ist ungültig, wurde nicht bereitgestellt oder mit unzureichenden Berechtigungen bereitgestellt. Stellen Sie sicher, dass Sie ein gültiges Autorisierungstoken angeben.

Bewährte Methoden für Entwicklung und Tests

Um die benutzerdefinierte Meteremissionen zu testen, implementieren Sie die Integration mit der Metering-API, erstellen Sie einen Plan für Ihr veröffentlichtes SaaS-Angebot mit benutzerdefinierten Dimensionen, die darin mit Nullpreis pro Einheit definiert sind. Und veröffentlichen Sie dieses Angebot als Vorschau, sodass nur eingeschränkte Benutzer auf die Integration zugreifen und 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 begrenzte Benutzergruppen zu beschränken.

Support

Befolgen Sie die Anweisungen in Support für das kommerzielle Marketplace-Programm im Partner Center, um die Supportoptionen von Herausgebern zu verstehen und ein Supportticket mit Microsoft zu öffnen.

Verwandte Inhalte

Weitere Informationen zu Metering-Dienst-APIs finden Sie unter Marketplace-Meteringdienst-APIs – Häufig gestellte Fragen.