Számlázott számlaegyeztetési API v2 (GA)
A következőkre vonatkozik: Partnerközpont (független felhőben nem érhető el)
Az aszinkron API gyorsabb és kezelhetőbb módot kínál a számlázási és egyeztetési adatok Azure-blobokon keresztüli elérésére. Ezzel az API-val nem kell órákig nyitva tartania a kapcsolatot, és nem kell egyszerre 2000 sortétel kötegeit végighaladnia.
Az új kereskedelmi számlázott számlaegyeztetési API-t valet kulcs és aszinkron kérés-válasz minták használatával optimalizáltuk. Ez az API egy közös hozzáférésű jogosultságkód (SAS) jogkivonatot biztosít, amellyel hozzáférhet az összes attribútumhoz vagy a számlázott számlaegyeztetési adatok egy részhalmazához.
Feljegyzés
Az új API nem a Partnerközpont API-gazdagépén található. Ehelyett az MS Graphon találhatja meg a Microsoft Graph API használatával a partner számlázási adatainak exportálásához – Microsoft Graph 1.0-s verzió. Az API eléréséhez tekintse meg az alábbi részleteket.
Ezt az API-t most csak az MS Graph nyilvános/globális felhőhöz használhatja. Az Azure Government, az Azure Germany vagy az Azure China 21Vianet esetében még nem érhető el.
API – Áttekintés
A számlázott új kereskedelmi számlák egyeztetési adatainak aszinkron lekéréséhez használjon két API-végpontot. Ennek folyamata a következő:
Számlázott számlaegyeztetési végpont
Ezzel az API-val lekérheti az új kereskedelmi számlázású számlaegyeztetési sorelemeket. Az API egy 202-es HTTP-állapotot és egy URL-t tartalmazó helyfejlécet ad vissza. Ezt az URL-címet rendszeres időközönként lekérdezheti, amíg meg nem kapja a sikeres állapotot egy jegyzék URL-címmel.
Műveleti állapot végpontja
A sikeres állapot eléréséhez rendszeresen hívja meg ezt az API-t. Ha az adatok nem állnak készen, az API-válasz tartalmaz egy Újrapróbálkozási fejlécet, amelyből megtudhatja, hogy mennyi ideig kell várnia, mielőtt újra próbálkozna. Ha a művelet befejeződött, egy jegyzékerőforrást kap egy tármappával, ahol letöltheti a használati adatokat. A válasz kisebb részekre bontja a fájlokat az optimalizált átviteli sebesség és az I/O-párhuzamosság érdekében.
Szekvenciadiagram
Íme egy szekvenciadiagram, amely az új kereskedelmi számlák egyeztetési adatainak letöltésének lépéseit mutatja be.
Felhasználói műveletütemezés
A számlázott számlaegyeztetési adatok lekéréséhez kövesse az alábbi lépéseket:
1. lépés: Kérelem elküldése
POST-kérés elküldése az API-végpontnak.
Számlázott számlaegyeztetési sorelemek lekérése
API-kérés
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
Paraméterek lekérdezése
n/a
Kérés törzse
| Attribútum | Kötelező | Típus | Leírás |
|---|---|---|---|
| attributeSet | Hamis | Sztring | Az összes attribútumnál válassza a "full" vagy a "basic" (alapszintű) lehetőséget egy korlátozott készlethez. Az alapértelmezett érték a "teljes". (Lásd a cikkben szereplő attribútumok listáját). Opcionális. |
| invoiceId | Igaz | Sztring | Egyedi azonosító minden számlához. Szükséges. |
Kérésfejlécek
Fejlécek kérése az API-hoz a Microsoft Graph használatának ajánlott eljárásait követve.
API-válasz
HTTP/1.1 202 Accepted
Location: <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Az API általában HTTP 202-es állapottal válaszol. A kéréseken alapuló egyéb lehetséges állapotok a jelen cikkben szereplő Standard API-válaszállapotok között szerepelnek.
| Kód | Leírás |
|---|---|
| 202 – Elfogadva | A kérést elfogadták. A kérés állapotának ellenőrzéséhez kérje le a hely fejlécében megadott URL-címet. |
2. lépés: A kérelem állapotának ellenőrzése
A kérés állapotának ellenőrzéséhez várjon egy HTTP 200-válaszra, amely "sikeres" vagy "sikertelen" állapotú. A jegyzék URL-címét a "resourceLocation" attribútumban kapja meg, ha a kérés sikeres.
Művelet állapotának lekérése
Lekéri egy kérés állapotát.
API-kérés
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Kérelemparaméterek
| Név | Belefoglalás a következőbe: | Kötelező | Típus | Leírás |
|---|---|---|---|---|
| operationId | Kérés URI-ja | Igaz | Sztring | Egyedi azonosító a kérés állapotának ellenőrzéséhez. Szükséges. |
Kérelem fejléce
Fejlécek kérése az API-hoz a Microsoft Graph használatának ajánlott eljárásait követve.
Kérés törzse
N/A.
Reagálási állapot
A cikkben a Standard API válaszállapotaiban felsorolt szabványos HTTP-állapotok mellett az API a következő HTTP-állapotot is visszaadhatja:
| Kód | Leírás |
|---|---|
| 410 – Eltűnt | A jegyzékhivatkozás egy megadott időpont után lejár. A jegyzékhivatkozás ismételt lekéréséhez küldjön egy új kérést. |
Válasz hasznos adatai
Az API-válasz hasznos adatai a következő attribútumokat tartalmazzák:
| Attribútum | Kötelező | Leírás |
|---|---|---|
| id | Igaz | Egyedi azonosító minden válaszhoz Szükséges. |
| status | Igaz | Értékek és műveletek: Kötelező. notstarted: Várja meg az "Újrapróbálkozott" fejlécben megadott időt, majd hozzon létre egy újabb hívást az állapot ellenőrzéséhez. futtatás: Várja meg az "Újrapróbálkozás után" fejlécben megadott időt, majd hozzon létre egy újabb hívást az állapot ellenőrzéséhez. sikeres: Az adatok készen állnak. Kérje le a jegyzékbeli hasznos adatokat a resourceLocationban megadott URI használatával. sikertelen: A művelet véglegesen meghiúsult. Indítsa újra. |
| createdDateTime | Igaz | A kérés teljesítésének időpontja. Szükséges. |
| lastActionDateTime | Igaz | Az állapot legutóbbi módosításának időpontja. Szükséges. |
| resourceLocation | Hamis | A jegyzékbeli hasznos adatok URI-ja. Opcionális. |
| error | Hamis | Ha a művelet sikertelen, a hiba részletei JSON formátumban jelennek meg. Opcionális. A rendszer a következő attribútumokat tartalmazza: üzenet: A hiba részletes leírása. kód: A hiba típusa. |
Erőforrás-hely objektum
API-kérés
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-válasz
A válasz azt javasolja, hogy várjon 10 másodpercig, mielőtt újrapróbálkozna, amikor az adatok feldolgozása még folyamatban van.
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"
}
API-kérés
(10 másodperccel az előző kérés után...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-válasz
Az API a "sikeres" állapotot és a resourceLocation URI-t adja vissza.
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"
}
\]
}
}
3. lépés: Számlázott számlaegyeztetési adatok letöltése az Azure Blob Storage-ból
Kérje le a közös hozzáférésű jogosultságkód (SAS) jogkivonatot és a blobtároló helyét a "sasToken" és a "rootDirectory" tulajdonságból, amely a jegyzék hasznos api-válaszát tartalmazza. Azure Storage SDK/eszköz a blobfájl letöltéséhez és kibontásához. JSONLines formátumban van.
Tipp.
Tekintse meg a mintakódot , amely letölti és kibontja az Azure-blobfájlt a helyi adatbázisba.
Standard API-válaszállapotok
Ezeket a HTTP-állapotokat az API válaszából kaphatja meg:
| Kód | Leírás |
|---|---|
| 400 – Hibás kérés | A kérelem hiányzik, vagy helytelen adatokat tartalmaz. A hiba részleteiért tekintse meg a válasz törzsét. |
| 401 – Jogosulatlan | A hívó nincs hitelesítve, és az első hívás megkezdése előtt hitelesítenie kell magát a partner API szolgáltatással. |
| 403 – Tiltott | Nem rendelkezik a kérés teljesítéséhez szükséges engedéllyel. |
| 404 – Nem található | A kért erőforrások nem érhetők el a megadott bemeneti paraméterekkel. |
| 410 – Eltűnt | A jegyzékhivatkozás már nem érvényes vagy aktív. Küldjön be egy új kérést. |
| 500 – Belső kiszolgálóhiba | Az API vagy annak egyik függősége jelenleg nem tudja teljesíteni a kérést. Próbálkozzon újra később. |
Számlázott számlaegyeztetési adatattribútumok
A számlázott számlaegyeztetési API által a "teljes" vagy az "alapszintű" attribútumkészletekhez visszaadott attribútumok összehasonlításához tekintse meg az alábbi táblázatot.
| Attribútum | Teljes | Alap |
|---|---|---|
| Partnerazonosító | igen | igen |
| Vevőkód | igen | igen |
| CustomerName | igen | igen |
| CustomerDomainName | igen | nem |
| CustomerCountry | igen | nem |
| InvoiceNumber | igen | igen |
| MpnId | igen | nem |
| Tier2MpnId | igen | igen |
| OrderId | igen | igen |
| OrderDate | igen | igen |
| ProductId | igen | igen |
| Termékváltozat azonosítója | igen | igen |
| Rendelkezésre állási azonosító | igen | igen |
| SkuName | igen | nem |
| ProductName | igen | igen |
| ChargeType | igen | igen |
| Egységár | igen | igen |
| Mennyiség | igen | nem |
| Részösszeg | igen | igen |
| TaxTotal | igen | igen |
| Összesen | igen | igen |
| Pénznem | igen | igen |
| PriceAdjustmentDescription | igen | igen |
| Közzétevő neve | igen | igen |
| PublisherId | igen | nem |
| SubscriptionDescription | igen | nem |
| SubscriptionId | igen | igen |
| ChargeStartDate | igen | igen |
| ChargeEndDate | igen | igen |
| TermAndBillingCycle | igen | igen |
| EffectiveUnitPrice | igen | igen |
| UnitType | igen | nem |
| Alternatív azonosító | igen | nem |
| BillableQuantity | igen | igen |
| BillingFrequency | igen | nem |
| PricingCurrency | igen | igen |
| PCToBCExchangeRate | igen | igen |
| PCToBCExchangeRateDate | igen | nem |
| MeterDescription | igen | nem |
| ReservationOrderId | igen | igen |
| CreditReasonCode | igen | igen |
| SubscriptionStartDate | igen | igen |
| SubscriptionEndDate | igen | igen |
| Referenciaazonosító | igen | igen |
| ProductQualifiers | igen | nem |
| PromotionId | igen | igen |
| ProductCategory | igen | igen |
Mintakód
Az API használatával kapcsolatos útmutatásért tekintse meg a C#-ban található mintakódot tartalmazó alábbi hivatkozást.
Visszajelzés
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ: https://aka.ms/ContentUserFeedback.
Visszajelzés küldése és megtekintése a következőhöz: