Fakturerad och ej fakturerad dagligen klassificerad användningsavstämning API v2 (GA)
Gäller för: Partnercenter (ej tillgängligt i Azure Government eller Azure China 21Vianet.)
Våra asynkrona API:er erbjuder ett snabbare och mer hanterbart sätt att komma åt fakturerings- och avstämningsdata via Azure-blobar. Med dessa API:er behöver du inte hålla anslutningen öppen i timmar eller loopa genom batcharna med 2 000 radobjekt.
Vi har optimerat våra nya API:er för daglig användningsavstämning med hjälp av valet-nyckel och asynkrona mönster för begärandesvar . När du använder dessa API:er får du en token som du kan använda för att komma åt antingen alla attribut eller en delmängd av de dagliga klassificerade användningsavstämningsdata.
Kommentar
De nya API:erna finns inte på API-värden för Partnercenter. I stället kan du hitta dem på MS Graph i Använda Microsoft Graph API för att exportera partnerfaktureringsdata – Microsoft Graph v1.0 | Microsoft Learn. Om du vill komma åt dessa API:er kan du läsa följande information.
Du kan använda dessa API:er för det offentliga/globala MS Graph-molnet först nu. De är ännu inte tillgängliga för Azure Government eller Azure China 21Vianet.
Viktigt!
Om du vill ge din app den behörighet som krävs för att få åtkomst till partnerfaktureringsdata måste du följa den här länken och lära dig mer om grunderna för autentisering och auktorisering för Microsoft Graph.
Vanligtvis kan du använda antingen Azure-portalen eller Administrationscenter för Entra för att tilldela den behörighet som krävs: "PartnerBilling.Read.All". Här är stegen för att göra det:
- Registrera din app på Microsoft Entra-startsidan under avsnittet Appregistreringar.
- Tilldela behörighet till din app på sidan Microsoft Entra-app under avsnittet API-behörigheter. Välj "Lägg till en behörighet" och välj omfånget "PartnerBilling.Read.All".
Kommentar
Om du har använt vår betaversion kanske du inte märker några betydande ändringar i den allmänt tillgängliga versionen (GA). Vi rekommenderar att du jämför de två versionerna för att förstå skillnaderna och uppdateringarna.
Viktigt!
Den nya dagliga användningen för handel inkluderar inte avgifterna för dessa produkter:
- Azure-reservation
- Azure-besparingsprenumeration
- Office
- Dynamics
- Microsoft Power Apps
- Evig programvara
- Prenumeration på programvara
- SaaS-produkt som inte är Microsoft
API-översikt
Om du vill hämta nya dagliga användningsradobjekt för handel asynkront använder du två API-slutpunkter. Så här gör du:
Slutpunkt för användningsradobjekt
Använd det här API:et för att hämta fakturerade eller ej fakturerade dagliga klassificerade användningsradobjekt. Du får http-status 202 och en URL i platsrubriken. Avsök den här URL:en med jämna mellanrum tills du får en lyckad status med en manifest-URL.
Slutpunkt för åtgärdsstatus
Om du vill få statusen lyckad fortsätter du att anropa det här API:et med jämna mellanrum. Om data inte är klara innehåller API-svaret ett återförsökshuvud för att berätta hur lång tid det tar att vänta innan du försöker igen. När åtgärden är klar får du en manifestresurs med en lagringsmapp där du kan ladda ned användningsdata. Svaret delar upp filerna i mindre delar för optimerat dataflöde och I/O-parallellitet.
Sekvensdiagram
Här är ett sekvensdiagram som visar stegen för att ladda ned avstämningsdata.
Åtgärdssekvens för användare
Följ dessa steg om du vill hämta nya dagliga förbrukningsavstämningsobjekt för handel :
Steg 1: Skicka begäran
Skicka en POST-begäran till API-slutpunkten.
Hämta poster för dagliga dagliga klassificerade användningsrader
Hämta nya dagliga användningsradsobjekt som inte fakturerats för handel för den aktuella eller senaste kalendermånaden eller faktureringsperioden.
API-begäran
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
Accept: application/json
Content-Type: application/json
{
"currencyCode": "USD",
"billingPeriod": "current",
"attributeSet": "basic"
}
Begärandetext
| Attribut | Obligatoriskt | Type | Beskrivning |
|---|---|---|---|
| attributeSet | Falsk | String | Välj "fullständig" för alla attribut eller "grundläggande" för en begränsad uppsättning. Standardvärdet är "full". (Se listan över attribut här). Valfritt. |
| billingPeriod | Sant | String | Använd "aktuell" eller "sista" (samma som "föregående" i V1-API:er) för att få dagligt betygsatt användning för den aktuella eller senaste kalendermånaden eller faktureringsperioden. Obligatoriskt. |
| currencyCode | Sant | String | Valutakod för partnerfakturering. Obligatoriskt. |
Begärandehuvuden
Information om hur du begär huvuden för API :et finns i Tillförlitlighet och support.
API-svar
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
När du använder API:et returneras vanligtvis en HTTP 202-status. Information om andra möjliga statusar baserat på dina begäranden finns i Standard API-svarsstatusar.
| Kod | beskrivning |
|---|---|
| 202 – Godkänd | Din begäran godkändes. Om du vill kontrollera statusen för din begäran frågar du url:en som anges i platsrubriken. |
Hämta fakturerade dagliga klassificerade användningsradobjekt
Hämta nya handelsfakturerade dagliga klassificerade användningsradobjekt för en faktura för den stängda faktureringsperioden.
API-begäran
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
Frågeparametrar
Ej tillämpligt
Begärandetext
| Attribut | Obligatoriskt | Type | Beskrivning |
|---|---|---|---|
| invoiceId | Sant | String | En unik identifierare för varje faktura. Obligatoriskt. |
| attributeSet | Falsk | String | Välj "fullständig" för alla attribut eller "grundläggande" för en begränsad uppsättning. Standardvärdet är "full". (Se listan över attribut här). Valfritt. |
Begärandehuvud
Begär rubriker för API:et. Mer information finns i tillförlitlighet och support.
API-svar
HTTP/1.1 202 Accepterad
Plats: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
När du använder API:et returneras vanligtvis en HTTP 202-status. Andra möjliga statusar baserat på dina begäranden finns i Statusar.
| Kod | beskrivning |
|---|---|
| 202 – Godkänd | Din begäran godkändes. Om du vill kontrollera statusen för din begäran frågar du url:en som anges i platsrubriken. |
Steg 2: Kontrollera status för begäran
Om du vill kontrollera status för en begäran väntar du på ett HTTP 200-svar med statusen "lyckades" eller "misslyckades". Om begäran lyckas anges manifest-URL:en i attributet "resourceLocation".
Hämta åtgärdsstatus
Hämtar status för en begäran.
API-begäran
Parametrar för begäran
| Name | Inkludera i | Obligatoriskt | Type | Beskrivning |
|---|---|---|---|---|
| operationId | URI för förfrågan | Sant | String | Ett unikt ID för att kontrollera status för begäran. Obligatoriskt. |
Begärandehuvud
Information om hur du begär huvuden för API :et finns i Tillförlitlighet och support.
Begärandetext
Saknas.
Svarsstatus
Förutom http-standardstatusarna kan API:et returnera följande HTTP-status:
| Kod | beskrivning |
|---|---|
| 410 – Borta | Manifestlänken är endast aktiv under en viss tidsperiod som angetts av servern. När den här tiden har gått måste du skicka en ny begäran för att få åtkomst till manifestet. |
Svarsnyttolast
API-svarsnyttolasten innehåller följande attribut:
| Attribut | Obligatoriskt | Beskrivning |
|---|---|---|
| id | Sant | Ett unikt ID för varje svar. Obligatoriskt. |
| status | Sant | Värden och åtgärder (krävs): notstarted: Vänta tills den tid som anges i rubriken "Försök igen" och gör sedan ett nytt anrop för att kontrollera statusen. körs: Vänta tills den tid som anges i rubriken "Försök igen" och gör sedan ett nytt anrop för att kontrollera statusen. lyckades: Data är klara. Hämta manifestnyttolasten med hjälp av den URI som anges i resourceLocation. misslyckades: Åtgärden misslyckades permanent. Starta om den. |
| createdDateTime | Sant | Den tid då begäran gjordes. Obligatoriskt. |
| lastActionDateTime | Sant | Den tid då statusen senast ändrades. Obligatoriskt. |
| resourceLocation | Falsk | URI:n för manifestnyttolasten. Valfritt. |
| fel | Falsk | Om åtgärden misslyckas anges felinformation i JSON-format. Valfritt. Följande attribut kan inkluderas: message (Required): En detaljerad beskrivning av felet. code (Required): Den typ av fel som inträffade. |
Resursplatsobjekt
| Attribut | Beskrivning |
|---|---|
| id | En unik identifierare för manifestet. |
| schemaVersion | Version av manifestschemat. |
| dataFormat | Format för faktureringsdatafilen. compressedJSON: dataformat där varje blob är en komprimerad fil som innehåller data i JSON-linjeformat . Om du vill hämta data från varje blob expanderar du dem. |
| createdDateTime | Datum och tid då manifestfilen skapades. |
| eTag | Version av manifestdata. En ändring i faktureringsinformationen genererar ett nytt värde. |
| partnerTenantId | ID för partnerns klientorganisation. |
| rootDirectory | Rotkatalogen för filen. |
| sasToken | SAS-token (signatur för delad åtkomst) som gör att du kan läsa alla filer under katalogen. |
| partitionType | Delar upp data i flera blobar baserat på attributet "partitionValue" . Systemet delar partitioner som överskrider det antal som stöds. Som standard partitioneras data baserat på antalet radobjekt i filen. Ange inte ett fast antal radobjekt eller filstorlek i koden eftersom dessa värden kan ändras. |
| blobCount | Totalt antal filer för det här partnerklient-ID:t. |
| blobar | En JSON-matris med "blob"-objekt som innehåller filinformationen för partnerklient-ID:t. |
| blob-objekt | Ett objekt som innehåller följande information: |
| name | Namnet på bloben. |
| partitionValue | Partition som innehåller filen. Den stora partitionen är uppdelad i flera filer, där varje fil innehåller samma "partitionValue". |
API-begäran
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-svar
Svaret rekommenderar att du väntar i 10 sekunder innan du försöker igen när du bearbetar data.
HTTP/1.1 200 OK
Retry-After: 10
{
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-05Z",
"status": "running"
}
API-begäran
(10 sekunder efter föregående begäran...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-svar
API:et returnerar statusen "lyckades" och URI:n för "resourceLocation".
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",
"@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",
"id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",
"createdDateTime": "2023-12-05T21:17:29Z",
"lastActionDateTime": "2023-12-05T21:18:00.8897902Z",
"status": "succeeded",
"resourceLocation": {
"id": "44e8500b-ab92-490e-8ac3-90500a1d3427",
"createdDateTime": "2023-11-06T19:58:47.513Z",
"schemaVersion": "2",
"dataFormat": "compressedJSON",
"partitionType": "default",
"eTag": "RwDrn7fbiTXy6UULE",
"partnerTenantId": "0e195b37-4574-4539-bc42-0e539b9684c0",
"rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",
"sasToken": "{token}",
"blobCount": 1,
"blobs": \[
{
"name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",
"partitionValue": "default"
}
\]
}
}
Steg 3: Ladda ned dagliga klassificerade radobjekt för användningsavstämning från Azure Blob Storage
Hämta sas-token (signatur för delad åtkomst) och bloblagringsplatsen från "sasToken" och "rootDirectory" egenskaperna för api-svaret för manifestnyttolasten. Använd Azure Storage SDK/-verktyget för att ladda ned och packa upp blobfilen. Den är i JSONLines-format .
Dricks
Kolla in vår exempelkod för att ladda ned och packa upp Azure-blobfilen till din lokala databas.
Standard-API-svarsstatusar
Du kan få dessa HTTP-statusar från API-svaret:
| Code | Beskrivning |
|---|---|
| 400 – Felaktig begäran | Begäran saknas eller innehåller felaktiga data. Kontrollera svarstexten om du vill ha felinformation. |
| 401 – behörighet saknas | Anroparen autentiseras inte och du måste autentisera med partner-API-tjänsten innan du gör det första anropet. |
| 403 – förbjuden | Du har inte den behörighet som krävs för att göra begäran. |
| 404 – Hittades inte | De begärda resurserna är inte tillgängliga med de angivna indataparametrarna. |
| 410 – Borta | Tidsgränsen för manifestlänken uppnåddes eller upphörde att gälla. Skicka en ny begäran. |
| 500 – Internt serverfel | API:et eller något av dess beroenden kan inte uppfylla begäran just nu. Försök igen senare. |
| 5000 – Inga tillgängliga data | Systemet har inga data för de angivna indataparametrarna. |
Jämför beta- och GA-versioner
Se jämförelsetabellen för att förstå skillnaderna mellan betaversionerna och allmänt tillgängliga (GA). Om du använder betaversionen bör det vara enkelt att byta till ga-versionen.
| Viktig information | Beta | Allmänt tillgängligt |
|---|---|---|
| API-värdslutpunkt | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| HTTP-metod | POST | POST |
| Api-slutpunkt för ej fakturerad dagligt klassificerad användning | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| Indataparametrar för api:et för ej fakturerad dagligt klassificerad användning | Om du vill ange parametrar i API-begäran tar du med dem i frågesträngen för begärande-URL:en. Om du till exempel vill ange parametrarna period och currencyCode lägger du till i begärande-URL ?period=current¤cyCode=usd :en. |
Ange indata genom att inkludera ett JSON-objekt i begärandetexten. JSON-objektet bör innehålla följande egenskaper: * currencyCode: Valutakoden för fakturan. Till exempel USD. * billingPeriod: Faktureringsperioden för fakturan. Till exempel aktuell. Här är ett exempel på ett JSON-objekt som innehåller egenskaperna currencyCode och billingPeriod: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Api-slutpunkt för fakturerad dagligt betygsatt användning | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| Indataparametrar för API:et för fakturerad dagligt klassificerad användning | Om du vill ange parametrar i API-begäran tar du med invoiceId i begärande-URL:en. Dessutom kan du inkludera en valfri fragmentparameter i frågesträngen för att hämta den fullständiga uppsättningen attribut. Om du till exempel vill hämta den fullständiga uppsättningen attribut lägger du till i begärande-URL ?fragment=full :en. |
Ange indata genom att inkludera ett JSON-objekt i begärandetexten. JSON-objektet bör innehålla följande egenskaper: * invoiceId: Fakturans ID. Till exempel G00012345. * attributeSet: Den uppsättning attribut som ska inkluderas i svaret. Till exempel full. Här är ett exempel på ett JSON-objekt som innehåller egenskaperna invoiceId och attributeSet: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| Manifestresurs | Använd en separat GET /manifest/{id}-metod för att hämta manifestresursen. | Använd metoden GET /operations/{Id}, som returnerar den relaterade manifestresursen i resourceLocation, vilket eliminerar behovet av ett separat anrop till METODEN GET /manifest/{id}. |
| Ändringar i manifestschemat | ||
| "id": Inte tillgängligt | "id": En unik identifierare för manifestresursen. | |
| "version": Tillgänglig | "version": har bytt namn till "schemaversion". | |
| "dataFormat": Tillgänglig | "dataFormat": Tillgänglig. | |
| "utcCretedDateTime": Tillgänglig | "utcCretedDateTime": omdöpt till "createdDateTime". | |
| "eTag": Tillgänglig | "eTag": Tillgänglig. | |
| "partnerTenantId": Tillgänglig | "partnerTenantId": Tillgänglig | |
| "rootFolder": Tillgänglig | "rootFolder": har bytt namn till "rootDirectory". | |
| "rootFolderSAS": Tillgänglig | "rootFolderSAS": omdöpt till "sasToken". Den innehåller nu en token och innehåller inte längre rotkatalogsökvägen. Om du vill komma åt katalogen använder du egenskapen "rootDirectory" i stället. | |
| "partitionType": Tillgänglig | "partitionType": Tillgänglig. | |
| "blobCount": Tillgänglig | "blobCount": Tillgänglig. | |
| "sizeInBytes": Tillgänglig | "sizeInBytes": Inte tillgängligt. | |
| "blobar": Tillgänglig | "blobar": Tillgänglig. | |
| "blobobjekt": Tillgängligt | "blobobjekt": Tillgängligt. | |
| "name": Tillgänglig | "name": Tillgänglig. | |
| "partitionValue": Tillgänglig | "partitionValue": Tillgänglig. |
Objektattribut för dagliga klassificerade användningsavstämningsobjekt
Om du vill jämföra attributen som returneras av API:et för daglig klassificering av användning för attributuppsättningarna "full" eller "basic" läser du följande information.
| Attribut | Fullständig | Grundläggande |
|---|---|---|
| PartnerId | ja | ja |
| PartnerName | ja | ja |
| CustomerId | ja | ja |
| CustomerName | ja | Ja |
| CustomerDomainName | ja | nej |
| CustomerCountry | ja | nej |
| MpnId | ja | nej |
| Tier2MpnId | ja | nej |
| InvoiceNumber | ja | ja |
| Produkt-ID | ja | ja |
| SkuId | ja | ja |
| AvailabilityId | ja | nej |
| SkuName | ja | ja |
| ProductName | ja | nej |
| PublisherName | ja | ja |
| PublisherId | ja | nej |
| SubscriptionDescription | ja | nej |
| SubscriptionId | ja | ja |
| ChargeStartDate | ja | ja |
| ChargeEndDate | ja | ja |
| UsageDate | ja | ja |
| MeterType | ja | nej |
| MeterCategory | ja | nej |
| MeterId | ja | nej |
| MeterSubCategory | ja | nej |
| MeterName | ja | nej |
| MeterRegion | ja | nej |
| Enhet | ja | ja |
| ResourceLocation | ja | nej |
| ConsumedService | ja | nej |
| ResourceGroup | ja | nej |
| ResourceURI | ja | ja |
| ChargeType | ja | ja |
| UnitPrice | ja | ja |
| Kvantitet | ja | ja |
| UnitType | ja | nej |
| BillingPreTaxTotal | ja | ja |
| BillingCurrency | ja | ja |
| PricingPreTaxTotal | ja | ja |
| PricingCurrency | ja | ja |
| ServiceInfo1 | ja | nej |
| ServiceInfo2 | ja | nej |
| Taggar | ja | nej |
| AdditionalInfo | ja | nej |
| EffectiveUnitPrice | ja | ja |
| PCToBCExchangeRate | ja | ja |
| EntitlementId | ja | ja |
| EntitlementDescription | ja | nej |
| PartnerEarnedCreditPercentage | ja | nej |
| CreditPercentage | ja | ja |
| CreditType | ja | ja |
| BenefitOrderID | ja | ja |
| BenefitID | ja | nej |
| BenefitType | ja | ja |
Viktigt!
Anteckna dessa ändringar när du flyttar till API v2 från v1.
Varje attributs namn börjar i versaler.
unitOfMeasure är nu Enhet. Attributets betydelse och värde är desamma.
resellerMpnId är nu Tier2MpnId. Attributets betydelse och värde är desamma.
Namnet och värdet för rateOfPartnerEarnedCredit har ändrats till PartnerEarnedCreditPercentage. Attributets nya namn och värde återspeglar procentandelen i stället för bråket. Till exempel är 0,15 nu 15.
rateOfCredit är nu CreditPercentage. Attributets innebörd och värde har ändrats. Till exempel är 1,00 nu 100.
Exempelkod
Mer information finns i API-exempel för Partnercenter: Hämta faktureringsrekonfigureringsdata.
Feedback
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i: https://aka.ms/ContentUserFeedback.
Skicka och visa feedback för