Fakturované a nefakturované rozhraní API pro odsouhlasení využití v2 (GA)
Platí pro: Partnerské centrum (nedostupné ve službě Azure Government, Azure Germany nebo Azure China 21Vianet.)
Naše asynchronní rozhraní API nabízejí rychlejší a lépe spravovatelný způsob přístupu k datům fakturace a odsouhlasení prostřednictvím objektů blob Azure. S těmito rozhraními API nemusíte udržovat připojení otevřené po dobu hodin nebo smyčky prostřednictvím dávek 2 000 řádků.
Optimalizovali jsme naše nová obchodní rozhraní API s denním hodnocením využití pomocí vzorů valet key a asynchronních požadavků a odpovědí . Když použijete tato rozhraní API, obdržíte token, který můžete použít pro přístup ke všem atributům nebo podmnožině dat denního odsouhlasení využití.
Poznámka:
Nová rozhraní API nejsou hostovaná na hostiteli rozhraní API Partnerského centra. Místo toho je najdete v MS Graphu pomocí rozhraní Microsoft Graph API k exportu fakturačních dat partnerů – Microsoft Graph v1.0 | Microsoft Learn. Pokud chcete získat přístup k těmto rozhraním API, projděte si následující podrobnosti.
Tato rozhraní API můžete použít pouze pro veřejný nebo globální cloud MS Graph. Zatím nejsou dostupné pro Azure Government, Azure Germany nebo Azure China 21Vianet.
Poznámka:
Pokud používáte naši beta verzi, nemusíte si všimnout významných změn v obecně dostupné verzi (GA). Doporučujeme porovnat obě verze, abyste porozuměli rozdílům a aktualizacím.
Důležité
Nové využití s denním hodnocením obchodu nezahrnuje 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ého společnosti než Microsoft
Přehled rozhraní API
Pokud chcete načíst nové obchodní položky s denním hodnocením využití asynchronně, použijte dva koncové body rozhraní API. Postup je následující:
Koncový bod řádkové položky využití
Pomocí tohoto rozhraní API můžete načíst fakturované nebo nefakturované řádkové položky využití s denním hodnocením. V hlavičce umístění se zobrazí stav HTTP 202 a adresa URL. Tuto adresu URL cyklické dotazování v pravidelných intervalech, dokud neobdržíte stav úspěchu s adresou URL manifestu.
Koncový bod stavu operace
Pokud chcete získat stav úspěchu, pokračujte voláním tohoto rozhraní API v pravidelných intervalech. Pokud data nejsou připravená, odpověď rozhraní API obsahuje hlavičku Opakování po , která vám řekne, jak dlouho se má čekat, než to zkusíte znovu. Po dokončení operace získáte prostředek manifestu se složkou úložiště, kde si můžete stáhnout data o využití. Odpověď rozdělí soubory na menší části pro optimalizovanou propustnost a vstupně-výstupní paralelismus.
Sekvenční diagram
Tady je sekvenční diagram, který ukazuje kroky pro stažení dat odsouhlasení.
Pořadí akcí uživatele
Chcete-li načíst nové položky řádku odsouhlasení využití s denním hodnocením obchodu , postupujte takto:
Krok 1: Odeslání žádosti
Odešlete požadavek POST do koncového bodu rozhraní API.
Získání nefakturovaných denních položek řádků využití
Získejte nové obchodní nefakturované denní položky řádku využití pro aktuální nebo poslední kalendářní měsíc nebo fakturační období.
Požadavek rozhraní API
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"
}
Text požadavku
| Atribut | Požaduje se | Type | Popis |
|---|---|---|---|
| attributeSet | False | String | Pro všechny atributy nebo "základní" pro omezenou sadu zvolte "full". Výchozí hodnota je úplná. (Seznam atributů najdete tady). Nepovinné. |
| billingPeriod | True | String | K získání denního poměru využití pro aktuální nebo poslední kalendářní měsíc nebo fakturační období použijte "aktuální" nebo "poslední" (stejné jako "předchozí" v rozhraních API V1). Povinný: |
| currencyCode | True | String | Kód měny fakturace partnera. Povinný: |
Záhlaví žádosti
Pokud chcete požádat o hlavičky rozhraní API, přečtěte si téma Spolehlivost a podpora.
Odpověď rozhraní API
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
Když použijete rozhraní API, obvykle vrátí stav HTTP 202. Pokud chcete zobrazit další možné stavy na základě vašich požadavků, podívejte se na stavy odpovědí na standardní rozhraní API.
| Kód | Popis |
|---|---|
| 202 – přijato | Vaše žádost byla přijata. Pokud chcete zkontrolovat stav požadavku, zadejte dotaz na adresu URL uvedenou v hlavičce umístění. |
Získání fakturovaných denních položek řádků využití
Získejte nové obchodní fakturované denní položky řádku využití faktury za uzavřené fakturační období.
Požadavek rozhraní API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
Parametry dotazů
–
Text požadavku
| Atribut | Požaduje se | Type | Popis |
|---|---|---|---|
| invoiceId | True | String | Jedinečný identifikátor každé faktury. Povinný: |
| attributeSet | False | String | Pro všechny atributy nebo "základní" pro omezenou sadu zvolte "full". Výchozí hodnota je úplná. (Seznam atributů najdete tady). Nepovinné. |
Hlavička požadavku
Hlavičky požadavků pro rozhraní API Další informace najdete v tématu spolehlivost a podpora.
Odpověď rozhraní API
Http/1.1 202 Přijato
Umístění: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
Když použijete rozhraní API, obvykle vrátí stav HTTP 202. Další možné stavy na základě vašich požadavků najdete v tématu Stavy.
| Kód | Popis |
|---|---|
| 202 – přijato | Vaše žádost byla přijata. Pokud chcete zkontrolovat stav požadavku, zadejte dotaz na adresu URL uvedenou v hlavičce umístění. |
Krok 2: Kontrola stavu žádosti
Pokud chcete zkontrolovat stav požadavku, počkejte na odpověď HTTP 200 se stavem "úspěch" nebo "selhání". Pokud je požadavek úspěšný, adresa URL manifestu se poskytne v atributu resourceLocation.
Získání stavu operace
Načte stav požadavku.
Požadavek rozhraní API
Parametry požadavku
| Název | Zahrnout do | Požaduje se | Type | Popis |
|---|---|---|---|---|
| operationId | Identifikátor URI žádosti | True | String | Jedinečné ID pro kontrolu stavu žádosti. Povinný: |
Hlavička požadavku
Pokud chcete požádat o hlavičky rozhraní API, přečtěte si téma Spolehlivost a podpora.
Text požadavku
Není k dispozici.
Stav odpovědi
Kromě standardních stavů HTTP může rozhraní API vrátit následující stav HTTP:
| Kód | Popis |
|---|---|
| 410 – Pryč | Odkaz manifestu je aktivní pouze po určitou dobu trvání nastavenou serverem. Po uplynutí této doby musíte odeslat nový požadavek pro přístup k manifestu. |
Datová část odpovědi
Datová část odpovědi rozhraní API obsahuje následující atributy:
| Atribut | Požadováno | Popis |
|---|---|---|
| ID | True | Jedinečné ID pro každou odpověď. Povinný: |
| stav | True | Hodnoty a akce (povinné): notstarted: Počkejte na dobu uvedenou v hlavičce Opakovat až po, a pak proveďte další volání, které zkontroluje stav. running: Počkejte na dobu uvedenou v hlavičce "Opakovat až po" a pak proveďte další volání, které zkontroluje stav. úspěch: Data jsou připravená. Načtěte datovou část manifestu pomocí identifikátoru URI zadaného v resourceLocation. Selhalo: Operace se trvale nezdařila. Restartujte ho. |
| createdDateTime | True | Čas provedení požadavku. Povinný: |
| lastActionDateTime | True | Čas poslední změny stavu Povinný: |
| resourceLocation | False | Identifikátor URI datové části manifestu. Nepovinné. |
| chyba | False | Pokud operace selže, podrobnosti o chybě se zadají ve formátu JSON. Nepovinné. Mohou být zahrnuty následující atributy: message (Povinné): Podrobný popis chyby. code (Povinné): Typ chyby, ke které došlo. |
Objekt umístění prostředku
| Atribut | Popis |
|---|---|
| ID | Jedinečný identifikátor manifestu. |
| schemaVersion | Verze schématu manifestu |
| dataFormat | Formát souboru fakturačních dat compressedJSON: formát dat, kde každý objekt blob je komprimovaný soubor, který obsahuje data ve formátu řádků JSON . Pokud chcete načíst data z každého objektu blob, dekomprimujte je. |
| createdDateTime | Datum a čas vytvoření souboru manifestu |
| eTag | Verze dat manifestu Změna fakturačních údajů vygeneruje novou hodnotu. |
| partnerTenantId | ID tenanta partnera. |
| rootDirectory | Kořenový adresář souboru. |
| sasToken | Token SAS (sdílený přístupový podpis), který umožňuje číst všechny soubory v adresáři. |
| partitionType | Rozdělí data do více objektů blob na základě atributu partitionValue . Systém rozdělí oddíly, které překračují podporované číslo. Ve výchozím nastavení jsou data rozdělena na oddíly podle počtu řádků v souboru. Nenastavujte v kódu pevný počet řádků nebo velikost souboru, protože se tyto hodnoty můžou změnit. |
| blobCount | Celkový počet souborů pro toto ID tenanta partnera |
| objekty blob | Pole JSON objektů blob, které obsahují podrobnosti o souboru pro ID partnerského tenanta. |
| Objekt blob | Objekt, který obsahuje následující podrobnosti: |
| name | Název objektu blob. |
| partitionValue | Oddíl obsahující soubor. Velký oddíl je rozdělen do více souborů, přičemž každý soubor obsahuje stejný "partitionValue". |
Požadavek rozhraní API
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Odpověď rozhraní API
Odpověď doporučuje čekat 10 sekund před dalším pokusem při zpracování dat.
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"
}
Požadavek rozhraní API
(10 sekund po předchozím požadavku...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Odpověď rozhraní API
Rozhraní API vrátí stav "úspěch" a identifikátor URI pro "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": "0e195b37-4574-4539-bc42-0e539b9684c0",
"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"
}
\]
}
}
Krok 3: Stažení položek řádku s vyrovnáním denního poměru využití ze služby Azure Blob Storage
Získejte token sdíleného přístupového podpisu (SAS) a umístění úložiště objektů blob z vlastností sasToken a rootDirectory, které odpovídá 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 JSONLines .
Tip
Podívejte se na náš ukázkový kód pro stažení a rozbalení souboru objektu blob Azure do místní databáze.
Stavy odpovědí standardního rozhraní API
Z odpovědi rozhraní API můžete obdržet tyto stavy HTTP:
| Kód | Popis |
|---|---|
| 400 – Chybný požadavek | Požadavek chybí nebo obsahuje nesprávná data. Podrobnosti o chybě najdete v textu odpovědi. |
| 401 – Neautorizováno | Volající není ověřený a před prvním voláním se musíte ověřit ve službě partnerského rozhraní API. |
| 403 – Zakázáno | K provedení požadavku nemáte potřebnou autorizaci. |
| 404 – Nenalezena | Požadované prostředky nejsou k dispozici se zadanými vstupními parametry. |
| 410 – Pryč | Vypršel časový limit odkazu manifestu nebo vypršela jeho platnost. Odešlete novou žádost. |
| 500 – Vnitřní chyba serveru | Rozhraní API nebo jedna z jejích závislostí teď nemůže požadavek splnit. Zkuste to později. |
| 5000 – Nejsou k dispozici žádná data | Systém nemá žádná data pro zadané vstupní parametry. |
Porovnání beta verzí a verzí GA
V tabulce porovnání najdete informace o rozdílech mezi beta a obecně dostupnou verzí (GA). Pokud používáte beta verzi, přechod na verzi GA by měl být jednoduchý.
| Důležité informace | Beta | Obecně dostupné |
|---|---|---|
| Koncový bod hostitele rozhraní API | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| Metoda HTTP: | POST | POST |
| Nefakturovaný koncový bod rozhraní API pro denní hodnocení využití | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| Vstupní parametry pro rozhraní API pro nefakturované denní využití | Pokud chcete zadat parametry v požadavku rozhraní API, zahrňte je do řetězce dotazu adresy URL požadavku. Pokud například chcete zadat parametry period a currencyCode, připojte ?period=current¤cyCode=usd se k adrese URL požadavku. |
Pokud chcete zadat vstupy, zahrňte do textu požadavku objekt JSON. Objekt JSON by měl obsahovat následující vlastnosti: * currencyCode: Kód měny pro fakturu. Například USD. * billingPeriod: Fakturační období faktury. Například aktuální. Tady je příklad objektu JSON, který obsahuje vlastnosti currencyCode a billingPeriod: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Koncový bod rozhraní API fakturovaného denního poměru využití | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| Vstupní parametry pro rozhraní API fakturovaného denního hodnocení využití | Pokud chcete zadat parametry v požadavku rozhraní API, zahrňte do adresy URL požadavku ID faktury. Kromě toho můžete do řetězce dotazu zahrnout volitelný parametr fragmentu, který načte úplnou sadu atributů. Pokud například chcete načíst úplnou sadu atributů, připojte ?fragment=full se k adrese URL požadavku. |
Pokud chcete zadat vstupy, zahrňte do textu požadavku objekt JSON. Objekt JSON by měl obsahovat následující vlastnosti: * invoiceId: ID faktury. Například G00012345. * attributeSet: Sada atributů, které se mají zahrnout do odpovědi. Například úplná. Tady je příklad objektu JSON, který obsahuje vlastnosti invoiceId a attributeSet: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| Prostředek manifestu | K načtení prostředku manifestu použijte samostatnou metodu GET /manifests/{id}. | Použijte metodu GET /operations/{Id}, která vrátí související prostředek manifestu v resourceLocation a eliminuje potřebu samostatného volání metody GET /manifests/{id}. |
| Změny schématu manifestu | ||
| "id": Není k dispozici | "id": Jedinečný identifikátor prostředku manifestu. | |
| "version": K dispozici | "version": přejmenováno na "schemaversion". | |
| "dataFormat": K dispozici | "dataFormat": K dispozici. | |
| "utcCretedDateTime": K dispozici | "utcCretedDateTime": přejmenováno na "createdDateTime". | |
| "eTag": K dispozici | "eTag": K dispozici. | |
| PartnerTenantId: K dispozici | PartnerTenantId: K dispozici | |
| RootFolder: K dispozici | RootFolder: přejmenováno na rootDirectory. | |
| RootFolderSAS: K dispozici | RootFolderSAS: přejmenováno na sasToken. Teď poskytuje token a už neobsahuje cestu ke kořenovému adresáři. Pokud chcete získat přístup k adresáři, použijte místo toho vlastnost rootDirectory. | |
| PartitionType: K dispozici | "partitionType": K dispozici. | |
| "blobCount": K dispozici | "blobCount": K dispozici. | |
| SizeInBytes: K dispozici | SizeInBytes: Není k dispozici. | |
| "Objekty blob": K dispozici | "Objekty blob": K dispozici. | |
| "Objekt blob": K dispozici | Objekt blob: K dispozici. | |
| "name": K dispozici | "name": K dispozici. | |
| "partitionValue": K dispozici | "partitionValue": K dispozici. |
Atributy položky řádku s vyrovnáním denního poměru využití
Pokud chcete porovnat atributy vrácené rozhraním API pro odsouhlasení denního poměru využití pro "úplné" nebo "základní" sady atributů, projděte si následující informace.
| Atribut | Úplný | Basic |
|---|---|---|
| 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 |
Důležité
Tyto změny si poznamenejte při přechodu na rozhraní API verze 2 z verze 1.
Název každého atributu začíná velkými písmeny.
UnitOfMeasure je nyní Unit. Význam a hodnota atributu jsou stejné.
resellerMpnId je teď Tier2MpnId. Význam a hodnota atributu jsou stejné.
Název a hodnota rateOfPartnerEarnedCredit se změnily na PartnerEarnedCreditPercentage. Nový název a hodnota atributu odrážejí procento místo zlomku. Například 0,15 je teď 15.
RateOfCredit je nyní CreditPercentage. Význam a hodnota atributu se změnily. Například 1,00 je teď 100.
Ukázkový kód
Další informace najdete v ukázkách rozhraní API Partnerského centra: Získání údajů o reconu fakturace.
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