Rozhraní API pro vyúčtování faktury v2 (GA)
Platí pro: Partnerské centrum (nedostupné v suverénním cloudu)
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, aby bylo připojení otevřené po dobu hodin nebo zpracování dávek s 2 000 řádkovými položkami, můžete teď zjednodušit pracovní postup, snížit zatížení serveru a zlepšit dobu zpracování dat.
Nové rozhraní API pro odsouhlasení faktur faktur účtované obchodem používá pokročilé techniky, jako jsou klíče valet 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.
Toto rozhraní API poskytuje 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ě fakturovaných dat odsouhlasení faktury. 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 není hostované na hostiteli rozhraní API Partnerského centra. Místo toho ji najdete v MS Graphu pomocí rozhraní Microsoft Graph API k exportu fakturačních dat partnerů – Microsoft Graph v1.0. Pokud chcete získat přístup k tomuto rozhraní API, projděte si následující podrobnosti.
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.
Přehled rozhraní API
Abychom vám pomohli načíst fakturované nové řádkové položky vyrovnání faktury pro obchodování asynchronně, 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 vyúčtování faktury
Nejprve pomocí tohoto rozhraní API načtěte nové položky faktury fakturované fakturou. 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ý znázorňuje kroky pro stažení dat odsouhlasení nových obchodních faktur.
Pořadí akcí uživatele
Pokud chcete načíst fakturovaná data odsouhlasení faktur, postupujte takto:
Krok 1: Odeslání žádosti
Odešlete požadavek POST do koncového bodu rozhraní API.
Získání fakturovaných položek řádku s vyrovnáním faktury
Požadavek rozhraní API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
Parametry dotazů
–
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é. |
| invoiceId | True | String | Jedinečný identifikátor každé faktury. Povinný: |
Záhlaví žádosti
Hlavičky požadavků pro rozhraní API s využitím kroků uvedených v části Osvědčené postupy pro používání Microsoft Graphu Podle těchto pokynů zajistíte spolehlivost a podporu vaší aplikace. Vaše pozornost k podrobnostem v tomto kroku je zásadní pro bezproblémovou integraci a optimální výkon.
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í. |
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
Hlavičky požadavků pro rozhraní API s využitím kroků uvedených v části Osvědčené postupy pro používání Microsoft Graphu Podle těchto pokynů zajistíte spolehlivost a podporu vaší aplikace. Vaše pozornost k podrobnostem v tomto kroku je zásadní pro bezproblémovou integraci a optimální výkon.
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 dobu uvedenou v hlavičce Retry-After a poté proveďte další pokus o kontrolu stavu. spuštění: Počkejte po dobu uvedenou v hlavičce "Retry-After", poté proveďte další volání ke kontrole stavu. ú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 Nová hodnota se vygeneruje vždy, když dojde ke změně fakturačních údajů. |
| 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 and 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 je 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 počkat na 10 sekund, než se pokusíte znovu, když se vaše data stále zpracovávají.
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í fakturovaných řádkových položek vyrovnání faktur z Úložiště objektů blob v Azure
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 se můžou zobrazit 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 dostupné 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. |
Atributy řádkové položky vyúčtování faktury
Pokud chcete porovnat atributy vrácené rozhraním API pro odsouhlasení faktur za "úplné" nebo "základní" sady atributů, projděte si tuto tabulku. Pro více informací o těchto atributech a jejich významech si přečtěte tuto příručku.
| Atribut | Úplný | Basic |
|---|---|---|
| Id partnera | ano | ano |
| CustomerId | ano | ano |
| CustomerName | ano | ano |
| CustomerDomainName | ano | ne |
| CustomerCountry | ano | ne |
| InvoiceNumber | ano | ano |
| MpnId | ano | ne |
| Tier2MpnId | ano | ano |
| OrderId | ano | ano |
| OrderDate | ano | ano |
| ID produktu | ano | ano |
| SkuId | ano | ano |
| AvailabilityId | ano | ano |
| SkuName | ano | ne |
| ProductName | ano | ano |
| ChargeType | ano | ano |
| UnitPrice | ano | ano |
| Množství | ano | ne |
| Dílčí součet | ano | ano |
| TaxTotal | ano | ano |
| Celkem | ano | ano |
| Měna | ano | ano |
| PriceAdjustmentDescription | ano | ano |
| Název vydavatele | ano | ano |
| PublisherId | ano | ne |
| Popis předplatného | ano | ne |
| SubscriptionId | ano | ano |
| ChargeStartDate | ano | ano |
| ChargeEndDate | ano | ano |
| TermAndBillingCycle | ano | ano |
| EffectiveUnitPrice | ano | ano |
| UnitType | ano | ne |
| AlternateId | ano | ne |
| BillableQuantity | ano | ano |
| BillingFrequency | ano | ne |
| PricingCurrency | ano | ano |
| PCToBCExchangeRate | ano | ano |
| PCToBCExchangeRateDate | ano | ne |
| MeterDescription | ano | ne |
| ReservationOrderId | ano | ano |
| CreditReasonCode | ano | ano |
| SubscriptionStartDate | ano | ano |
| SubscriptionEndDate | ano | ano |
| ReferenceId | ano | ano |
| ProductQualifiers | ano | ne |
| PromotionId | ano | ano |
| ProductCategory | 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.
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#.