Marketplace forgalmi díjas számlázási API-k

  • Cikk

A forgalmi díjas számlázási API-kat akkor kell használni, amikor a közzétevő egyéni mérési dimenziókat hoz létre a Partnerközpontban közzéteendő ajánlathoz. A forgalmi díjas számlázási API-kkal való integráció minden olyan megvásárolt ajánlathoz szükséges, amely egy vagy több egyéni dimenzióval rendelkező csomaggal rendelkezik a használati események kibocsátásához.

Fontos

Nyomon kell követnie a kódban szereplő használatot, és csak az alapdíj feletti használatért kell használati eseményeket küldenie a Microsoftnak.

Az egyéni mérési dimenziók SaaS-hez való létrehozásáról további információt az SaaS forgalmi díjas számlázásában talál.

Az egyéni mérési dimenziók felügyelt alkalmazáscsomaggal rendelkező Azure-alkalmazás-ajánlatokhoz való létrehozásáról további információt az Azure-alkalmazásajánlat beállítási részleteinek konfigurálása című témakörben talál.

TLS 1.2-megjegyzés kényszerítése

A TLS 1.2-es verziója a HTTPS-kommunikáció minimális verziója. Győződjön meg arról, hogy ezt a TLS-verziót használja a kódban. A TLS 1.0-s és 1.1-es verziója elavult, és a csatlakozási kísérletek elutasításra kerülnek.

Forgalmi díjas számlázási egyszeri használati esemény

A használati esemény API-t a közzétevőnek kell meghívnia, hogy használati eseményeket bocsátjon ki egy aktív erőforráson (előfizetve) az adott ügyfél által vásárolt csomaghoz. A használati eseményt a rendszer külön bocsátja ki a közzétevő által az ajánlat közzétételekor meghatározott terv minden egyéni dimenziója esetében.

Erőforrásonként és dimenziónként egy naptári nap minden órájában csak egy használati esemény bocsátható ki. Ha egy órán belül egynél több egységet használ fel, akkor halmozódjon fel az adott órában felhasznált összes egység, majd adja ki egyetlen eseményben. A használati események csak az elmúlt 24 órában bocsáthatók ki. Ha bármikor kibocsát egy használati eseményt 8:00 és 8:59:59 között (és elfogadjuk), és egy további eseményt küld ugyanarra a napra 8:00 és 8:59:59 között, akkor a rendszer ismétlődőként elutasítja.

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

Lekérdezési paraméterek:

Paraméter Ajánlás
ApiVersion Használja a 2018-08-31-et.

Kérelemfejlécek:

Tartalomtípus Használja a következő parancsot: application/json
x-ms-requestid Egyedi sztringérték az ügyfél kérésének nyomon követéséhez, lehetőleg GUID azonosítóval. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben.
x-ms-correlationid Egyedi sztringérték az ügyfélen végzett művelethez. Ez a paraméter korrelálja az ügyfélművelet összes eseményét a kiszolgálóoldali eseményekkel. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben.
authorization Egyedi hozzáférési jogkivonat, amely azonosítja az API-hívást kezdeményező ISV-t. A formátum az, "Bearer <access_token>" amikor a közzétevő lekéri a jogkivonat értékét a következőhöz hasonlóan:

Példa kérelemtörzsre:

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

Azure-alkalmazás Managed Apps-csomagok esetében a resourceId felügyelt alkalmazásresource group Id. Egy példaszkript a lekéréshez az Azure által felügyelt identitások jogkivonatának használatával.

SaaS-ajánlatok esetén az resourceId SaaS-előfizetés azonosítója. További információ az SaaS-előfizetésekről: listás előfizetések.

Válaszok

Kód: 200
OK. A használati kibocsátás a Microsoft oldalán lett elfogadva és rögzítve további feldolgozás és számlázás céljából.

Példa válasz hasznos adatra:

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

Kód: 400
Rossz kérés.

  • Hiányzó vagy érvénytelen kérelemadatok megadása.
  • effectiveStartTime a múltban több mint 24 óra. Az esemény lejárt.
  • Az SaaS-előfizetés nem előfizetéses állapotban van.

Példa válasz hasznos adatra:

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

Kód: 403

Tiltott. Az engedélyezési jogkivonat nincs megadva, érvénytelen vagy lejárt. Vagy a kérés egy olyan ajánlat előfizetéséhez próbál hozzáférni, amelyet az engedélyezési jogkivonat létrehozásához használttól eltérő Microsoft Entra-alkalmazásazonosítóval tettek közzé.

Kód: 409
Konfliktus. A megadott erőforrás-azonosítóhoz, érvényes használati dátumhoz és órához már sikeresen jelentett egy használati eseményt.

Példa válasz hasznos adatra:

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

Forgalmi díjas számlázási köteg használati eseménye

A kötegelt használati esemény API lehetővé teszi, hogy egyszerre több megvásárolt erőforrás használati eseményeit is kibocsátsa. Emellett több használati eseményt is kibocsáthat ugyanahhoz az erőforráshoz, feltéve, hogy különböző naptári órákban vannak. Egyetlen kötegben az események maximális száma 25.

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

Lekérdezési paraméterek:

Paraméter Ajánlás
ApiVersion Használja a 2018-08-31-et.

Kérelemfejlécek:

Tartalomtípus Használja a következő parancsot: application/json
x-ms-requestid Egyedi sztringérték az ügyfél kérésének nyomon követéséhez, lehetőleg GUID azonosítóval. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben.
x-ms-correlationid Egyedi sztringérték az ügyfélen végzett művelethez. Ez a paraméter korrelálja az ügyfélművelet összes eseményét a kiszolgálóoldali eseményekkel. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben.
authorization Egyedi hozzáférési jogkivonat, amely azonosítja az API-hívást kezdeményező ISV-t. A formátum az, Bearer <access_token> amikor a közzétevő lekéri a jogkivonat értékét a következőhöz hasonlóan:

Feljegyzés

A kérelem törzsében az erőforrás-azonosító különböző jelentéssel rendelkezik az SaaS-alkalmazás és az egyéni fogyasztásmérőt kibocsátó Azure Managed App esetében. Az SaaS-alkalmazás erőforrás-azonosítója a következő resourceID: . Az Azure-alkalmazás Managed Apps-csomagok erőforrás-azonosítója a következőresourceUri: . Az erőforrás-azonosítókról további információt az Azure Marketplace forgalmi díjas számlázása – A használati események elküldésekor a megfelelő azonosító kiválasztása című témakörben talál.

SaaS-ajánlatok esetén az resourceId SaaS-előfizetés azonosítója. További információ az SaaS-előfizetésekről: listás előfizetések.

Példa kéréstörzs saaS-alkalmazásokhoz:

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

Azure-alkalmazás Managed Apps-csomagok esetében a resourceUri felügyelt alkalmazásresourceUsageId. Egy példaszkript a lekéréshez az Azure által felügyelt identitások jogkivonatának használatával.

Példa kéréstörzsre Azure-alkalmazás felügyelt alkalmazásokhoz:

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

Válaszok

Kód: 200
OK. A köteghasználati kibocsátást a Microsoft oldalán fogadták el és rögzítették további feldolgozás és számlázás céljából. A válaszlista a köteg egyes eseményeinek állapotával lesz visszaadva. A válasz hasznos adatainak átfuttatásával megismerheti a kötegelt esemény részeként küldött egyes használati eseményekre adott válaszokat.

Példa válasz hasznos adatra:

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

Az API-válaszban BatchUsageEvent hivatkozott állapotkód leírása:

Állapotkód Leírás
Accepted Elfogadott.
Expired Lejárt használat.
Duplicate Duplikált használat.
Error Hibakód.
ResourceNotFound A megadott használati erőforrás érvénytelen.
ResourceNotAuthorized Nem jogosult használati adatokat megadni ehhez az erőforráshoz.
ResourceNotActive Az erőforrás fel van függesztve, vagy soha nem aktiválódott.
InvalidDimension Az ajánlat/csomag esetében érvénytelen az a dimenzió, amelyhez a használatot átadták.
InvalidQuantity Az átadott mennyiség kisebb vagy egyenlő 0-nak.
BadArgument A bemenet hiányzik vagy helytelenül van formázva.

Kód: 400
Rossz kérés. A köteg több mint 25 használati eseményt tartalmazott.

Kód: 403
Tiltott. Az engedélyezési jogkivonat nincs megadva, érvénytelen vagy lejárt. Vagy a kérés egy olyan ajánlat előfizetéséhez próbál hozzáférni, amelyet az engedélyezési jogkivonat létrehozásához használttól eltérő Microsoft Entra-alkalmazásazonosítóval tettek közzé.

A forgalmi díjas számlázás lekéri a használati eseményeket

Meghívhatja a használati események API-t a használati események listájának lekéréséhez. Az ISV-k ezzel az API-val megtekinthetik azokat a használati eseményeket, amelyeket egy bizonyos konfigurálható ideig közzétettek, és hogy ezek az események milyen állapotban vannak az API meghívásának időpontjában.

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

Lekérdezési paraméterek:

Paraméter Ajánlás
ApiVersion Használja a 2018-08-31-et.
usageStartDate DateTime ISO8601 formátumban. Például: 2020-12-03T15:00 vagy 2020-12-03
UsageEndDate (nem kötelező) DateTime ISO8601 formátumban. Alapértelmezett = aktuális dátum
offerId (nem kötelező) Default = minden elérhető
planId (nem kötelező) Default = minden elérhető
dimenzió (nem kötelező) Default = minden elérhető
azureSubscriptionId (nem kötelező) Default = minden elérhető
reconStatus (nem kötelező) Default = minden elérhető

A reconStatus lehetséges értékei:

ReconStatus Leírás
Elküldve A PC Analytics még nem dolgozza fel
Elfogadva Megfeleltetve a PC Analyticsnek
Elutasítva Elutasítva a folyamatban. Az ok kivizsgálásához forduljon a Microsoft ügyfélszolgálatához.
Eltérés A MarketplaceAPI és a Partner Center Analytics mennyisége nem nulla, de nem egyezik

Kérelemfejlécek:

Tartalomtípus Alkalmazás/json használata
x-ms-requestid Egyedi sztringérték (lehetőleg GUID) az ügyféltől érkező kérés nyomon követéséhez. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben.
x-ms-correlationid Egyedi sztringérték az ügyfélen végzett művelethez. Ez a paraméter korrelálja az ügyfélművelet összes eseményét a kiszolgálóoldali eseményekkel. Ha ez az érték nincs megadva, a rendszer létrehoz egyet, és megadja a válaszfejlécekben.
engedélyezés Egyedi hozzáférési jogkivonat, amely azonosítja az API-hívást kezdeményező ISV-t. A formátum az, Bearer <access_token> amikor a közzétevő lekéri a jogkivonat értékét. További információkért lásd:

Válaszok

Példák a válasz hasznos adataira:

Elfogadott*

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

Beküldve

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

Eltérés

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

Elutasította

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

Állapotkódok

Kód: 403 Tiltott. Az engedélyezési jogkivonat nincs megadva, érvénytelen vagy lejárt. Vagy a kérés egy olyan ajánlat előfizetéséhez próbál hozzáférni, amelyet az engedélyezési jogkivonat létrehozásához használttól eltérő Microsoft Entra-alkalmazásazonosítóval tettek közzé.

Ajánlott fejlesztési és tesztelési eljárások

Az egyéni fogyasztásmérő-kibocsátás teszteléséhez implementálja a metering API-val való integrációt, hozzon létre egy tervet a közzétett SaaS-ajánlathoz, amelyben egyedi dimenziók vannak meghatározva, egységenként nulla ár mellett. És tegye közzé ezt az ajánlatot előzetes verzióként, így csak korlátozott felhasználók férhetnek hozzá és tesztelhetik az integrációt.

Privát csomagot is használhat egy meglévő élő ajánlathoz, hogy korlátozott célközönségre korlátozza a csomaghoz való hozzáférést a tesztelés során.

Támogatás kérése

A Partnerközpont kereskedelmi piactér programjának támogatásával kapcsolatos útmutatást követve megismerheti a közzétevők támogatási lehetőségeit, és támogatási jegyet nyithat a Microsofttal.

Következő lépések

A mérési szolgáltatás API-kkal kapcsolatos további információkért tekintse meg a Marketplace mérési szolgáltatás API-jait ismertető gyakori kérdéseket.