Dela via


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.

Ett diagram som visar stegen för att ladda ned avstämningen.

Å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

GET https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

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&currencyCode=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.