Facturerings- en afstemmings-API v2 (bèta)
Van toepassing op: Partnercentrum | Partnercentrum beheerd door 21Vianet | Partnercentrum voor Microsoft Cloud voor de Amerikaanse overheid
Gebruik deze API's om dagelijks gefactureerde en niet-gefactureerde dagelijkse gebruiksgegevens asynchroon op te halen.
Notitie
Deze API voor gefactureerd dagelijks geclassificeerd gebruik werkt na 30 juni 2024 niet meer. Raadpleeg de volgende details om te bepalen welke versie moet worden gebruikt en wanneer.
- Gebruik deze API tot en met 30 juni 2024 , tenzij u bent overgeschakeld naar v2 GA, om dagelijks gefactureerde gebruiksitems te ontvangen voor facturen die zijn gemaakt voor factureringsperioden tussen september 2022 en juni 2024.
- Gebruik alleen API v2 GA na 30 juni 2024 om gefactureerde dagelijkse verbruiksregelitems op te halen voor facturen die zijn gemaakt voor factureringsperioden van september 2022.
Deze API voor niet-gefactureerd dagelijks geclassificeerd gebruik werkt na 30 juni 2024 niet meer. Raadpleeg de volgende details om te bepalen welke versie moet worden gebruikt en wanneer.
- Gebruik deze API tot 30 juni 2024 , tenzij u bent overgeschakeld naar v2 GA om niet-gefactureerde dagelijkse gebruiksregelitems voor huidige en vorige factureringsperioden op te halen.
- Gebruik alleen API v2 GA na 30 juni 2024 om niet-gefactureerde dagelijkse verbruiksregelitems voor huidige en vorige facturering op te halen.
Als u wilt beginnen met het voorbereiden van de migratie naar de nieuwe V2 GA-API's, raadpleegt u de volgende koppeling:
Gefactureerde en niet-gefactureerde dagelijkse afstemmings-API voor gebruik v2 (GA)
Notitie
U kunt uw dagelijkse niet-gefactureerde gebruiksgegevens ophalen via de API- of Partnercentrum-portal. Het kan tot 24 uur duren voordat de gegevens beschikbaar zijn. Er kunnen echter verdere vertragingen optreden, afhankelijk van uw locatie en wanneer de meters het gebruik rapporteren.
Soms ziet u mogelijk niet de meest recente niet-gefactureerde gebruiksgegevens totdat de gefactureerde gebruiksgegevens voor de vorige maand worden geleverd. Dit wordt gedaan om ervoor te zorgen dat gefactureerde gebruiksgegevens binnen de overeengekomen tijd worden geleverd. Zodra u de gefactureerde gebruiksgegevens ontvangt, moet u alle bijgewerkte niet-gefactureerde gebruiksgegevens kunnen ophalen vanaf het begin van de maand.
Belangrijk
De dagelijkse gebruiksgegevens bevatten niet de kosten voor deze producten:
- Azure-reservering
- Azure-besparingsplan
- Office
- Dynamics
- Microsoft Power Apps
- Eeuwigdurende software
- Softwareabonnement
- SaaS-product van derden
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 hebben valetsleutel en asynchrone aanvraagantwoordpatronen gebruikt 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 het volgende 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.
Eindpunt van bewerkingsstatus
Totdat u de status van het succes ontvangt, houdt u deze API regelmatig in de peiling. 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.
Manifesteindpunt
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 onderstaande diagram ziet u de stappen die nodig zijn om afstemmingsgegevens te downloaden.
Gebruikersactiereeks
Volg de onderstaande 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 gebruiksregelitems ophalen voor de huidige of 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 | Query | 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 | Query | 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. |
| currencyCode | Query | Waar | String | Valutacode voor partnerfacturering. |
Afgeschafte aanvraagparameters
Voor de nieuwere API-versie zijn de volgende URI-parameters niet vereist:
| Naam | Beschrijving |
|---|---|
| Provider | N.v.t. (Het retourneert alle azure-abonnementsgebruik en komt overeen met de 'eenmalige' van bestaande V1-API's.) |
| hasPartnerEarnedCredit | N.v.t. (retourneert alle gegevens, ongeacht PEC.) |
| Tekengrootte | N.v.t. |
| Verschuiving | N.v.t. |
| seekOperation | 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 is 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 |
|---|---|---|---|---|
| InvoiceId | Pad | Waar | String | Het factuurnummer van het Partnercentrum. |
| Fragment | Query | 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 |
|---|---|
| Provider | N.v.t. (Het retourneert alle azure-abonnementsgebruik en komt overeen met de 'eenmalige' van bestaande V1-API's.) |
| hasPartnerEarnedCredit | N.v.t. (retourneert alle gegevens, ongeacht PEC.) |
| Tekengrootte | N.v.t. |
| Verschuiving | N.v.t. |
| seekOperation | 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 is geaccepteerd. Controleer de aanvraagstatus door de header-URL van de bewerkingslocatie te peilen. |
Stap 2: Status van aanvraag controleren
Wacht op een HTTP 200 met de terminalstatus geslaagd of mislukt. De manifest-URL wordt '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 | Waar | 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 de onderstaande 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. |
Nettolading van antwoord
De nettolading van het API-antwoord retourneert de volgende kenmerken:
| Naam | Optioneel | Beschrijving |
|---|---|---|
| createdDateTime | false | Aanvraagtijd. |
| lastActionDateTime | false | Statuswijzigingstijd. |
| resourceLocation | true | De nettolading-URI van het manifest. |
| status | false | Mogelijke waarden en acties. |
| Weergegeven als | 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'. |
| actief | 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 | true | Foutdetails in json-indeling als de status van de bewerking is mislukt. |
| Naam | Optioneel | Beschrijving |
|---|---|---|
| bericht | false | 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. |
Aanvraagheader
Zie de [lijst met aanvraagheaders voor de API] in dit artikel.
Aanvraagtekst
N.v.t.
Antwoordstatus
Naast de standaard HTTP-status kan de API de onderstaande 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. |
| dataFormat | De bestandsindeling voor factureringsgegevens. Mogelijke waarden gecomprimeerdeJSONLines: elke blob is een gecomprimeerd bestand en gegevens in het bestand hebben de JSON-regelsindeling . Decomprim het bestand om toegang te krijgen tot de gegevens. |
| utcCreatedDateTime | Tijd voor het maken van manifestbestanden. |
| eTag | Manifestgegevensversie. Een wijziging in factureringsgegevens genereert een nieuwe eTag-waarde. |
| partnerTenantId | Tenant-id van partner. |
| rootFolder | De hoofdmap van het bestand. |
| rootFolderSAS | Het SAS-token voor toegang tot het bestand. |
| partitionType | 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'. Gegevens worden standaard gepartitioneerd door het aantal regelitems in het bestand. Stel geen vast aantal regelitems of bestandsgrootte in uw code in, omdat deze kunnen worden gewijzigd. |
| blobCount | Totaal aantal bestanden voor deze partnertenant-id. |
| sizeInBytes | 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. |
| sizeInBytes | Blobgrootte in bytes. |
| partitionValue | 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": "14f593ad-1edc-474d-aaa0-83abbf9638da",
"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 antwoord van de nettolading-API van het manifest. Gebruik de Azure Storage SDK/het hulpprogramma om het blobbestand te downloaden en uit te pakken. Deze heeft de indeling van JSON-regels .
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 de aanvraag. |
Standaard-API-antwoordstatussen
Hier volgen de HTTP-statussen van het API-antwoord:
| Naam | Beschrijving |
|---|---|
| 400 Ongeldige 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. Probeert u het later nog eens. |
| 404 Niet gevonden | Resource is niet beschikbaar met invoerparameters. |
| 410 Verdwenen | Er is een time-out opgetreden voor de manifestkoppeling of deze is verstreken. Dien een nieuwe aanvraag in. |
Kenmerken van gebruiksgegevens
Het gefactureerde of niet-gefactureerde API-antwoord met de aanvraagparameter 'full' of 'basic' retourneert de volgende kenmerken:
| Kenmerk | "vol" | "basic" |
|---|---|---|
| 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 |
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