Rozhraní API pro fakturaci a vyrovnání v2 (beta)
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 můžete asynchronně fakturovat a nefakturovaná data o využití s denním hodnocením.
Poznámka:
Toto rozhraní API pro fakturované denní využití přestane fungovat po 30. červnu 2024. V následujících podrobnostech se rozhodněte, kterou verzi použít a kdy.
- Pokud jste nepřepnuli na obecně dostupnou verzi 2, použijte toto rozhraní API do 30. června 2024, abyste mohli fakturovat řádkové položky s denním poměrem využití pro faktury vytvořené pro fakturační období od září 2022 do června 2024.
- K získání faktur za faktury vytvořené pro fakturační období od září 2022 použijte pouze obecně dostupné rozhraní API v2 po 30. červnu 2024.
Toto rozhraní API pro nefakturované denní využití přestane fungovat po 30. červnu 2024. V následujících podrobnostech se rozhodněte, kterou verzi použít a kdy.
- Pokud jste nepřepnuli na obecně dostupnou verzi 2, použijte toto rozhraní API až do 30. června 2024 a získejte nefakturované položky řádků s denním hodnocením pro aktuální a předchozí fakturační období.
- K získání nefakturovaných denních položek s denním hodnocením pro aktuální a předchozí fakturaci používejte pouze obecně dostupné rozhraní API v2 po 30. červnu 2024 .
Pokud chcete začít připravovat migraci na nová rozhraní API ga v2, podívejte se na následující odkaz:
Fakturované a nefakturované rozhraní API pro odsouhlasení využití v2 (GA)
Poznámka:
Denní nefakturované údaje o využití můžete načíst prostřednictvím rozhraní API nebo portálu Partnerského centra. Zpřístupnění dat může trvat až 24 hodin. V závislosti na vaší poloze a na tom, kdy měřiče hlásí využití, ale může docházet k dalším zpožděním.
Někdy se nemusí zobrazit nejnovější nefakturovaná data o využití, dokud se nedoručí fakturovaná data o využití za předchozí měsíc. Tím zajistíte, že se fakturovaná data o využití doručí v rámci schváleného času. Jakmile obdržíte fakturovaná data o využití, měli byste být schopni načíst všechna aktualizovaná nefakturovaná data o využití od začátku měsíce.
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 třetích stran
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í jsme použili vzory valet key a asynchronní odpovědi na požadavky, abychom výsledky doručovali asynchronně. Odpovědi rozhraní API poskytnou 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 tady:
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 bude obsahovat hlavičku Opakování po , která udává, jak dlouho byste měli čekat 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
Následující 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 následujících 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. |
| Období | 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 | Žádost byla přijata. 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". Na základě rozhraní API požadavku může vrátit jiný standardní stav.
| Název | Popis |
|---|---|
| 202 Přijato | Žádost byla přijata. 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 bude ve stavu úspěchu "resourceLocation".
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 následující 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". |
| Podařilo | 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 následující 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. Dekomprese souboru pro přístup k datům. |
| 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, budou data rozdělena do více souborů odpovídajících hodnotě partitionValue. Data jsou ve výchozím nastavení rozdělena podle počtu řádků v souboru. Nenastavujte v kódu pevný počet řádků nebo velikost souboru, protože se můžou změnit. |
| 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": "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"
}
]
}
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 vypršel časový limit. 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 |
| EntitlementId | ano | ano |
| EntitlementDescription | ano | ne |
| PartnerEarnedCreditPercentage | ano | ne |
| CreditPercentage | ano | ano |
| CreditType | ano | ano |
| BenefitOrderID | ano | ano |
| BenefitID | ano | ne |
| BenefitType | ano | ano |
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro