Gefactureerde en niet-gefactureerde dagelijkse afstemmings-API voor gebruik v2 (GA)
Van toepassing op: Partnercentrum (niet beschikbaar in Azure Government, Azure Duitsland of Azure China 21Vianet.)
Onze asynchrone API's bieden een snellere en beter beheerbare manier om toegang te krijgen tot facturerings- en afstemmingsgegevens via Azure-blobs. Met deze API's hoeft u de verbinding urenlang open te houden of de batches van 2000 regelitems te doorlopen.
We hebben onze nieuwe commerce-api's voor het dagelijks beoordelen van gebruiksafstemming geoptimaliseerd met behulp van valetsleutel en asynchrone aanvraagantwoordpatronen . Wanneer u deze API's gebruikt, ontvangt u een token dat u kunt gebruiken voor toegang tot alle kenmerken of een subset van de dagelijkse afstemmingsgegevens voor gebruik.
Notitie
De nieuwe API's worden niet gehost op de Partner Center API-host. In plaats daarvan kunt u ze vinden in MS Graph op De Microsoft Graph API gebruiken om factureringsgegevens van partners te exporteren - Microsoft Graph v1.0 | Microsoft Learn. Raadpleeg de volgende details om toegang te krijgen tot deze API's.
U kunt deze API's alleen nu gebruiken voor de openbare/wereldwijde MS Graph-cloud. Ze zijn nog niet beschikbaar voor Azure Government, Azure Duitsland of Azure China 21Vianet.
Notitie
Als u onze bètaversie hebt gebruikt, ziet u mogelijk geen belangrijke wijzigingen in de algemeen beschikbare (GA)-versie. We raden u aan de twee versies te vergelijken om inzicht te hebben in de verschillen en updates.
Belangrijk
Het nieuwe dagelijkse gebruik van de handel omvat niet de kosten voor deze producten:
- Azure-reservering
- Azure-besparingsplan
- Office
- Dynamics
- Microsoft Power Apps
- Eeuwigdurende software
- Softwareabonnement
- Niet-Microsoft SaaS-product
API-overzicht
Gebruik twee API-eindpunten om dagelijks geclassificeerde gebruiksregelitems op te halen. Dit is het proces:
Eindpunt van gebruiksregelitem
Gebruik deze API om gefactureerde of niet-gefactureerde dagelijkse gebruiksregelitems op te halen. U krijgt een HTTP-status van 202 en een URL in de locatieheader. Peil deze URL regelmatig totdat u een geslaagde status met een manifest-URL ontvangt.
Eindpunt van bewerkingsstatus
Als u een successtatus wilt krijgen, moet u deze API regelmatig aanroepen. Als de gegevens niet gereed zijn, bevat het API-antwoord een header Opnieuw proberen na om u te laten weten hoe lang moet worden gewacht voordat u het opnieuw probeert. Wanneer de bewerking is voltooid, krijgt u een manifestresource met een opslagmap waarin u de gebruiksgegevens kunt downloaden. Het antwoord breekt de bestanden op in kleinere stukken voor geoptimaliseerde doorvoer en I/O-parallelle uitvoering.
Sequentiediagram
Hier volgt een sequentiediagram met de stappen voor het downloaden van de afstemmingsgegevens.
Gebruikersactiereeks
Voer de volgende stappen uit om nieuwe artikelen voor het dagelijks beoordelen van gebruiksafstemming op te halen:
Stap 1: Aanvraag indienen
Dien een POST-aanvraag in bij het API-eindpunt.
Niet-gefactureerde dagelijkse verbruiksregelitems ophalen
Ontvang nieuwe handelsverkeer niet-gefactureerde dagelijkse verbruiksregelitems voor de huidige of laatste kalendermaand of factureringsperiode.
API-aanvraag
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"
}
Aanvraagtekst
| Kenmerk | Vereist | Type | Description |
|---|---|---|---|
| attributeSet | Onwaar | String | Kies 'volledig' voor alle kenmerken of basic voor een beperkte set. De standaardwaarde is 'vol'. (Zie hier de lijst met kenmerken ). Optioneel. |
| billingPeriod | Waar | String | Gebruik 'current' of 'last' (hetzelfde als 'vorige' in V1-API's) om dagelijks beoordeeld gebruik op te halen voor de huidige of laatste kalendermaand of factureringsperiode. Vereist. |
| currencyCode | Waar | String | Valutacode voor partnerfacturering. Vereist. |
Aanvraagheaders
Als u headers voor de API wilt aanvragen, raadpleegt u Betrouwbaarheid en ondersteuning.
API-reactie
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
Wanneer u de API gebruikt, wordt doorgaans een HTTP 202-status geretourneerd. Als u andere mogelijke statussen wilt zien op basis van uw aanvragen, raadpleegt u de statussen van de Standard-API-respons.
| Code | Beschrijving |
|---|---|
| 202 – Geaccepteerd | Uw aanvraag is geaccepteerd. Als u de status van uw aanvraag wilt controleren, voert u een query uit op de URL die is opgegeven in de locatieheader. |
Gefactureerde dagelijkse verbruiksregelitems ophalen
Ontvang nieuwe commerce gefactureerde dagelijkse verbruiksregelitems voor een factuur voor de gesloten factureringsperiode.
API-aanvraag
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
Queryparameters
N.v.t.
Aanvraagtekst
| Kenmerk | Vereist | Type | Description |
|---|---|---|---|
| InvoiceId | Waar | String | Een unieke id voor elke factuur. Vereist. |
| attributeSet | Onwaar | String | Kies 'volledig' voor alle kenmerken of basic voor een beperkte set. De standaardwaarde is 'vol'. (Zie hier de lijst met kenmerken ). Optioneel. |
Aanvraagheader
Aanvraagheaders voor de API. Zie de betrouwbaarheid en ondersteuning voor meer informatie.
API-reactie
HTTP/1.1 202 Geaccepteerd
Locatie: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
Wanneer u de API gebruikt, wordt doorgaans een HTTP 202-status geretourneerd. Zie Statussen voor andere mogelijke statussen op basis van uw aanvragen.
| Code | Beschrijving |
|---|---|
| 202 – Geaccepteerd | Uw aanvraag is geaccepteerd. Als u de status van uw aanvraag wilt controleren, voert u een query uit op de URL die is opgegeven in de locatieheader. |
Stap 2: Status van aanvraag controleren
Als u de status van een aanvraag wilt controleren, wacht u op een HTTP 200-antwoord met de status Geslaagd of Mislukt. Als de aanvraag is geslaagd, wordt de manifest-URL opgegeven in het kenmerk resourceLocation.
Bewerkingsstatus ophalen
Haalt de status van een aanvraag op.
API-aanvraag
Aanvraagparameters
| Naam | Opnemen in | Vereist | Type | Description |
|---|---|---|---|---|
| operationId | Aanvraag-URI | Waar | String | Een unieke id om de aanvraagstatus te controleren. Vereist. |
Aanvraagheader
Als u headers voor de API wilt aanvragen, raadpleegt u Betrouwbaarheid en ondersteuning.
Aanvraagtekst
N.v.t.
Antwoordstatus
Naast de standaard HTTP-statussen kan de API de volgende HTTP-status retourneren:
| Code | Beschrijving |
|---|---|
| 410 – Weg | De manifestkoppeling is alleen actief voor een specifieke duur die door de server is ingesteld. Nadat deze tijd is verstreken, moet u een nieuwe aanvraag indienen om toegang te krijgen tot het manifest. |
Nettolading van antwoord
De nettolading van het API-antwoord bevat de volgende kenmerken:
| Kenmerk | Vereist | Beschrijving |
|---|---|---|
| id | Waar | Een unieke id voor elk antwoord. Vereist. |
| status | Waar | Waarden en acties (vereist): notstarted: Wacht op de tijd die is opgegeven in de header 'Opnieuw proberen-na' en voer vervolgens nog een aanroep uit om de status te controleren. wordt uitgevoerd: Wacht op de tijd die is opgegeven in de header 'Opnieuw proberen-na' en voer vervolgens een andere aanroep uit om de status te controleren. geslaagd: de gegevens zijn gereed. Haal de nettolading van het manifest op met behulp van de URI die is opgegeven in resourceLocation. mislukt: de bewerking is permanent mislukt. Start het opnieuw op. |
| createdDateTime | Waar | Het tijdstip waarop de aanvraag is ingediend. Vereist. |
| lastActionDateTime | Waar | De tijd waarop de status voor het laatst is gewijzigd. Vereist. |
| resourceLocation | Onwaar | De URI voor de nettolading van het manifest. Optioneel. |
| error | Onwaar | Als de bewerking mislukt, worden foutdetails opgegeven in JSON-indeling. Optioneel. De volgende kenmerken zijn mogelijk opgenomen: bericht (vereist): een gedetailleerde beschrijving van de fout. code (vereist): het type fout dat is opgetreden. |
Resourcelocatieobject
| Kenmerk | Beschrijving |
|---|---|
| id | Een unieke id voor het manifest. |
| schemaVersion | Versie van het manifestschema. |
| dataFormat | Indeling van het factureringsgegevensbestand. compressedJSON: gegevensindeling waarbij elke blob een gecomprimeerd bestand is dat gegevens in JSON-regelsindeling bevat. Als u de gegevens uit elke blob wilt ophalen, moet u deze decomprimeren. |
| createdDateTime | Datum en tijd waarop het manifestbestand is gemaakt. |
| eTag | Versie van de manifestgegevens. Een wijziging in factureringsgegevens genereert een nieuwe waarde. |
| partnerTenantId | Id van de tenant van de partner. |
| rootDirectory | Hoofdmap van het bestand. |
| sasToken | SAS-token (Shared Access Signature) waarmee u alle bestanden in de map kunt lezen. |
| partitionType | Verdeelt gegevens in meerdere blobs op basis van het kenmerk partitionValue . Het systeem splitst partities die het ondersteunde aantal overschrijden. Standaard worden gegevens gepartitioneerd op basis van het aantal regelitems in het bestand. Stel geen vast aantal regelitems of bestandsgrootte in de code in, omdat deze waarden kunnen veranderen. |
| blobCount | Totaal aantal bestanden voor deze partnertenant-id. |
| blobs | Een JSON-matrix van 'blob'-objecten die de bestandsgegevens voor de tenant-id van de partner bevatten. |
| blobobject | Een object met de volgende details: |
| naam | Naam van de blob. |
| partitionValue | Partitie die het bestand bevat. De grote partitie wordt gesplitst in meerdere bestanden, waarbij elk bestand dezelfde 'partitionValue' bevat. |
API-aanvraag
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-reactie
Het antwoord raadt aan om 10 seconden te wachten voordat u het opnieuw probeert bij het verwerken van gegevens.
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-aanvraag
(10 seconden na de vorige aanvraag...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-reactie
De API retourneert de status Geslaagd en de URI voor 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"
}
\]
}
}
Stap 3: Regelitems voor dagelijkse afstemming van gebruiksgegevens downloaden uit Azure Blob Storage
Haal het SAS-token (Shared Access Signature) en de blob-opslaglocatie op uit de eigenschappen sasToken en rootDirectory. Gebruik de Azure Storage SDK/het hulpprogramma om het blobbestand te downloaden en uit te pakken. Deze heeft de JSONLines-indeling .
Tip
Bekijk onze voorbeeldcode om het Azure-blobbestand te downloaden en uit te pakken in uw lokale database.
Standaard-API-antwoordstatussen
Mogelijk ontvangt u deze HTTP-statussen van het API-antwoord:
| Code | Beschrijving |
|---|---|
| 400 – Ongeldige aanvraag | De aanvraag ontbreekt of bevat onjuiste gegevens. Controleer de hoofdtekst van het antwoord op foutdetails. |
| 401 - Niet geautoriseerd | De aanroeper wordt niet geverifieerd en u moet zich verifiëren met de partner-API-service voordat u de eerste aanroep doet. |
| 403 - Verboden | U hebt niet de benodigde autorisatie om de aanvraag te doen. |
| 404 – Niet gevonden | De aangevraagde resources zijn niet beschikbaar met de opgegeven invoerparameters. |
| 410 – Weg | Er is een time-out opgetreden voor de manifestkoppeling of verlopen. Dien een nieuwe aanvraag in. |
| 500 – Interne serverfout | De API of een van de bijbehorende afhankelijkheden kan momenteel niet voldoen aan de aanvraag. Probeer het later opnieuw. |
| 5000 – Geen gegevens beschikbaar | Het systeem heeft geen gegevens voor de opgegeven invoerparameters. |
Bèta- en GA-versies vergelijken
Zie de vergelijkingstabel om inzicht te hebben in de verschillen tussen de bètaversie en algemeen beschikbare (GA)-versies. Als u de bètaversie gebruikt, moet het eenvoudig zijn om over te schakelen naar de GA-versie.
| Belangrijke informatie | Bèta | Algemeen beschikbaar |
|---|---|---|
| API-hosteindpunt | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| HTTP-methode | POSTEN | POSTEN |
| Niet-gefactureerd dagelijks geclassificeerd gebruiks-API-eindpunt | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| Invoerparameters voor de niet-gefactureerde dagelijkse gebruiks-API | Als u parameters in de API-aanvraag wilt opgeven, neemt u deze op in de querytekenreeks van de aanvraag-URL. Als u bijvoorbeeld de parameters periode en currencyCode wilt opgeven, voegt u deze toe aan ?period=current¤cyCode=usd de aanvraag-URL. |
Als u invoer wilt opgeven, neemt u een JSON-object op in de aanvraagbody. Het JSON-object moet de volgende eigenschappen bevatten: * currencyCode: De valutacode voor de factuur. Bijvoorbeeld USD. * billingPeriod: De factureringsperiode voor de factuur. Bijvoorbeeld huidige. Hier volgt een voorbeeld van een JSON-object dat de eigenschappen currencyCode en billingPeriod bevat: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Gefactureerd dagelijks geclassificeerd api-eindpunt voor gebruik | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| Invoerparameters voor de gefactureerde dagelijkse gebruiks-API | Als u parameters in de API-aanvraag wilt opgeven, neemt u de invoiceId op in de aanvraag-URL. Daarnaast kunt u een optionele fragmentparameter in de querytekenreeks opnemen om de volledige set kenmerken op te halen. Als u bijvoorbeeld de volledige set kenmerken wilt ophalen, voegt u deze toe ?fragment=full aan de aanvraag-URL. |
Als u invoer wilt opgeven, neemt u een JSON-object op in de aanvraagbody. Het JSON-object moet de volgende eigenschappen bevatten: * invoiceId: de id van de factuur. Bijvoorbeeld G00012345. * attributeSet: de set kenmerken die moeten worden opgenomen in het antwoord. Bijvoorbeeld vol. Hier volgt een voorbeeld van een JSON-object dat de eigenschappen invoiceId en attributeSet bevat: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| Manifestresource | Gebruik een afzonderlijke METHODE GET /manifests/{id} om de manifestresource op te halen. | Gebruik de methode GET /operations/{Id}, die de gerelateerde manifestresource in resourceLocation retourneert, waardoor er geen afzonderlijke aanroep naar de METHODE GET /manifests/{id} nodig is. |
| Wijzigingen in het manifestschema | ||
| "id": niet beschikbaar | 'id': een unieke id voor de manifestresource. | |
| "versie": Beschikbaar | "version": hernoemd in "schemaversion.". | |
| "dataFormat": Beschikbaar | "dataFormat": Beschikbaar. | |
| "utcCretedDateTime": Beschikbaar | 'utcCretedDateTime': hernoemd in 'createdDateTime'. | |
| "eTag": Beschikbaar | "eTag": Beschikbaar. | |
| "partnerTenantId": Beschikbaar | "partnerTenantId": Beschikbaar | |
| "rootFolder": Beschikbaar | 'rootFolder': hernoemd in 'rootDirectory'. | |
| "rootFolderSAS": Beschikbaar | 'rootFolderSAS': hernoemd in 'sasToken'. Het biedt nu een token en bevat niet langer het pad naar de hoofdmap. Als u toegang wilt krijgen tot de map, gebruikt u in plaats daarvan de eigenschap rootDirectory. | |
| "partitionType": Beschikbaar | "partitionType": Beschikbaar. | |
| "blobCount": Beschikbaar | "blobCount": Beschikbaar. | |
| "sizeInBytes": Beschikbaar | "sizeInBytes": Niet beschikbaar. | |
| "blobs": Beschikbaar | "blobs": Beschikbaar. | |
| "blob-object": Beschikbaar | "blobobject": Beschikbaar. | |
| "name": Beschikbaar | "name": Beschikbaar. | |
| "partitionValue": Beschikbaar | "partitionValue": Beschikbaar. |
Kenmerken van het dagelijkse afstemmingslijnitem voor gebruik
Raadpleeg de volgende informatie om de kenmerken te vergelijken die worden geretourneerd door de dagelijkse afstemmings-API voor gebruiksafstemming voor de 'volledige' of 'basis'-kenmerksets.
| Kenmerk | Volledig | Basis |
|---|---|---|
| PartnerId | ja | ja |
| PartnerName | ja | ja |
| CustomerId | ja | ja |
| CustomerName | ja | Ja |
| CustomerDomainName | ja | nee |
| CustomerCountry | ja | nee |
| MpnId | ja | nee |
| Tier2MpnId | ja | nee |
| InvoiceNumber | ja | ja |
| Product-id | ja | ja |
| SkuId | ja | ja |
| AvailabilityId | ja | nee |
| SkuName | ja | ja |
| ProductName | ja | nee |
| PublisherName | ja | ja |
| PublisherId | ja | nee |
| SubscriptionDescription | ja | nee |
| SubscriptionId | ja | ja |
| ChargeStartDate | ja | ja |
| ChargeEndDate | ja | ja |
| UsageDate | ja | ja |
| MeterType | ja | nee |
| MeterCategory | ja | nee |
| MeterId | ja | nee |
| MeterSubCategory | ja | nee |
| MeterName | ja | nee |
| MeterRegion | ja | nee |
| Eenheid | ja | ja |
| ResourceLocation | ja | nee |
| ConsumedService | ja | nee |
| ResourceGroup | ja | nee |
| ResourceURI | ja | ja |
| ChargeType | ja | ja |
| UnitPrice | ja | ja |
| Hoeveelheid | ja | ja |
| UnitType | ja | nee |
| BillingPreTaxTotal | ja | ja |
| BillingCurrency | ja | ja |
| PricingPreTaxTotal | ja | ja |
| PricingCurrency | ja | ja |
| ServiceInfo1 | ja | nee |
| ServiceInfo2 | ja | nee |
| Tags | ja | nee |
| AdditionalInfo | ja | nee |
| EffectiveUnitPrice | ja | ja |
| PCToBCExchangeRate | ja | ja |
| EntitlementId | ja | ja |
| EntitlementDescription | ja | nee |
| PartnerEarnedCreditPercentage | ja | nee |
| CreditPercentage | ja | ja |
| CreditType | ja | ja |
| BenefitOrderID | ja | ja |
| BenefitID | ja | nee |
| BenefitType | ja | ja |
Belangrijk
Noteer deze wijzigingen wanneer u overstapt naar API v2 vanuit v1.
De naam van elk kenmerk begint in hoofdletters.
unitOfMeasure is nu Unit. De betekenis en waarde van het kenmerk zijn hetzelfde.
resellerMpnId is nu Tier2MpnId. De betekenis en waarde van het kenmerk zijn hetzelfde.
De naam en waarde van rateOfPartnerEarnedCredit zijn gewijzigd in PartnerEarnedCreditPercentage. De nieuwe naam en waarde van het kenmerk geven het percentage weer in plaats van de breuk. 0,15 is nu bijvoorbeeld 15.
rateOfCredit is nu CreditPercentage. De betekenis en waarde van het kenmerk zijn gewijzigd. 1.00 is nu bijvoorbeeld 100.
Voorbeeldcode
Zie voorbeelden van partnercentrum-API's voor meer informatie: factureringsgegevens ophalen.
Feedback
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.
Feedback verzenden en weergeven voor