Nytt dagliga användnings-API för e-handel v2 (beta)
Gäller för: Partnercenter | Partnercenter som drivs av 21Vianet | Partnercenter för Microsoft Cloud for US Government
Använd dessa API:er för att få nya e-handelsfakturerade och ej fakturerade dagliga användningsdata asynkront.
Kommentar
Det här API:et kommer snart att bli inaktuellt. För att säkerställa sömlösa åtgärder rekommenderar vi att du migrerar till GA-versionen. Här är den information du behöver för att planera framåt:
Mål: Hämta fakturerade dagliga klassificerade användningsradobjekt för faktureringsperioder från september 2022 före den 21 januari 2025.
Åtgärd: Använd det här API:et men migrera till v2 GA så snart som möjligt.
Mål: Hämta fakturerade dagliga klassificerade användningsradobjekt för faktureringsperioder från september 2022 från den 21 januari 2025.
Åtgärd: Använd endast API v2 GA.
Mål: Hämta ej fakturerade dagliga klassificerade användningsradobjekt för aktuella och tidigare faktureringsperioder före den 21 januari 2025.
Åtgärd: Använd det här API:et men migrera till v2 GA så snart som möjligt.
Mål: Hämta ej fakturerade dagliga klassificerade användningsradobjekt för aktuella och tidigare faktureringsperioder från den 21 januari 2025.
Åtgärd: Använd endast API v2 GA.
Om du vill ha en smidig övergång till de nya API:erna följer du den här länken: Fakturerad och ej fakturerad dagligen klassificerad användningsavstämning API v2 (GA).
Tack för din uppmärksamhet och vi ser fram emot att du fortsätter att lyckas med våra fakturerings-API:er.
Kommentar
Du kan komma åt dina ej fakturerade dagliga klassificerade användningsradobjekt via API:et eller Partnercenter-portalen. För att säkerställa korrekta data 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 du inte ser de senaste dagliga, ej fakturerade dagliga användningsdata förrän föregående månads fakturerade användningsdata är tillgängliga. När du har fått de fakturerade användningsdata kan du sedan hämta alla uppdaterade ej fakturerade användningsdata från början av månaden.
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.
Viktigt!
De dagliga betygssatta användningsdata 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
Det asynkrona API:et är en ny metod för att snabbt komma åt fakturerings- och avstämningsdata i hanterbara segment. Det eliminerar behovet av att upprätthålla en öppen anslutning i timmar och loopa igenom miljontals transaktioner iterativt.
Vi använder betjäningsnyckeln och asynkrona begärandesvarsmönster för att optimera våra fakturerings- och avstämnings-API:er för att leverera resultaten asynkront. API-svar ger en token för åtkomst till avstämningsdata med alla attribut eller en delmängd.
Du kan ladda ned användningsdata asynkront med hjälp av tre nya steg (API-slutpunkter). Mer information finns i följande avsnitt:
Slutpunkt för användningsradobjekt
Använd det här API:et för att komma åt fakturerade eller ej fakturerade förbrukningsradobjekt. Den returnerar http-status 202 och en platsrubrik med URL:en, som du måste avsöka med jämna mellanrum tills du får statusen lyckades med en manifest-URL.
Slutpunkt för åtgärdsstatus
Tills du får statusen lyckades kan du fortsätta att avsöka det här API:et med jämna mellanrum. Om begärda data inte är tillgängliga innehåller API-svaret ett återförsökshuvud som anger hur länge du ska vänta innan du skickar en annan begäran.
Manifestslutpunkt
Den här slutpunkten innehåller en lagringsmapp från vilken faktiska faktureringsdata kan laddas ned. Svaret delar eller partitioner filerna för att optimera dataflödet och I/O-parallelliteten.
Sekvensdiagram
Diagrammet visar de steg som krävs för att ladda ned avstämningsdata.
Åtgärdssekvens för användare
Följ dessa steg för att hämta avstämningsdata.
Steg 1: Skicka begäran
Skicka en POST-begäran till API-slutpunkten.
Hämta ofakturerade användningsradobjekt
Hämta ofakturerade användningsradobjekt för den aktuella eller senaste kalendermånaden.
API-begäran
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
Parametrar för begäran
| Namn | I | Krävs | Typ | Beskrivning |
|---|---|---|---|---|
| fragment | Fråga | Falsk | String | Välj "fullständig" för ett fullständigt svar eller "grundläggande" för en delmängd av attribut. Standardvärdet är "full". Se listan över attribut i den här artikeln. |
| period | Fråga | Sant | String | Använd "aktuell" eller "sista" för att hämta användning för den aktuella eller senaste kalendermånaden. Värdet "last" är detsamma som "föregående" i befintliga V1-API:er. |
| currencyCode | Fråga | Sant | String | Valutakod för partnerfakturering. |
Inaktuella parametrar för begäran
Den nyare API-versionen kräver inte följande URI-parametrar:
| Namn | Beskrivning |
|---|---|
| Provider | Saknas. (Den returnerar all Användning av Azure-plan och motsvarar "engångsanvändningen" för befintliga V1-API:er.) |
| hasPartnerEarnedCredit | Saknas. (returnerar alla data, oavsett PEC.) |
| Storlek | Saknas. |
| Förskjutning | Saknas. |
| seekOperation | Saknas. |
Begärandehuvud
Se listan över begärandehuvuden för API :et i den här artikeln.
Begärandetext
Saknas.
API-svar
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
API returnerar HTTP-status 202. Baserat på begäran kan API returnera annan standardstatus.
| Namn | Beskrivning |
|---|---|
| 202 Accepterad | Begäran godkänns. Fråga url:en för åtgärdsplatsrubriken för begärandestatus. |
Hämta fakturerade användningsradobjekt
Hämta fakturerade klassificerade användningsradobjekt för den stängda faktureringsperioden.
API-begäran
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
Parametrar för begäran
| Namn | I | Krävs | Typ | Beskrivning |
|---|---|---|---|---|
| invoiceId | Sökväg | Sant | String | Fakturanumret för Partnercenter. |
| Fragment | Fråga | Falsk | String | Välj "fullständig" för ett fullständigt svar eller "grundläggande" för en delmängd av attribut. Standardvärdet är "full". Se listan över attribut i den här artikeln. |
Inaktuella parametrar för begäran
Den nyare API-versionen kräver inte följande URI-parametrar:
| Namn | Beskrivning |
|---|---|
| Provider | Saknas. (Den returnerar all Användning av Azure-plan och motsvarar "engångsanvändningen" för befintliga V1-API:er.) |
| hasPartnerEarnedCredit | Saknas. (returnerar alla data, oavsett PEC.) |
| Storlek | Saknas. |
| Förskjutning | Saknas. |
| seekOperation | Saknas. |
Begärandehuvud
Se listan över begärandehuvuden för API :et i den här artikeln.
Begärandetext
Saknas.
API-svar
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
API:et returnerar "HTTP 202 Accepted". Baserat på API för begäran kan returnera annan standardstatus.
| Namn | Beskrivning |
|---|---|
| 202 Accepterad | Begäran godkänns. Kontrollera begärandestatusen genom att avsöka url:en för åtgärdsplatsens sidhuvud. |
Steg 2: Kontrollera status för begäran
Vänta på en HTTP 200 med terminalstatusen lyckades eller misslyckades. Manifest-URL:en är "resourceLocation" i statusen lyckades.
Hämta åtgärdsstatus
Hämtar status för en begäran om avstämningsdata.
API-begäran
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
Parametrar för begäran
| Namn | I | Krävs | Typ | Beskrivning |
|---|---|---|---|---|
| operationId | Sökväg | Sant | String | Åtgärds-ID:t. |
Begärandehuvud
Se listan över begärandehuvuden för API :et i den här artikeln.
Begärandetext
Saknas.
Svarsstatus
Förutom HTTP-standardstatusen i den här artikeln kan API:et returnera denna HTTP-status:
| Namn | Beskrivning |
|---|---|
| 410 Borta | Varje åtgärdslänk är aktiv under en angiven mängd serverkontrollerad tid. När tiden har gått måste klienten skicka en ny begäran. |
Svarsnyttolast
API-svarsnyttolasten returnerar följande attribut:
| Name | Valfritt | beskrivning |
|---|---|---|
| createdDateTime | falskt | Tid för begäran. |
| lastActionDateTime | falskt | Statusändringstid. |
| resourceLocation | true | URI:n för manifestnyttolasten. |
| status | falskt | Möjliga värden och åtgärder. |
| Värde | Klientåtgärd |
|---|---|
| inte startad | Gör ett nytt anrop för att kontrollera statusen efter att ha väntat på den tid som anges i rubriken "Försök efter igen". |
| körs | Gör ett nytt anrop för att kontrollera statusen efter att ha väntat på den tid som anges i rubriken "Försök efter igen". |
| Lyckades | Det slutliga drifttillståndet, som anger att data är klara. Hämta manifestnyttolasten med hjälp av den URI som anges i resourceLocation. |
| Misslyckades | Terminaltillstånd, vilket indikerar permanent fel. Starta om åtgärden. |
För felattribut:
| Name | Valfritt | beskrivning |
|---|---|---|
| fel | true | Felinformation som anges i json-format om åtgärdens status misslyckas. |
| Name | Valfritt | beskrivning |
|---|---|---|
| meddelande | falskt | Beskriver felet i detalj |
| kod | falskt | Anger vilken typ av fel som inträffade |
API-begäran
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
API-svar
Svaret föreslår att du väntar 10 sekunder innan du försöker igen när data bearbetas.
HTTP/1.1 200 OK
Retry-After: 10
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime":" 2022-06-1T10-01-05Z",
"status": "running"
}
API-begäran
(10 sekunder efter den tidigare begäran)
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
API-svar
API:et returnerar statusen "lyckades" och URI:n "resourceLocation".
HTTP/1.1 200 OK
Content-Type: application/json
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-13Z",
"status": "succeeded",
"resourceLocation": "https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/e03e1882-ff59-4c09-882f-74e60b4d7743"
}
Steg 3: Hämta manifestnyttolast
Anroparen gör en GET-begäran till manifest-URL:en för att lära sig mer om var avstämningsdata lagras i Azure-blobar.
Hämta manifestet
Hämtar manifestet med information om azure-lagringsplatsen för avstämningsdata.
API-begäran
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Parametrar för begäran
| Namn | I | Krävs | Typ | Beskrivning |
|---|---|---|---|---|
| manifestId | Sökväg | Sant | String | Manifest-ID:t. |
Begärandehuvud
Se [listan över begärandehuvuden för API:et] i den här artikeln.
Begärandetext
Saknas.
Svarsstatus
Förutom HTTP-standardstatusen kan API:et returnera denna HTTP-status:
| Namn | Beskrivning |
|---|---|
| 410 Borta | Varje manifestlänk är aktiv under en angiven mängd serverkontrollerad tid. När tiden har gått måste klienten skicka en ny begäran. |
Svarsnyttolast
API-svaret returnerar följande attribut:
| Namn | Beskrivning |
|---|---|
| Version | Manifestschemaversionen. |
| dataFormat | Filformatet för faktureringsdata. Möjliga värden komprimeradeJSONLines: varje blob är en komprimerad fil och data i filen är i JSON-linjeformat . För att komma åt data expanderar du filen. |
| utcCreatedDateTime | Tiden då manifestfilen skapades. |
| eTag | Manifestdataversion. En ändring av faktureringsinformationen genererar ett nytt eTag-värde. |
| partnerTenantId | Partnerklientorganisations-ID. |
| rootFolder | Filens rotkatalog. |
| rootFolderSAS | SAS-token för åtkomst till filen. |
| partitionType | Den här egenskapen delar upp data. Om en viss partition har mer än det tal som stöds delas data upp i flera filer som motsvarar "partitionValue". Som standard partitioner systemet data baserat på antalet radobjekt i filen. Ange inte ett fast antal radobjekt eller filstorlek i koden eftersom partitioneringsprincipen kan ändras. |
| blobCount | Totalt antal filer för det här partnerklient-ID:t. |
| sizeInBytes | Totalt antal byte i alla filer. |
| blobar | En JSON-matris med "blob"-objekt med information om alla filer för partnerklient-ID:t. |
| Blobobjekt | |
| Name | Blobens namn. |
| sizeInBytes | Blobstorlek i byte. |
| partitionValue | Partitionen som innehåller filen. En stor partition delas upp i flera filer, var och en med samma "partitionValue". |
Nyttolast för exempelmanifest
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "14f593ad-1edc-474d-aaa0-83abbf9638da",
"rootFolder": "https://{billing.blob.core.windows.net}/{folder_path}",
"rootFolderSAS": "\*\*\*",
"partitionType": "ItemCount",
"blobCount": 3,
"sizeInBytes": 2000,
"blobs": [
{
"name": "{blobName1.json.gz}",
"sizeinBytes": 500,
"partitionValue": "1"
},
{
"name": "{blobName2.json.gz}",
"sizeinBytes": 1000,
"partitionValue": "2"
},
{
"name": "{blobName3.json.gz}",
"sizeinBytes": 500,
"partitionValue": "3"
}
]
}
Steg 4: Ladda ned avstämningsdata för användning från lagringsplats
Hämta SAS-token och bloblagringsplatsen från egenskaperna "rootFolderSAS" och "rootFolder" i api-svaret för manifestnyttolasten. Använd Azure Storage SDK/-verktyget för att ladda ned och packa upp blobfilen. Den är i JSON-linjeformat .
Standard-API-begärandehuvuden
Alla API:er accepterar följande rubriker:
| Namn | Krävs | Typ | Beskrivning |
|---|---|---|---|
| Auktorisering | Sant | String | Auktoriseringsbäraretoken. |
| ms-correlationid | Falsk | String | En intern spårning av begäranden. Varje begäran genererar en ny spårare (GUID). |
| ms-cv | Falsk | String | En intern spårning av begäranden. |
| ms-requestid | Falsk | String | Begärande-ID:t för idempotens. |
Standard-API-svarsstatusar
Följande är HTTP-statusarna från API-svaret:
| Namn | Beskrivning |
|---|---|
| 400 – Felaktig begäran | Det saknades eller var felaktiga data. Felinformationen ingår i svarstexten. |
| 401 – Ej behörig | Anroparen är inte autentiserad och måste autentisera med partner-API-tjänsten innan det första anropet. |
| 403 – Förbjuden | Anroparen har inte behörighet att göra begäran. |
| 500 – Internt serverfel | API:et eller något av dess beroenden kan inte uppfylla begäran. Försök igen senare. |
| 404 – Hittades inte | Resursen är inte tillgänglig med indataparametrar. |
| 410 Borta | Tidsgränsen för manifestlänken har överskridit eller förflutit. Skicka en ny begäran. |
Attribut för användningsdata
Api-svaret för fakturerad eller ej fakturerad användning med parametern "fullständig" eller "grundläggande" begäran returnerar följande attribut:
| Attribut | "full" | "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 |