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årt nya asynkrona API erbjuder ett snabbare och effektivare sätt att komma åt dina fakturerings- och avstämningsdata via Azure-blobar. I stället för att hålla en anslutning öppen i timmar eller bearbeta batchar med 2 000 radobjekt kan du nu effektivisera arbetsflödet, minska serverbelastningen och förbättra databearbetningstiderna.
De nya API:erna för daglig användningsavstämning för handel använder avancerade tekniker som valet-nyckel och asynkrona mönster för begäran-svar . Valet-nyckelmönstret möjliggör säker åtkomst till resurser utan att dela autentiseringsuppgifter, medan det asynkrona mönstret för begäran-svar möjliggör effektiv kommunikation mellan system.
Dessa API:er ger dig en SAS-token (signatur för delad åtkomst) som du kan använda för att komma åt antingen alla attribut eller en delmängd av de dagliga klassificerade användningsavstämningsdata. Den här token förbättrar säkerheten genom att ge begränsad tidsåtkomst och ger flexibilitet när det gäller att hantera dataåtkomstbehörigheter.
Genom att använda våra optimerade API:er kan du uppnå snabbare resultat med mindre ansträngning, förenkla din dataåtkomst och förbättra den övergripande effektiviteten. Använd de här verktygen för att effektivisera arbetsflödet och hantera behörigheter mer effektivt.
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 åtkomst till partnerfaktureringsdata följer du den här länken och bekantar dig med grunderna för autentisering och auktorisering för Microsoft Graph. Det här steget är avgörande eftersom det säkerställer att din app på ett säkert sätt kan komma åt nödvändiga data.
Du kan tilldela behörigheten "PartnerBilling.Read.All" med antingen Azure Portal eller Administrationscenter för Entra. Så här gör du:
- Registrera din app på Microsoft Entra-startsidan under avsnittet Appregistreringar.
- Om du vill bevilja nödvändig behörighet går du till sidan Microsoft Entra-app. Under avsnittet API-behörigheter väljer du "Lägg till en behörighet" och väljer omfånget "PartnerBilling.Read.All".
Genom att slutföra de här stegen ser du till att din app har nödvändig åtkomst till partnerfaktureringsdata.
Kommentar
Om du har använt vår betaversion kommer du förmodligen att finna övergången till den allmänna tillgänglighetsversionen (GA) smidig och intuitiv. För att hjälpa dig att förstå uppdateringarna och förbättringarna rekommenderar vi att du jämför betaversioner och GA-versioner. Om du förstår de här uppdateringarna kan du maximera de nya funktionerna och förbättringarna som är tillgängliga i GA-versionen.
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 från andra länder än Microsoft eller Marketplace
API-översikt
För att hjälpa dig att hämta fakturerade dagliga användningsradobjekt för e-handel asynkront erbjuder vi två viktiga API-slutpunkter. Följ den här smidiga guiden för att komma igång snabbt och effektivt!
Slutpunkt för användningsradobjekt
Använd först det här API:et för att hämta nya dagliga användningsradobjekt för handel . När du gör en begäran får du HTTP-status 202 och en platsrubrik med en URL. Avsök den här URL:en regelbundet tills du får en lyckad status och en manifest-URL.
Slutpunkt för åtgärdsstatus
Fortsätt sedan att kontrollera åtgärdsstatusen genom att anropa det här API:et med jämna mellanrum. Om data inte är klara innehåller svaret ett återförsökshuvud som anger 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 länk till lagringsmappen för att ladda ned användningsdata. Svaret segmentar filerna för att förbättra dataflödet och möjliggöra I/O-parallellitet.
Genom att följa dessa steg kan du effektivt hantera fakturaavstämningsprocessen.
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.
Kommentar
Du kan komma åt dina ej fakturerade dagliga klassificerade användningsradobjekt via API:et eller Partnercenter-portalen. För att säkerställa datanoggrannhet kan du tillåta upp till 24 timmar för tillgänglighet. Beroende på din plats och när mätarna rapporterar användningen kan det uppstå ytterligare fördröjningar.
Vi prioriterar tidsleverans av fakturerade dagliga användningsdata först. Ibland kanske den senaste ej fakturerade dagliga klassificerade användningsdata inte visas förrän föregående månads fakturerade data är tillgängliga. När du har fått de fakturerade data kan du sedan komma åt alla uppdaterade ej fakturerade användningsdata från början av månaden.
Viktiga punkter:
- Tillåt upp till 24 timmar för datatillgänglighet.
- Det kan uppstå ytterligare fördröjningar beroende på din plats och mätarrapporteringstider.
- Fakturerade dagliga användningsdata prioriteras framför ej fakturerade data.
Din förståelse och ditt tålamod uppskattas när vi strävar efter att tillhandahålla så exakt och snabb information som möjligt.
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. Om det inte anges är "full" standardvärdet. Kontrollera listan över attribut i det här avsnittet. Valfritt. |
billingPeriod | Sant | String | Använd "aktuell" för den aktuella faktureringsperioden eller "sista" för den föregående faktureringsperioden (samma som "föregående" i v1-API:et för att hämta ej fakturerad daglig användning. Obligatoriska. |
currencyCode | Sant | String | Valutakod för partnerfakturering. Obligatoriska. |
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
API:et svarar vanligtvis med http 202-status. Du kan också stöta på andra statusar beroende på dina begäranden. Dessa statusar visas i avsnittet 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. Obligatoriska. |
attributeSet | Falsk | String | Välj "fullständig" för alla attribut eller "grundläggande" för en begränsad uppsättning. Om det inte anges är "full" standardvärdet. Kontrollera listan över attribut i det här avsnittet. 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. För andra möjliga statusar baserade på dina förfrågningar, se 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 hålla reda på status för en begäran ser du till att du får ett HTTP 200-svar som är en standardstatuskod som anger "lyckades" eller "misslyckades". Om det lyckas hittar du manifest-URL:en i attributet "resourceLocation". Det här attributet ger en slutpunkt för åtkomst till nödvändig information.
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 | En unik identifierare för att kontrollera status för begäran. Obligatoriska. |
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 de standard-HTTP-statusar som anges i Standard API-svarsstatusar kan API:et också returnera följande HTTP-status:
Kod | Beskrivning |
---|---|
410 – Borta | Manifestlänken upphör att gälla efter en angiven tid. Om du vill hämta manifestlänken igen skickar du en ny begäran. |
Svarsnyttolast
API-svarsnyttolasten innehåller följande attribut:
Attribut | Obligatoriskt | Beskrivning |
---|---|---|
id | Sant | En unik identifierare för varje svar. Obligatoriska. |
status | Sant |
Värden och åtgärder: Krävs: inte startad: Vänta under den angivna varaktigheten i rubriken "Försök igen" och gör sedan ett nytt anrop för att kontrollera statusen. körs: Vänta tills den angivna varaktigheten i rubriken "Försök efter 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. Obligatoriska. |
lastActionDateTime | Sant | Senaste gången statusen ändrades. Obligatoriska. |
resourceLocation | Falsk | URI:n för manifestnyttolasten. Valfritt. |
fel | Falsk | Information om eventuella fel, som anges i JSON-format. Valfritt. Attribut som ingår: message: Beskrivning av felet. kod: Typ av fel. |
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 | Microsoft Entra-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. Undvik att hårdkoda antal radobjekt eller filstorlekar när de 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: namn och partitionValue |
name | Namnet på bloben. |
partitionValue | Partition som innehåller filen. Den stora partitionen är uppdelad i flera filer baserat på vissa kriterier, till exempel filstorlek eller antal poster, 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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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
Först måste du hämta sas-token (signatur för delad åtkomst) och bloblagringsplatsen. Du hittar den här informationen i egenskaperna "sasToken" och "rootDirectory" för api-svaret för manifestnyttolasten. Om du sedan vill ladda ned och packa upp blobfilen använder du Azure Storage SDK/-verktyget. Den är i JSONLines-format .
Dricks
Se till att kolla in vår exempelkod. Den visar hur du laddar ned och packar 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 | Autentisering krävs innan du gör det första anropet. Autentisera med partner-API-tjänsten. |
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 | Manifestlänken är inte giltig eller aktiv längre. Skicka en ny begäran. |
500 – Internt serverfel | API:et eller 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
Kolla in jämförelsetabellen för att se skillnaderna mellan betaversionen och de allmänt tillgängliga (GA). Om du för närvarande använder betaversionen är övergången till GA-versionen enkel och enkel.
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. Din JSON bör ha följande egenskaper: * currencyCode: Din faktureringsvaluta. Till exempel USD. * billingPeriod: Faktureringsperioden för fakturan. Till exempel aktuell. Här är ett JSON-exempelobjekt 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. Din JSON bör ha följande egenskaper: * invoiceId: Den unika identifieraren för fakturan. Till exempel G00012345. * attributeSet: De attribut som ska finnas i svaret, till exempel fullständiga. Här är ett JSON-exempelobjekt 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} för att komma åt manifestresursen i resourceLocation. Den här metoden sparar tid genom att eliminera behovet av ett separat anrop till GET /manifest/{id}. |
Ändringar i manifestschemat | ||
"id": Inte tillgängligt | "id": En unik identifierare för manifestresursen. | |
"version": Tillgänglig | "version": har ändrats till "schemaversion". | |
"dataFormat": Tillgänglig | "dataFormat": Tillgänglig. | |
"utcCretedDateTime": Tillgänglig | "utcCretedDateTime": har ändrats till "createdDateTime". | |
"eTag": Tillgänglig | "eTag": Tillgänglig. | |
"partnerTenantId": Tillgänglig | "partnerTenantId": Tillgänglig | |
"rootFolder": Tillgänglig | "rootFolder": har ändrats till "rootDirectory". | |
"rootFolderSAS": Tillgänglig | "rootFolderSAS": har ändrats till "sasToken". Den här uppdateringen innehåller bara token utan rotkatalogsökvägen. Om du vill hitta 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 fakturerad eller ej fakturerad användningsavstämning för attributuppsättningarna "full" eller "basic" läser du den här tabellen. Mer information om dessa attribut och deras betydelser finns i den här dokumentationen.
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 |
PCToBCExchangeRateDate | ja | nej |
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 från API v1 till v2.
Varje attributnamn börjar nu med en versal bokstav för att upprätthålla konsekvens med filen och förbättra läsbarheten.
unitOfMeasure uppdateras till Enhet. Dess betydelse och värde förblir oförändrade, vilket förenklar attributnamnet.
resellerMpnId är nu Tier2MpnId. Innebörden och värdet är desamma.
rateOfPartnerEarnedCredit uppdateras till PartnerEarnedCreditPercentage. Det nya namnet och värdet gör det nu lättare att förstå eftersom de återspeglar procentandelen i stället för bråket. Till exempel är 0,15 nu 15 %.
rateOfCredit är nu CreditPercentage. Både namnet och värdet har ändrats för att ge en tydligare förståelse. Till exempel är 1,00 nu 100 %.
Vi tror att dessa ändringar gör API:erna mer intuitiva och enklare att använda.
Exempelkod
Om du vill använda det här API:et läser du följande länk, som innehåller C#-exempelkod.
Api-exempel för Partnercenter: Hämta faktureringsrekonfigureringsdata.