Rozhraní API pro vyúčtování faktury v2 (GA)
Platí pro: Partnerské centrum (nedostupné v suverénním cloudu)
Naše asynchronní rozhraní API nabízí rychlejší a lépe spravovatelný způsob přístupu k datům fakturace a odsouhlasení prostřednictvím objektů blob Azure. S tímto rozhraním API nemusíte udržovat připojení otevřené po dobu hodin nebo procházet dávky 2 000 řádkových položek najednou.
Optimalizovali jsme naše nové rozhraní API pro odsouhlasení faktur faktur účtované obchodem pomocí klíče valet a asynchronního vzoru odpovědi na požadavky. 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.
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.
Toto rozhraní API můžete použít jenom pro veřejný nebo globální cloud MS Graph. Zatím není k dispozici pro Azure Government, Azure Germany nebo Azure China 21Vianet.
Přehled rozhraní API
Pokud chcete načíst fakturovaná data vyúčtování nových obchodních faktur asynchronně, použijte dva koncové body rozhraní API. Postup je následující:
Koncový bod vyúčtování faktury
Toto rozhraní API slouží k načtení nových řádkových položek faktur faktur faktury faktury faktury. Rozhraní API vrátí stav HTTP 202 a hlavičku umístění obsahující adresu 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ý 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". Výchozí hodnota je úplná. (Podívejte se na seznam atributů v tomto článku). Nepovinné. |
| 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
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. Další možné stavy založené na vašich požadavcích jsou uvedené ve stavech odpovědí standardního rozhraní API v tomto článku.
| 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í". Adresu URL manifestu získáte v atributu resourceLocation, pokud je požadavek úspěšný.
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é ID pro kontrolu stavu žádosti. 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
Text požadavku
Není k dispozici.
Stav odpovědi
Kromě standardních stavů HTTP uvedených ve stavech odpovědí standardního rozhraní API v tomto článku může rozhraní API vrátit 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ž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é. Zahrnuté jsou následující atributy: zpráva: Podrobný popis chyby. kód: 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 tyto hodnoty se 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, který obsahuje soubor. Velký oddíl je rozdělen do více souborů, přičemž každý soubor obsahuje stejný "partitionValue". |
| 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 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": "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í fakturovaných dat odsouhlasení faktur 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. Sada AZURE Storage SDK nebo nástroj pro stažení a rozbalení souboru 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
Tyto stavy HTTP můžete získat z odpovědi rozhraní API:
| 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 musíte provést ověření 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 dostupné se zadanými vstupními parametry. |
| 410 – Pryč | Odkaz manifestu již není platný nebo aktivní. 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. |
Atributy fakturovaných dat odsouhlasení faktur
Pokud chcete porovnat atributy vrácené rozhraním API pro odsouhlasení faktury za "úplné" nebo "základní" sady atributů, projděte si následující tabulku.
| 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 |
Ukázkový kód
Pokyny k používání rozhraní API najdete na následujícím odkazu, který obsahuje ukázkový kód v jazyce C#.
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