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.
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 |