Sdílet prostřednictvím


Fakturované a nefakturované rozhraní API pro odsouhlasení využití v2 (GA)

Platí pro: Partnerské centrum (nedostupné ve službě Azure Government nebo Azure China 21Vianet.)

Naše nové asynchronní rozhraní API nabízí rychlejší a efektivnější způsob přístupu k datům fakturace a odsouhlasení prostřednictvím objektů blob Azure. Místo toho, abyste nechávali připojení otevřené po celé hodiny nebo zpracovávali dávky s 2 000 řádkovými položkami, můžete teď zjednodušit pracovní postup, snížit zatížení serveru a zkrátit dobu zpracování dat.

Nová obchodní rozhraní API pro odsouhlasení denního poměru využití používají pokročilé techniky, jako jsou valet key a asynchronní vzory odpovědí na žádosti. Vzor klíče valet umožňuje zabezpečený přístup k prostředkům bez sdílení přihlašovacích údajů, zatímco vzor asynchronní odpovědi na požadavek umožňuje efektivní komunikaci mezi systémy.

Tato rozhraní API poskytují token sdíleného přístupového podpisu (SAS), který můžete použít pro přístup ke všem atributům nebo podmnožině dat odsouhlasení denního hodnocení využití. Tento token vylepšuje zabezpečení tím, že uděluje omezený přístup a nabízí flexibilitu při správě přístupových oprávnění k datům.

Přijetím našich optimalizovaných rozhraní API můžete dosáhnout rychlejších výsledků s menším úsilím, zjednodušením přístupu k datům a zlepšením celkové efektivity. Využijte tyto nástroje ke zjednodušení pracovního postupu a efektivnější správě oprávnění.

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 nebo Azure China 21Vianet.

Důležité

Pokud chcete aplikaci povolit přístup k fakturačním datům partnerů, postupujte podle tohoto odkazu a seznamte se se základy ověřování a autorizace pro Microsoft Graph. Tento krok je zásadní, protože zajišťuje, že vaše aplikace bude mít zabezpečený přístup k potřebným datům.

Oprávnění PartnerBilling.Read.All můžete přiřadit pomocí webu Azure Portal nebo Centra pro správu Entra. Postupujte následovně:

  • Zaregistrujte aplikaci na domovské stránce Microsoft Entra v části Registrace aplikací.
  • Pokud chcete udělit potřebná oprávnění, přejděte na stránku aplikace Microsoft Entra. V části Oprávnění rozhraní API vyberte Přidat oprávnění a zvolte obor PartnerBilling.Read.All.

Provedením těchto kroků zajistíte, že vaše aplikace bude mít požadovaný přístup k fakturačním datům partnera.

Poznámka:

Pokud používáte naši beta verzi, pravděpodobně zjistíte, že přechod na obecnou dostupnost (GA) je hladký a intuitivní. Abychom vám pomohli porozumět aktualizacím a vylepšením, doporučujeme porovnat beta verze a verze GA. Porozumění těmto aktualizacím vám pomůže maximalizovat nové funkce a vylepšení dostupná ve verzi GA.

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ých společností než Microsoft nebo marketplace

Přehled rozhraní API

Abychom vám pomohli asynchronně načíst fakturované nové obchodní položky s denním hodnocením využití, nabízíme dva klíčové koncové body rozhraní API. Pokud chcete rychle a efektivně začít, postupujte podle tohoto zjednodušeného průvodce.

Koncový bod řádkové položky využití

Nejprve pomocí tohoto rozhraní API načtěte nové obchodní položky s denním hodnocením využití. Při vytváření požadavku obdržíte stav HTTP 202 a hlavičku umístění s adresou URL. Tuto adresu URL pravidelně dotazujte, dokud nedostanete stav úspěchu a adresu URL manifestu.

Koncový bod stavu operace

V dalším kroku pokračujte kontrolou stavu operace voláním tohoto rozhraní API v pravidelných intervalech. Pokud data nejsou připravená, odpověď obsahuje hlavičku Opakování po označující, jak dlouho se má čekat, než se pokusíte znovu. Po dokončení operace obdržíte prostředek manifestu s odkazem na složku úložiště pro stažení dat o využití. Odezva segmentuje soubory za účelem zvýšení propustnosti a umožnění paralelismu vstupně-výstupních operací.

Pomocí těchto kroků můžete efektivně spravovat proces odsouhlasení faktur.

Sekvenční diagram

Tady je sekvenční diagram, který ukazuje kroky pro stažení dat odsouhlasení.

Diagram znázorňující kroky pro stažení 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í.

Poznámka:

K nefakturované denní hodnotě využití se dostanete prostřednictvím rozhraní API nebo portálu Partnerského centra. Aby byla zajištěna přesnost dat, může trvat až 24 hodin, než budou k dispozici. 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í. Někdy se může stát, že nejnovější nefakturované denní údaje o využití se nemusí zobrazovat, dokud nebudou k dispozici fakturovaná data z předchozího měsíce. Jakmile obdržíte fakturovaná data, můžete získat přístup ke všem aktualizovaným nefakturovaným datům o využití od začátku měsíce.

klíčové body:

  • Počkejte až 24 hodin pro dostupnost dat.
  • V závislosti na časech hlášení polohy a měřičů může docházet k dalším zpožděním.
  • Fakturovaná data o využití s denním hodnocením mají přednost před nefakturovanými daty.

Vaše porozumění a trpělivost si vážíme, když se snažíme poskytovat co nejpřesnější a včasné informace.

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". Pokud není zadána, je výchozí hodnotou "full". Zkontrolujte seznam atributů v této části. Volitelné.
billingPeriod True String Pokud chcete získat nefakturované denní poměrné využití, použijte "aktuální" pro aktuální fakturační období nebo "poslední" pro předchozí fakturační období (stejné jako "předchozí" v rozhraní 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

Rozhraní API obvykle reaguje se stavem HTTP 202. V závislosti na vašich požadavcích můžete také narazit na jiné stavy. Tyto stavy jsou uvedeny v části Stavy odpovědí standardního 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". Pokud není zadána, je výchozí hodnotou "full". Zkontrolujte seznam atributů v této části. Volitelné.
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 podle vašich požadavků vizte v statusech.

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 sledovat stav požadavku, ujistěte se, že obdržíte odpověď HTTP 200, což je standardní stavový kód označující "úspěch" nebo "selhání". V případě úspěchu najdete adresu URL manifestu v atributu resourceLocation. Tento atribut poskytuje koncový bod pro přístup k požadovaným informacím.

Získání stavu operace

Načte stav požadavku.

Požadavek rozhraní API

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

Parametry požadavku
Název Zahrnout do Požaduje se Type Popis
operationId Identifikátor URI žádosti True String Jedinečný identifikátor pro kontrolu stavu požadavku. 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 uvedených ve stavech odpovědí standardového rozhraní API může rozhraní API vrátit také následující stav HTTP:

Kód Popis
410 – Pryč Odkaz manifestu vyprší po nastaveném čase. Pokud chcete znovu získat odkaz na manifest, odešlete nový požadavek.
Datová část odpovědi

Datová část odpovědi rozhraní API obsahuje následující atributy:

Atribut Požaduje se Popis
ID True Jedinečný identifikátor pro každou odpověď. Povinný:
stav True Hodnoty a akce: Povinné:

nezahájené: Počkejte po zadanou dobu podle pole hlavičky "Retry-After" a poté znovu zavolejte pro kontrolu stavu.

spuštění: Počkejte po určenou dobu v hlavičce 'Retry-After' a potom znovu zkontrolujte 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. Volitelné.
chyba False Podrobnosti o všech chybách ve formátu JSON
Volitelné.
Zahrnuté atributy:
zpráva: Popis chyby.
kód: Typ chyby.
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 Microsoft Entra 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. Vyhněte se pevně zakódování počtu položek řádků nebo velikostí souborů, protože by se mohly 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 obsahující následující podrobnosti: name a partitionValue
name Název objektu blob.
partitionValue Oddíl obsahující soubor. Velký oddíl je rozdělen do více souborů na základě určitých kritérií, jako velikost souboru nebo počet záznamů, 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": "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"

            }

        \]

    }

}

Krok 3: Stažení položek řádku s vyrovnáním denního poměru využití ze služby Azure Blob Storage

Nejprve musíte získat token sdíleného přístupového podpisu (SAS) a umístění úložiště objektů blob. Tyto podrobnosti najdete ve vlastnostech sasToken a rootDirectory odpovědi rozhraní API datové části manifestu. Pak stáhněte a rozbalte soubor objektu blob pomocí sady AZURE Storage SDK nebo nástroje. Je ve formátu JSONLines .

Tip

Nezapomeňte se podívat na náš ukázkový kód. Ukazuje, jak stáhnout a rozbalit soubor objektů 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 Před prvním voláním se vyžaduje ověřování. Ověřte se pomocí partnerské služby 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č Odkaz manifestu už není platný nebo aktivní. Odešlete novou žádost.
500 – Vnitřní chyba serveru Rozhraní API nebo její závislosti teď nemůžou 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

Podívejte se na tabulku porovnání a podívejte se na rozdíly mezi beta a obecně dostupnými verzemi (GA). Pokud aktuálně používáte beta verzi, přechod na verzi GA je jednoduchý a snadný.

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&currencyCode=usd se k adrese URL požadavku.
Pokud chcete zadat vstupy, zahrňte do textu požadavku objekt JSON. Váš JSON by měl mít následující vlastnosti:
* currencyCode: Vaše fakturační měna. Například USD.
* billingPeriod: Fakturační období faktury. Například aktuální.
Tady je ukázkový objekt 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. Váš JSON by měl mít následující vlastnosti:
* invoiceId: Jedinečný identifikátor faktury. Například G00012345.
* attributeSet: Atributy, které by měly být v odpovědi, například úplné.
Tady je ukázkový objekt 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}. K přístupu k prostředku manifestu v resourceLocation použijte metodu GET /operations/{Id}. Tato metoda šetří čas tím, že eliminuje potřebu samostatného volání GET /manifests/{id}.
Změny schématu manifestu
"id": Není k dispozici "id": Jedinečný identifikátor prostředku manifestu.
"version": K dispozici "version": změněno na "schemaversion".
"dataFormat": K dispozici "dataFormat": K dispozici.
"utcCretedDateTime": K dispozici "utcCretedDateTime": změněno na "createdDateTime".
"eTag": K dispozici "eTag": K dispozici.
PartnerTenantId: K dispozici PartnerTenantId: K dispozici
RootFolder: K dispozici RootFolder: změnil se na rootDirectory.
RootFolderSAS: K dispozici RootFolderSAS: změnil se na sasToken. Tato aktualizace poskytuje pouze token bez cesty ke kořenovému adresáři. K vyhledání adresáře 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é fakturovaným nebo nefakturovaným rozhraním API pro odsouhlasení využití pro "úplné" nebo "základní" sady atributů, projděte si tuto tabulku. Další informace o těchto atributech a jejich významech najdete v této dokumentaci.

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
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

Důležité

Tyto změny si poznamenejte při přechodu z rozhraní API v1 na v2.

  • Každý název atributu teď začíná velkými písmeny písmenem, aby se zachovala konzistence se souborem a zlepšila čitelnost.

  • UnitOfMeasure se aktualizuje na Jednotku. Jeho význam a hodnota zůstávají beze změny, což zjednodušuje název atributu.

  • resellerMpnId je teď Tier2MpnId. Význam a hodnota jsou stejné.

  • RateOfPartnerEarnedCredit se aktualizuje na PartnerEarnedCreditPercentage. Nový název a hodnota teď odrážejí procento místo zlomku, aby bylo snazší porozumět. Například 0,15 je teď 15 %.

  • RateOfCredit je nyní CreditPercentage. Název i hodnota se změnily, aby byly srozumitelnější. Například 1,00 je teď 100 %.

Věříme, že tyto změny dělají rozhraní API intuitivnější a snadněji se používají.

Ukázkový kód

Pokud chcete toto rozhraní API použít, podívejte se na následující odkaz, který obsahuje ukázkový kód jazyka C#.

Ukázky rozhraní API Partnerského centra: Získání údajů o fakturaci