Nové komerční rozhraní API s denním hodnocením využití v2 (beta verze)
Platí pro: Partnerské centrum | Partnerské centrum provozované společností 21Vianet | Partnerské centrum pro Microsoft Cloud pro státní správu USA
Pomocí těchto rozhraní API získáte asynchronně fakturovaná a nefakturovaná data o využití s denním hodnocením.
Poznámka:
Toto rozhraní API bude brzy zastaralé. Pokud chcete zajistit bezproblémové operace, doporučujeme migrovat na verzi GA. Tady jsou podrobnosti, které je potřeba naplánovat předem:
Cíl: Načtení fakturovaných denních položek řádku využití pro fakturační období od září 2022 před 21. lednem 2025
Akce: Použijte toto rozhraní API, ale co nejdříve migrujte na verzi 2 GA.
Cíl: Od 21. ledna 2022 z 21. ledna 2025 načtěte fakturované položky řádku s denním hodnocením využití.
Akce: Používejte pouze rozhraní API v2 GA.
Cíl: Načtení nefakturovaných denních položek řádku využití pro aktuální a předchozí fakturační období před 21. lednem 2025
Akce: Použijte toto rozhraní API, ale co nejdříve migrujte na verzi 2 GA.
Cíl: Od 21. ledna 2025 načtěte nefakturované položky řádku s denním hodnocením využití pro aktuální a předchozí fakturační období.
Akce: Používejte pouze rozhraní API v2 GA.
Pokud chcete bezproblémový přechod na nová rozhraní API, postupujte podle tohoto odkazu: Fakturované a nefakturované rozhraní API pro odsouhlasení využití v2 (GA).
Děkujeme vám za vaši pozornost a těšíme se na váš trvalý úspěch s našimi fakturačními rozhraními API.
Poznámka:
K nefakturované denní hodnotě využití se dostanete prostřednictvím rozhraní API nebo portálu Partnerského centra. Pokud chcete zajistit přesná data, povolte dostupnost až 24 hodin. V závislosti na vaší poloze a na tom, kdy měřiče hlásí využití, může dojít k dalším zpožděním.
Nejprve upřednostňujeme doručení fakturovaných denních dat o využití. V některých případech se nemusí zobrazit nejnovější nefakturovaná denní data o využití, dokud nebudou k dispozici fakturovaná data o využití za předchozí měsíc. Jakmile obdržíte fakturovaná data o využití, můžete načíst všechna aktualizovaná nefakturovaná data o využití od začátku měsíce.
Vaše porozumění a trpělivost si vážíme, když se snažíme poskytovat co nejpřesnější a včasné informace.
Důležité
Data o denním poměru využití nezahrnují poplatky za tyto produkty:
- Rezervace Azure
- Úsporný plán pro Azure
- Office
- Dynamics
- Microsoft Power Apps
- Časově neomezený software
- Předplatné softwaru
- Produkt SaaS od jiných společností než Microsoft nebo marketplace
Přehled rozhraní API
Asynchronní rozhraní API je nová metoda pro rychlý přístup k datům fakturace a odsouhlasení v spravovatelných blocích. Eliminuje nutnost udržovat otevřené připojení po dobu hodin a cyklicky procházet miliony transakcí iterativním způsobem.
K optimalizaci fakturace a rozhraní API pro odsouhlasení pro asynchronní doručování výsledků používáme vzory valet key a asynchronní odpovědi na požadavky. Odpovědi rozhraní API poskytují token pro přístup k datům odsouhlasení se všemi atributy nebo podmnožinou.
Data o využití si můžete stáhnout asynchronně pomocí tří nových kroků (koncových bodů rozhraní API). Další informace najdete v následujících částech:
Koncový bod řádkové položky využití
Toto rozhraní API slouží k přístupu k fakturovaným nebo nefakturovaným položkám řádků spotřeby. Vrátí stav HTTP 202 a hlavičku umístění s adresou URL, kterou musíte pravidelně dotazovat, dokud neobdržíte stav úspěchu s adresou URL manifestu.
Koncový bod stavu operace
Dokud neobdržíte stav úspěchu, pravidelně se dotazujte na toto rozhraní API. Pokud požadovaná data nejsou k dispozici, odpověď rozhraní API obsahuje hlavičku Opakování po , která udává, jak dlouho byste měli počkat před odesláním jiného požadavku.
Koncový bod manifestu
Tento koncový bod poskytuje složku úložiště, ze které se dají stáhnout skutečná fakturační data. Odpověď rozdělí nebo rozdělí soubory za účelem optimalizace propustnosti a vstupně-výstupního paralelismu.
Sekvenční diagram
Diagram znázorňuje kroky potřebné ke stažení dat odsouhlasení.
Pořadí akcí uživatele
Pokud chcete načíst data odsouhlasení, postupujte podle těchto kroků.
Krok 1: Odeslání žádosti
Odešlete požadavek POST do koncového bodu rozhraní API.
Získání nefakturovaných položek řádků využití
Získejte nefakturované řádkové položky řádku využití pro aktuální nebo poslední kalendářní měsíc.
Požadavek rozhraní API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
Parametry požadavku
| Název | In | Povinní účastníci | Typ | Popis |
|---|---|---|---|---|
| fragment | Dotaz | False | String | Pro úplnou odpověď nebo "základní" pro podmnožinu atributů zvolte "full". Výchozí hodnota je úplná. Podívejte se na seznam atributů v tomto článku. |
| perioda | Dotaz | True | String | K získání využití pro aktuální nebo poslední kalendářní měsíc použijte "current" nebo "last". Hodnota "last" je stejná jako "předchozí" v existujících rozhraních API V1. |
| currencyCode | Dotaz | True | String | Kód měny fakturace partnera. |
Zastaralé parametry požadavku
Novější verze rozhraní API nevyžaduje následující parametry identifikátoru URI:
| Název | Popis |
|---|---|
| Poskytovatel | Není k dispozici. (Vrátí veškeré využití plánu Azure a odpovídá "jednorázovému" existujícímu rozhraní API V1.) |
| hasPartnerEarnedCredit | Není k dispozici. (vrátí všechna data bez ohledu na PEC.) |
| Velikost | Není k dispozici. |
| Odsazení | Není k dispozici. |
| seekOperation | Není k dispozici. |
Hlavička požadavku
Podívejte se na seznam hlaviček požadavků pro rozhraní API v tomto článku.
Text požadavku
Není k dispozici.
Odpověď rozhraní API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
Rozhraní API vrátí stav HTTP 202. Na základě požadavku může rozhraní API vrátit jiný standardní stav.
| Název | Popis |
|---|---|
| 202 Přijato | Požadavek je přijat. Zadejte dotaz na adresu URL hlavičky umístění operace pro stav požadavku. |
Získání fakturovaných položek řádku využití
Získejte fakturované řádkové položky řádku využití za uzavřené fakturační období.
Požadavek rozhraní API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
Parametry požadavku
| Název | In | Povinní účastníci | Typ | Popis |
|---|---|---|---|---|
| invoiceId | Cesta | True | String | Číslo faktury v Partnerském centru. |
| Fragment | Dotaz | False | String | Pro úplnou odpověď nebo "základní" pro podmnožinu atributů zvolte "full". Výchozí hodnota je úplná. Podívejte se na seznam atributů v tomto článku. |
Zastaralé parametry požadavku
Novější verze rozhraní API nevyžaduje následující parametry identifikátoru URI:
| Název | Popis |
|---|---|
| Poskytovatel | Není k dispozici. (Vrátí veškeré využití plánu Azure a odpovídá "jednorázovému" existujícímu rozhraní API V1.) |
| hasPartnerEarnedCredit | Není k dispozici. (vrátí všechna data bez ohledu na PEC.) |
| Velikost | Není k dispozici. |
| Odsazení | Není k dispozici. |
| seekOperation | Není k dispozici. |
Hlavička požadavku
Podívejte se na seznam hlaviček požadavků pro rozhraní API v tomto článku.
Text požadavku
Není k dispozici.
Odpověď rozhraní API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
Rozhraní API vrátí "HTTP 202 Accepted" (Přijato). Na základě rozhraní API požadavku může vrátit jiný standardní stav.
| Název | Popis |
|---|---|
| 202 Přijato | Požadavek je přijat. Zkontrolujte stav požadavku dotazováním adresy URL hlavičky umístění operace. |
Krok 2: Kontrola stavu žádosti
Počkejte na HTTP 200 se stavem terminálu, který byl úspěšný nebo selhal. Adresa URL manifestu je "resourceLocation" ve stavu úspěchu.
Získání stavu operace
Získá stav žádosti o data odsouhlasení.
Požadavek rozhraní API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
Parametry požadavku
| Název | In | Povinní účastníci | Typ | Popis |
|---|---|---|---|---|
| operationId | Cesta | True | String | ID operace. |
Hlavička požadavku
Podívejte se na seznam hlaviček požadavků pro rozhraní API v tomto článku.
Text požadavku
Není k dispozici.
Stav odpovědi
Kromě standardního stavu HTTP v tomto článku může rozhraní API vrátit tento stav HTTP:
| Název | Popis |
|---|---|
| 410 Pryč | Každý odkaz na operaci je aktivní po určenou dobu řízenou serverem. Po uplynutí doby musí klient odeslat novou žádost. |
Datová část odpovědi
Datová část odpovědi rozhraní API vrátí následující atributy:
| Název | Volitelné | Popis |
|---|---|---|
| createdDateTime | false (nepravda) | Čas žádosti. |
| lastActionDateTime | false (nepravda) | Čas změny stavu |
| resourceLocation | true | Identifikátor URI datové části manifestu. |
| stav | false (nepravda) | Možné hodnoty a akce. |
| Hodnota | Akce klienta |
|---|---|
| notstarted | Proveďte další volání, které zkontroluje stav po čekání na čas zadaný v hlavičce "Opakovat až po". |
| spuštěno | Proveďte další volání, které zkontroluje stav po čekání na čas zadaný v hlavičce "Opakovat až po". |
| uspěl | Konečný stav operace, který označuje, že jsou data připravená. Načtěte datovou část manifestu pomocí identifikátoru URI zadaného v resourceLocation. |
| selhalo | Stav terminálu, který označuje trvalé selhání. Restartujte operaci. |
Atribut chyby:
| Název | Volitelné | Popis |
|---|---|---|
| chyba | true | Podrobnosti o chybě zadané ve formátu JSON, pokud se stav operace nezdařil. |
| Název | Volitelné | Popis |
|---|---|---|
| zpráva | false (nepravda) | Podrobně popisuje chybu. |
| code | false (nepravda) | Označuje druh chyby, ke které došlo. |
Požadavek rozhraní API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Odpověď rozhraní API
Odpověď navrhuje čekat 10 sekund před opakováním při zpracování dat.
HTTP/1.1 200 OK
Retry-After: 10
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime":" 2022-06-1T10-01-05Z",
"status": "running"
}
Požadavek rozhraní API
(10 sekund po předchozí žádosti)
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Odpověď rozhraní API
Rozhraní API vrátí stav "úspěch" a identifikátor URI "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"
}
Krok 3: Získání datové části manifestu
Volající odešle na adresu URL manifestu požadavek GET, aby se dozvěděl více o tom, kde jsou data odsouhlasení uložená v objektech blob Azure.
Získání manifestu
Načte manifest s informacemi o umístění úložiště Azure s daty odsouhlasení.
Požadavek rozhraní API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Parametry požadavku
| Název | In | Povinní účastníci | Typ | Popis |
|---|---|---|---|---|
| manifestId | Cesta | True | String | ID manifestu. |
Hlavička požadavku
Podívejte se na [seznam hlaviček požadavků pro rozhraní API] v tomto článku.
Text požadavku
Není k dispozici.
Stav odpovědi
Kromě standardního stavu HTTP může rozhraní API vrátit tento stav HTTP:
| Název | Popis |
|---|---|
| 410 Pryč | Každý odkaz manifestu je aktivní po určenou dobu řízenou serverem. Po uplynutí doby musí klient odeslat novou žádost. |
Datová část odpovědi
Odpověď rozhraní API vrátí následující atributy:
| Název | Popis |
|---|---|
| Verze | Verze schématu manifestu. |
| dataFormat | Formát souboru fakturačních dat. Možné hodnoty komprimovanéJSONLines: každý objekt blob je komprimovaný soubor a data v souboru jsou ve formátu řádků JSON. Pokud chcete získat přístup k datům, dekomprimujte soubor. |
| utcCreatedDateTime | Čas vytvoření souboru manifestu |
| eTag | Verze dat manifestu Změna fakturačních údajů vygeneruje novou hodnotu eTag. |
| partnerTenantId | ID tenanta partnera. |
| rootFolder | Kořenový adresář souboru. |
| rootFolderSAS | Token SAS pro přístup k souboru. |
| partitionType | Tato vlastnost rozdělí data. Pokud má daný oddíl více než podporované číslo, data se rozdělí do více souborů odpovídajících hodnotě partitionValue. Ve výchozím nastavení systém rozděluje data na základě počtu řádkových položek v souboru. Nenastavujte v kódu pevný počet řádků nebo velikost souboru, protože se může změnit princip dělení. |
| blobCount | Celkový počet souborů pro toto ID tenanta partnera |
| sizeInBytes | Celkový počet bajtů ve všech souborech |
| objekty blob | Pole JSON objektů blob s podrobnostmi o všech souborech pro ID partnerského tenanta. |
| Objekt blob | |
| Název | Název objektu blob |
| sizeInBytes | Velikost objektu blob v bajtech |
| partitionValue | Oddíl, který obsahuje soubor. Velký oddíl bude rozdělen do více souborů, z nichž každý bude mít stejnou hodnotu partitionValue. |
Ukázková datová část manifestu
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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"
}
]
}
Krok 4: Stažení dat o odsouhlasení využití z umístění úložiště
Získejte token SAS a umístění úložiště objektů blob z vlastností rootFolderSAS a rootFolder a odpověď rozhraní API datové části manifestu. Pomocí sady Azure Storage SDK nebo nástroje stáhněte a rozbalte soubor objektu blob. Je ve formátu řádků JSON .
Hlavičky požadavků standardního rozhraní API
Všechna rozhraní API přijímají následující hlavičky:
| Název | Povinní účastníci | Typ | Popis |
|---|---|---|---|
| Autorizace | True | String | Autorizační nosný token |
| ms-correlationid | False | String | Interní sledování požadavků. Každý požadavek vygeneruje nový sledovací modul (GUID). |
| ms-cv | False | String | Interní sledování požadavků. |
| ms-requestid | False | String | ID idempotence požadavku. |
Stavy odpovědí standardního rozhraní API
Tady jsou stavy HTTP z odpovědi rozhraní API:
| Název | Popis |
|---|---|
| 400 – Chybný požadavek | Došlo k chybějícím nebo nesprávným datům. Podrobnosti o chybě jsou zahrnuty v textu odpovědi. |
| 401 – Neautorizováno | Volající není ověřený a musí se před prvním voláním ověřit ve službě partnerského rozhraní API. |
| 403 – Zakázáno | Volající nemá oprávnění k provedení žádosti. |
| 500 – Vnitřní chyba serveru | Rozhraní API nebo jedna z jejích závislostí nemůže požadavek splnit. Zkuste to později. |
| 404 – Nenalezeno | Prostředek není dostupný se vstupními parametry. |
| 410 Pryč | Vypršel časový limit odkazu manifestu nebo uplynul. Odešlete novou žádost. |
Atributy dat o využití
Fakturovaná nebo nefakturovaná odpověď rozhraní API pro využití s parametrem požadavku "full" nebo "basic" vrátí následující atributy:
| Atribut | "full" | "základní" |
|---|---|---|
| Id partnera | ano | ano |
| PartnerName | ano | ano |
| CustomerId | ano | ano |
| CustomerName | ano | Yes |
| CustomerDomainName | ano | ne |
| CustomerCountry | ano | ne |
| MpnId | ano | ne |
| Tier2MpnId | ano | ne |
| InvoiceNumber | ano | ano |
| ID produktu | ano | ano |
| SkuId | ano | ano |
| AvailabilityId | ano | ne |
| SkuName | ano | ano |
| ProductName | ano | ne |
| Název vydavatele | ano | ano |
| PublisherId | ano | ne |
| Popis předplatného | ano | ne |
| SubscriptionId | ano | ano |
| ChargeStartDate | ano | ano |
| ChargeEndDate | ano | ano |
| UsageDate | ano | ano |
| MeterType | ano | ne |
| MeterCategory | ano | ne |
| ID měřiče | ano | ne |
| MeterSubCategory | ano | ne |
| MeterName | ano | ne |
| MeterRegion | ano | ne |
| Jednotka | ano | ano |
| ResourceLocation | ano | ne |
| ConsumedService | ano | ne |
| ResourceGroup | ano | ne |
| Identifikátor ResourceURI | ano | ano |
| ChargeType | ano | ano |
| UnitPrice | ano | ano |
| Množství | ano | ano |
| UnitType | ano | ne |
| BillingPreTaxTotal | ano | ano |
| BillingCurrency | ano | ano |
| CenyPreTaxTotal | ano | ano |
| PricingCurrency | ano | ano |
| ServiceInfo1 | ano | ne |
| ServiceInfo2 | ano | ne |
| Značky | ano | ne |
| AdditionalInfo | ano | ne |
| EffectiveUnitPrice | ano | ano |
| PCToBCExchangeRate | ano | ano |
| PCToBCExchangeRateDate | ano | ne |
| EntitlementId | ano | ano |
| EntitlementDescription | ano | ne |
| PartnerEarnedCreditPercentage | ano | ne |
| CreditPercentage | ano | ano |
| CreditType | ano | ano |
| BenefitOrderID | ano | ano |
| BenefitID | ano | ne |
| BenefitType | ano | ano |