Delen via


Nieuwe commerce-API voor gewaardeerd dagelijks gebruik v2 (bèta)

Van toepassing op: Partnercentrum | Partnercentrum beheerd door 21Vianet | Partnercentrum voor Microsoft Cloud voor de Amerikaanse overheid

Gebruik deze API's om new commerce gefactureerde en niet-gefactureerde dagelijkse gebruiksgegevens asynchroon op te halen.

Notitie

Deze API wordt niet meer ondersteund en biedt geen gebruiksgegevens na de factureringsperiode van maart 2025. Volg deze link om soepel over te stappen naar de nieuwe API's: facturatie en niet-gefactureerde dagelijkse gebruiksafstemming API v2 (GA). Bedankt voor uw aandacht en we kijken uit naar uw voortdurende succes met onze facturerings-API's.

Notitie

U hebt toegang tot uw niet-gefactureerde dagelijkse verbruiksregelitems via de API- of Partnercentrum-portal. Zorg ervoor dat de gegevens nauwkeurig zijn door tot 24 uur te wachten voor beschikbaarheid. Afhankelijk van uw locatie en wanneer de meters het gebruik rapporteren, kunnen er verdere vertragingen optreden.

We geven prioriteit aan de tijdige levering van gefactureerde dagelijkse gebruiksgegevens. Soms ziet u mogelijk niet de meest recente niet-gefactureerde dagelijkse gebruiksgegevens totdat de gefactureerde gebruiksgegevens van de vorige maand beschikbaar zijn. Zodra u de gefactureerde gebruiksgegevens ontvangt, kunt u alle bijgewerkte niet-gefactureerde gebruiksgegevens ophalen vanaf het begin van de maand.

Uw begrip en geduld worden gewaardeerd omdat we ernaar streven om de meest nauwkeurige en tijdige informatie te bieden.

Belangrijk

De dagelijkse gebruiksgegevens bevatten niet de kosten voor deze producten:

  • Azure-reservering
  • Azure-besparingsplan
  • Kantoor
  • Dynamica
  • Microsoft Power Apps
  • Eeuwigdurende software
  • Softwareabonnement
  • SaaS-product dat niet van Microsoft of marketplace is

API-overzicht

De asynchrone API is een nieuwe methode voor het snel openen van facturerings- en afstemmingsgegevens in beheerbare segmenten. Het elimineert de noodzaak om een open verbinding gedurende uren te onderhouden en miljoenen transacties iteratief te doorlopen.

We gebruiken valetsleutel en asynchrone aanvraagantwoordpatronen om onze facturerings- en afstemmings-API's te optimaliseren om de resultaten asynchroon te leveren. API-antwoorden bieden een token voor toegang tot de afstemmingsgegevens met alle kenmerken of een subset.

U kunt de gebruiksgegevens asynchroon downloaden met behulp van drie nieuwe stappen (API-eindpunten). Lees de volgende secties voor meer informatie:

Eindpunt van gebruiksregelitem

Gebruik deze API voor toegang tot gefactureerde of niet-gefactureerde verbruiksitems. Het retourneert een HTTP-status van 202 en een locatieheader met de URL, die u regelmatig moet peilen totdat u een successtatus met een manifest-URL ontvangt.

Operatiestatus-eindpunt

Totdat u de successtatus ontvangt, controleert u deze API regelmatig. Als de aangevraagde gegevens niet beschikbaar zijn, bevat het API-antwoord een header Opnieuw proberen na die aangeeft hoe lang u moet wachten voordat een andere aanvraag wordt verzonden.

Manifest eindpunt

Dit eindpunt biedt een opslagmap waaruit werkelijke factureringsgegevens kunnen worden gedownload. Het antwoord splitst of partitioneert de bestanden om doorvoer en I/O parallellisme te optimaliseren.

Sequentiediagram

In het diagram ziet u de stappen die nodig zijn om afstemmingsgegevens te downloaden.

Diagram met de stappen die nodig zijn om afstemmingsgegevens te downloaden.

Gebruikersactiereeks

Volg deze stappen om afstemmingsgegevens op te halen.

Stap 1: Aanvraag indienen

Dien een POST-aanvraag in bij het API-eindpunt.

Niet-gefactureerde gebruiksregelitems ophalen

Niet-gefactureerde gebruiksartikelen ophalen voor deze of de vorige kalendermaand.

API-aanvraag

POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}

Aanvraagparameters

Naam In Vereist Type Beschrijving
fragment Zoekopdracht Onwaar String Kies 'volledig' voor een volledig antwoord of basic voor een subset van kenmerken. De standaardwaarde is 'vol'. Zie de lijst met kenmerken in dit artikel.
periode Aanvraag Waar String Gebruik 'huidige' of 'laatste' om het gebruik voor de huidige of laatste kalendermaand op te halen. De waarde 'laatste' is hetzelfde als 'vorige' in bestaande V1-API's.
valutacode Vraag Waar String Valutacode voor partnerfacturering.

Verouderde aanvraagparameters

Voor de nieuwere API-versie zijn de volgende URI-parameters niet vereist:

Naam Beschrijving
Aanbieder N.v.t. (Het retourneert alle Azure-planverbruik en komt overeen met de 'eenmalige' van bestaande V1-API's.)
heeftPartnerKredietVerdiend N.v.t. (retourneert alle gegevens, ongeacht PEC.)
Grootte N.v.t.
Verschuiving N.v.t.
zoekbewerking N.v.t.

Aanvraagheader

Zie de lijst met aanvraagheaders voor de API in dit artikel.

Aanvraagtekst

N.v.t.

API-reactie

HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6

API retourneert HTTP-status 202. Api kan op basis van aanvraag andere standaardstatussen retourneren.

Naam Beschrijving
202 Geaccepteerd De aanvraag wordt geaccepteerd. Voer een query uit op de header-URL van de bewerkingslocatie voor de aanvraagstatus.

Gefactureerde gebruiksregelitems ophalen

Gefactureerde gebruiksregelitems ophalen voor de gesloten factureringsperiode.

API-aanvraag

POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}

Aanvraagparameters

Naam In Vereist Type Beschrijving
factuurId Pad Waar String Het factuurnummer van het Partnercentrum.
Fragment Vraag Onwaar String Kies 'volledig' voor een volledig antwoord of basic voor een subset van kenmerken. De standaardwaarde is 'vol'. Zie de lijst met kenmerken in dit artikel.

Afgeschafte aanvraagparameters

Voor de nieuwere API-versie zijn de volgende URI-parameters niet vereist:

Naam Beschrijving
Dienstverlener N.v.t. (Het retourneert alle Azure-abonnementsgebruik en komt overeen met de 'eenmalige' van bestaande V1-API's.)
heeftPartnerCreditVerdiend N.v.t. (retourneert alle gegevens, ongeacht PEC.)
Grootte N.v.t.
Verschuiving N.v.t.
zoekoperatie N.v.t.

Aanvraagheader

Zie de lijst met aanvraagheaders voor de API in dit artikel.

Aanvraagtekst

N.v.t.

API-reactie

HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640

API retourneert 'HTTP 202 Geaccepteerd'. Op basis van de aanvraag-API kan een andere standaardstatus worden geretourneerd.

Naam Beschrijving
202 Geaccepteerd De aanvraag wordt geaccepteerd. Controleer de aanvraagstatus door de header-URL van de bewerkingslocatie te peilen.

Stap 2: Status van aanvraag controleren

Wacht op een HTTP 200-status met als eindstatus geslaagd of mislukt. De manifest-URL is de "resourceLocation" in de status "geslaagd".

Bewerkingsstatus ophalen

Hiermee wordt de status van een aanvraag voor afstemmingsgegevens opgehaald.

API-aanvraag

GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640

Aanvraagparameters

Naam In Vereist Type Beschrijving
operationId Pad True String De bewerkings-id.

Aanvraagheader

Zie de lijst met aanvraagheaders voor de API in dit artikel.

Aanvraagtekst

N.v.t.

Antwoordstatus

Naast de standaard HTTP-status in dit artikel kan de API deze HTTP-status retourneren:

Naam Beschrijving
410 Verdwenen Elke bewerkingskoppeling is actief voor een opgegeven hoeveelheid servergestuurde tijd. Nadat de tijd is verstreken, moet de client een nieuwe aanvraag indienen.

Antwoordlading

De nettolading van het API-antwoord retourneert de volgende kenmerken:

Naam Optioneel Beschrijving
aanmaakdatumtijd onwaar Aanvraagtijd.
laatsteActieDatumTijd onwaar Statuswijzigingstijd.
resourceLocation waar De payload-URI van het manifest.
status onwaar Mogelijke waarden en acties.
Waarde Clientactie
niet gestart Voer nog een aanroep uit om de status te controleren nadat u hebt gewacht op de tijd die is opgegeven in de header 'Opnieuw proberen na'.
rennen Voer nog een aanroep uit om de status te controleren nadat u hebt gewacht op de tijd die is opgegeven in de header 'Opnieuw proberen na'.
Geslaagd De laatste bewerkingsstatus, die aangeeft dat gegevens gereed zijn. Haal de nettolading van het manifest op met behulp van de URI die is opgegeven in resourceLocation.
mislukt Terminalstatus, wat een permanente fout aangeeft. Start de bewerking opnieuw op.

Voor foutkenmerk:

Naam Optioneel Beschrijving
error waar Foutdetails worden verstrekt in json-indeling als de status van de bewerking mislukt is.
Naam Optioneel Beschrijving
bericht onwaar Beschrijft de fout in detail
code false Geeft het type fout aan dat is opgetreden

API-aanvraag

GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640

API-reactie

Het antwoord stelt voor dat u 10 seconden moet wachten voordat u het opnieuw probeert bij het verwerken van gegevens.

HTTP/1.1 200 OK  
Retry-After: 10  
{  
"createdDateTime": "2022-06-1T10-01-03.4Z",  
"lastActionDateTime":" 2022-06-1T10-01-05Z",  
"status": "running"  
}

API-aanvraag

(10 seconden na de eerdere aanvraag)

GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640

API-reactie

De API retourneert de status Geslaagd en de URI resourceLocation.

HTTP/1.1 200 OK  
Content-Type: application/json  
{  
"createdDateTime": "2022-06-1T10-01-03.4Z",  
"lastActionDateTime": "2022-06-1T10-01-13Z",  
"status": "succeeded",  
"resourceLocation": "https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/e03e1882-ff59-4c09-882f-74e60b4d7743"  
}

Stap 3: Nettolading van manifest ophalen

De aanroeper doet een GET-aanvraag naar de manifest-URL voor meer informatie over waar de afstemmingsgegevens worden opgeslagen in Azure-blobs.

Het manifest verkrijgen

Haalt het manifest op met informatie over de Azure-opslaglocatie van de afstemmingsgegevens.

API-aanvraag

GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}

Aanvraagparameters

Naam In Vereist Type Beschrijving
manifestId Pad Waar String De manifest-ID.

Verzoekkoptekst

Zie de [lijst met aanvraagheaders voor de API] in dit artikel.

Aanvraagtekst

N.v.t.

Antwoordstatus

Naast de standaard HTTP-status kan de API deze HTTP-status retourneren:

Naam Beschrijving
410 Verdwenen Elke manifestkoppeling is actief voor een opgegeven hoeveelheid servergestuurde tijd. Nadat de tijd is verstreken, moet de client een nieuwe aanvraag indienen.

Nettolading van antwoord

Het API-antwoord retourneert de volgende kenmerken:

Naam Beschrijving
Versie De manifestschemaversie.
gegevensformaat De bestandsindeling voor factureringsgegevens. Mogelijke waarden: gecomprimeerdeJSONLines: elke blob is een gecomprimeerd bestand en de gegevens in het bestand zijn in JSON-lijnen formaat. Als u toegang wilt krijgen tot de gegevens, moet u het bestand decomprimeren.
utcCreatedDateTime Tijd voor het maken van manifestbestanden.
eTag Manifestgegevensversie. Een wijziging in factureringsgegevens genereert een nieuwe eTag-waarde.
partnerTenantId Partnertenant-id.
rootFolder De rootmap van het bestand.
rootFolderSAS Het SAS-token voor toegang tot het bestand.
partitieType Met deze eigenschap worden de gegevens verdeeld. Als een bepaalde partitie meer dan het ondersteunde getal heeft, worden de gegevens gesplitst in meerdere bestanden die overeenkomen met de 'partitionValue'. Standaard partitioneert het systeem gegevens op basis van het aantal regelitems in het bestand. Stel geen vast aantal regelitems of bestandsgrootte in uw code in, omdat het partitioneringsprincipe kan veranderen.
aantal blobs Totaal aantal bestanden voor deze partnertenant-id.
grootteInBytes Totaal aantal bytes in alle bestanden.
blobs Een JSON-matrix van 'blob'-objecten met de details van alle bestanden voor de tenant-id van de partner.
Blob-object
Naam De naam van de blob.
grootteInBytes Blobgrootte in bytes.
partitiewaarde De partitie die het bestand bevat. Een grote partitie wordt gesplitst in meerdere bestanden, elk met dezelfde 'partitionValue'.

Voorbeeld van nettolading van manifest

{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"rootFolder": "https://{billing.blob.core.windows.net}/{folder_path}",
"rootFolderSAS": "\*\*\*",
"partitionType": "ItemCount",
"blobCount": 3,
"sizeInBytes": 2000,
"blobs": [
  {
  "name": "{blobName1.json.gz}",
  "sizeinBytes": 500,
  "partitionValue": "1"
  },
  {
  "name": "{blobName2.json.gz}",
  "sizeinBytes": 1000,
  "partitionValue": "2"
  },
  {
  "name": "{blobName3.json.gz}",
  "sizeinBytes": 500,
  "partitionValue": "3"
  }
  ]
}

Stap 4: Gebruiksafstemmingsgegevens downloaden van opslaglocatie

Haal het SAS-token en de blobopslaglocatie op uit de eigenschappen "rootFolderSAS" en "rootFolder" van het manifest-payload-API-antwoord. Gebruik de Azure Storage SDK/het hulpprogramma om het blobbestand te downloaden en uit te pakken. Het is in het JSON-lijnenformaat.

Standard API-aanvraagheaders

Alle API's accepteren de volgende headers:

Naam Vereist Type Beschrijving
Autorisatie Waar String Autorisatie Bearer-token.
ms-correlationid Onwaar String Een interne aanvraagtracker. Elke aanvraag genereert een nieuwe tracker (GUID).
ms-cv Onwaar String Een interne aanvraagtracker.
ms-requestid Onwaar String De idempotentie-ID van het verzoek.

Standaard-API-antwoordstatussen

Hier volgen de HTTP-statussen van het API-antwoord:

Naam Beschrijving
400 Foutieve aanvraag Er ontbreken of onjuiste gegevens. De foutdetails worden opgenomen in de hoofdtekst van het antwoord.
401 Onbevoegd De aanroeper wordt niet geverifieerd en moet worden geverifieerd met de partner-API-service voordat de eerste aanroep wordt uitgevoerd.
403 Verboden De beller is niet gemachtigd om de aanvraag te doen.
500 Interne serverfout De API of een van de bijbehorende afhankelijkheden kan niet voldoen aan de aanvraag. Probeer het later opnieuw.
404 Niet gevonden Resource is niet beschikbaar met invoerparameters.
410 Verdwenen Er is een time-out opgetreden voor de manifestkoppeling of is verstreken. Dien een nieuwe aanvraag in.

Kenmerken van gebruiksgegevens

Het gefactureerde of niet-gefactureerde gebruik-API-antwoord met de aanvraagparameter 'full' of 'basic' retourneert de volgende attributen:

Attribuut "vol" "basis"
PartnerId ja ja
PartnerName ja ja
KlantId ja ja
Klantnaam ja Ja
KlantenDomeinNaam ja nee
Klantland ja nee
MpnId ja nee
Tier2MpnId ja nee
Factuurnummer ja ja
ProductId ja ja
SkuId ja ja
BeschikbaarheidsId ja nee
SkuName ja ja
ProductName ja nee
PublisherName ja ja
UitgeverId ja nee
Abonnementsbeschrijving ja nee
AbonnementId ja ja
StartdatumLading ja ja
ChargeEndDate ja ja
Gebruiksdatum ja ja
MeterType ja nee
MeterCategory ja nee
MeterId ja nee
MeterSubCategorie ja nee
MeterNaam ja nee
MeterRegion ja nee
Eenheid ja ja
ResourceLocation ja nee
ConsumedService ja nee
ResourceGroup ja nee
Resource-URI ja ja
LaadType ja ja
Eenheidsprijs ja ja
Hoeveelheid ja ja
Eenheidstype ja nee
FactureringVoorBelastingTotaal ja ja
Factureringsvaluta ja ja
PrijsVoorbelastingTotaal ja ja
Prijsvaluta ja ja
ServiceInfo1 ja nee
ServiceInfo2 ja nee
Tags ja nee
AanvullendeInformatie ja nee
EffectieveStuksprijs ja ja
PCToBCExchangeRate ja ja
PCToBCExchangeRateDate ja nee
ToekenningsId ja ja
Rechtomschrijving ja nee
Partner Verdiende Krediet Percentage ja nee
Kredietpercentage ja ja
Krediettype ja ja
VoordeelBestellingID ja ja
BenefitID ja nee
Soort Voordeel ja ja