API för fakturerad fakturaavstämning v2 (GA)
Gäller för: Partnercenter (ej tillgängligt i nationellt moln)
Vårt asynkrona API erbjuder ett snabbare och mer hanterbart sätt att komma åt fakturerings- och avstämningsdata via Azure-blobar. Med det här API:et behöver du inte hålla en anslutning öppen i timmar eller loopa genom batcharna med 2 000 radobjekt åt gången.
Vi har optimerat vårt nya API för fakturering av fakturaavstämning med hjälp av valet-nyckel och asynkrona mönster för begärandesvar . Det här API:et ger dig en SAS-token (signatur för delad åtkomst) som du kan använda för att komma åt antingen alla attribut eller en delmängd av fakturaavstämningsdata.
Kommentar
Det nya API:et finns inte på API-värden för Partnercenter. I stället kan du hitta den i MS Graph på Använda Microsoft Graph API för att exportera partnerfaktureringsdata – Microsoft Graph v1.0. Om du vill komma åt det här API:et läser du följande information.
Viktigt!
Om du vill ge din app den behörighet som krävs för att få åtkomst till partnerfaktureringsdata måste du följa den här länken och lära dig mer om grunderna för autentisering och auktorisering för Microsoft Graph.
Vanligtvis kan du använda antingen Azure-portalen eller Administrationscenter för Entra för att tilldela den behörighet som krävs: "PartnerBilling.Read.All". Här är stegen för att göra det:
- Registrera din app på Microsoft Entra-startsidan under avsnittet Appregistreringar.
- Tilldela behörighet till din app på sidan Microsoft Entra-app under avsnittet API-behörigheter. Välj "Lägg till en behörighet" och välj omfånget "PartnerBilling.Read.All".
API-översikt
Om du vill hämta fakturerade nya handelsfakturaavstämningsdata asynkront använder du två API-slutpunkter. Så här gör du:
Slutpunkt för fakturerad fakturaavstämning
Använd det här API:et för att hämta nya fakturerade fakturaavstämningsradobjekt för handel . API:et returnerar en HTTP-status för 202 och en platsrubrik som innehåller en URL. Avsök den här URL:en med jämna mellanrum tills du får en lyckad status med en manifest-URL.
Slutpunkt för åtgärdsstatus
Om du vill få statusen lyckad fortsätter du att anropa det här API:et med jämna mellanrum. Om data inte är klara innehåller API-svaret ett återförsökshuvud för att berätta hur lång tid det tar att vänta innan du försöker igen. När åtgärden är klar får du en manifestresurs med en lagringsmapp där du kan ladda ned användningsdata. Svaret delar upp filerna i mindre delar för optimerat dataflöde och I/O-parallellitet.
Sekvensdiagram
Här är ett sekvensdiagram som visar stegen för att ladda ned nya handelsfakturaavstämningsdata.
Åtgärdssekvens för användare
Följ dessa steg för att hämta fakturerade fakturaavstämningsdata:
Steg 1: Skicka begäran
Skicka en POST-begäran till API-slutpunkten.
Hämta fakturerade fakturaavstämningsradobjekt
API-begäran
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
Frågeparametrar
Ej tillämpligt
Begärandetext
| Attribut | Obligatoriskt | Type | Beskrivning |
|---|---|---|---|
| attributeSet | Falsk | String | Välj "fullständig" för alla attribut eller "grundläggande" för en begränsad uppsättning. Standardvärdet är "full". (Se listan över attribut i den här artikeln). Valfritt. |
| invoiceId | Sant | String | En unik identifierare för varje faktura. Obligatoriskt. |
Begärandehuvuden
Begär rubriker för API:et med hjälp av de steg som anges i Metodtips för att använda Microsoft Graph.
API-svar
HTTP/1.1 202 Accepted
Location: <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API:et svarar vanligtvis med http 202-status. Andra möjliga statusar, baserat på dina begäranden, visas i Standard API-svarsstatusar i den här artikeln.
| Kod | beskrivning |
|---|---|
| 202 – Godkänd | Din begäran godkändes. Om du vill kontrollera statusen för din begäran frågar du url:en som anges i platsrubriken. |
Steg 2: Kontrollera status för begäran
Om du vill kontrollera status för en begäran väntar du på ett HTTP 200-svar med statusen "lyckades" eller "misslyckades". Du får manifest-URL:en i attributet "resourceLocation" om begäran lyckas.
Hämta åtgärdsstatus
Hämtar status för en begäran.
API-begäran
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Parametrar för begäran
| Name | Inkludera i | Obligatoriskt | Type | Beskrivning |
|---|---|---|---|---|
| operationId | URI för förfrågan | Sant | String | Ett unikt ID för att kontrollera status för begäran. Obligatoriskt. |
Begärandehuvud
Begär rubriker för API:et med hjälp av de steg som anges i Metodtips för att använda Microsoft Graph.
Begärandetext
Saknas.
Svarsstatus
Förutom de standard-HTTP-statusar som anges i Standard API-svarsstatusar i den här artikeln kan API:et returnera följande HTTP-status:
| Kod | beskrivning |
|---|---|
| 410 – Borta | Manifestlänken upphör att gälla efter en angiven tid. Om du vill hämta manifestlänken igen skickar du en ny begäran. |
Svarsnyttolast
API-svarsnyttolasten innehåller följande attribut:
| Attribut | Obligatoriskt | Beskrivning |
|---|---|---|
| id | Sant | Ett unikt ID för varje svar Obligatoriskt. |
| status | Sant | Värden och åtgärder: Krävs. notstarted: Vänta tills den tid som anges i rubriken "Försök igen" och gör sedan ett nytt anrop för att kontrollera statusen. körs: Vänta tills den tid som anges i rubriken "Försök igen" och gör sedan ett nytt anrop för att kontrollera statusen. lyckades: Data är klara. Hämta manifestnyttolasten med hjälp av den URI som anges i resourceLocation. misslyckades: Åtgärden misslyckades permanent. Starta om den. |
| createdDateTime | Sant | Den tid då begäran gjordes. Obligatoriskt. |
| lastActionDateTime | Sant | Den tid då statusen senast ändrades. Obligatoriskt. |
| resourceLocation | Falsk | URI:n för manifestnyttolasten. Valfritt. |
| fel | Falsk | Om åtgärden misslyckas anges felinformation i JSON-format. Valfritt. Följande attribut ingår: meddelande: En detaljerad beskrivning av felet. kod: Den typ av fel som inträffade. |
Resursplatsobjekt
| Attribut | Beskrivning |
|---|---|
| id | En unik identifierare för manifestet. |
| schemaVersion | Version av manifestschemat. |
| dataFormat | Format för faktureringsdatafilen. compressedJSON: Dataformat där varje blob är en komprimerad fil som innehåller data i JSON-linjeformat . Om du vill hämta data från varje blob expanderar du dem. |
| createdDateTime | Datum och tid då manifestfilen skapades. |
| eTag | Version av manifestdata. En ändring i faktureringsinformationen genererar ett nytt värde. |
| partnerTenantId | ID för partnerns klientorganisation. |
| rootDirectory | Rotkatalogen för filen. |
| sasToken | SAS-token (signatur för delad åtkomst) som gör att du kan läsa alla filer under katalogen. |
| partitionType | Delar upp data i flera blobar baserat på attributet partitionValue . Systemet delar partitioner som överskrider det antal som stöds. Som standard partitioneras data baserat på antalet radobjekt i filen. Ange inte ett fast antal radobjekt eller filstorlek i koden eftersom dessa värden kan ändras. |
| blobCount | Totalt antal filer för det här partnerklient-ID:t. |
| blobar | En JSON-matris med "blob"-objekt som innehåller filinformationen för partnerklient-ID:t. |
| blob-objekt | Ett objekt som innehåller följande information: name: Namnet på bloben. partitionValue: Partition som innehåller filen. Den stora partitionen är uppdelad i flera filer, där varje fil innehåller samma "partitionValue". |
| name | Namnet på bloben. |
| partitionValue | Partition som innehåller filen. Den stora partitionen är uppdelad i flera filer, där varje fil innehåller samma "partitionValue". |
API-begäran
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-svar
Svaret rekommenderar att du väntar i 10 sekunder innan du försöker igen när dina data fortfarande bearbetas.
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-begäran
(10 sekunder efter föregående begäran...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-svar
API:et returnerar statusen "lyckades" och URI:n för "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"
}
\]
}
}
Steg 3: Ladda ned fakturerade fakturaavstämningsdata från Azure Blob Storage
Hämta sas-token (signatur för delad åtkomst) och bloblagringsplatsen från "sasToken" och "rootDirectory" egenskaperna för api-svaret för manifestnyttolasten. Azure Storage SDK/verktyg för att ladda ned och packa upp blobfilen. Den är i JSONLines-format .
Dricks
Kolla in vår exempelkod för att ladda ned och packa upp Azure-blobfilen till din lokala databas.
Standard-API-svarsstatusar
Du kan få dessa HTTP-statusar från svaret från API:et:
| Kod | beskrivning |
|---|---|
| 400 – Felaktig begäran | Begäran saknas eller innehåller felaktiga data. Kontrollera svarstexten om du vill ha felinformation. |
| 401 – behörighet saknas | Anroparen är inte autentiserad och du måste autentisera med partner-API-tjänsten innan du gör det första anropet. |
| 403 – förbjuden | Du har inte den behörighet som krävs för att göra begäran. |
| 404 – Hittades inte | De begärda resurserna är inte tillgängliga med de angivna indataparametrarna. |
| 410 – Borta | Manifestlänken är inte längre giltig eller aktiv. Skicka en ny begäran. |
| 500 – Internt serverfel | API:et eller något av dess beroenden kan inte uppfylla begäran just nu. Försök igen senare. |
| 5000 – Inga tillgängliga data | Systemet har inga data för de angivna indataparametrarna. |
Dataattribut för fakturerad fakturaavstämning
Om du vill jämföra attributen som returneras av API:et för fakturerad fakturaavstämning för attributuppsättningarna "full" eller "basic" läser du följande tabell.
| Attribut | Fullständig | Grundläggande |
|---|---|---|
| PartnerId | ja | ja |
| CustomerId | ja | ja |
| CustomerName | ja | ja |
| CustomerDomainName | ja | nej |
| CustomerCountry | ja | nej |
| InvoiceNumber | ja | ja |
| MpnId | ja | nej |
| Tier2MpnId | ja | ja |
| OrderId | ja | ja |
| OrderDate | ja | ja |
| Produkt-ID | ja | ja |
| SkuId | ja | ja |
| AvailabilityId | ja | ja |
| SkuName | ja | nej |
| ProductName | ja | ja |
| ChargeType | ja | ja |
| UnitPrice | ja | ja |
| Kvantitet | ja | nej |
| Delsumma | ja | ja |
| TaxTotal | ja | ja |
| Totalt | ja | ja |
| Valuta | ja | ja |
| PriceAdjustmentDescription | ja | ja |
| PublisherName | ja | ja |
| PublisherId | ja | nej |
| SubscriptionDescription | ja | nej |
| SubscriptionId | ja | ja |
| ChargeStartDate | ja | ja |
| ChargeEndDate | ja | ja |
| TermAndBillingCycle | ja | ja |
| EffectiveUnitPrice | ja | ja |
| UnitType | ja | nej |
| AlternateId | ja | nej |
| BillableQuantity | ja | ja |
| BillingFrequency | ja | nej |
| PricingCurrency | ja | ja |
| PCToBCExchangeRate | ja | ja |
| PCToBCExchangeRateDate | ja | nej |
| MeterDescription | ja | nej |
| ReservationOrderId | ja | ja |
| CreditReasonCode | ja | ja |
| SubscriptionStartDate | ja | ja |
| SubscriptionEndDate | ja | ja |
| ReferenceId | ja | ja |
| ProductQualifiers | ja | nej |
| PromotionId | ja | ja |
| ProductCategory | ja | ja |
Exempelkod
Vägledning om hur du använder API:et finns i följande länk som innehåller exempelkod i C#.
Feedback
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i: https://aka.ms/ContentUserFeedback.
Skicka och visa feedback för