Nieuwe commerce dagelijks beoordeeld gebruik v2 API (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 op te halen.
Notitie
Deze API wordt binnenkort afgeschaft. Om naadloze bewerkingen te garanderen, raden we u aan om te migreren naar de GA-versie. Hier volgen de details die u moet plannen:
Doel: Haal gefactureerde dagelijkse verbruiksregelitems op voor factureringsperioden van september 2022 vóór 21 januari 2025.
Actie: Gebruik deze API, maar migreer zo snel mogelijk naar v2 GA.
Doel: Haal gefactureerde dagelijkse verbruiksregelitems op voor factureringsperioden van september 2022 vanaf 21 januari 2025.
Actie: gebruik alleen API v2 GA.
Doel: niet-gefactureerde dagelijkse verbruiksregelitems ophalen voor de huidige en vorige factureringsperioden vóór 21 januari 2025.
Actie: Gebruik deze API, maar migreer zo snel mogelijk naar v2 GA.
Doel: haal niet-gefactureerde dagelijkse verbruiksregelitems op voor de huidige en vorige factureringsperioden van 21 januari 2025.
Actie: gebruik alleen API v2 GA.
Volg deze koppeling voor een naadloze overgang naar de nieuwe API's: Gefactureerde en niet-gefactureerde dagelijkse afstemmings-API voor gebruik 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. Om nauwkeurige gegevens te garanderen, kunt u maximaal 24 uur voor beschikbaarheid zorgen. Afhankelijk van uw locatie en wanneer de meters het gebruik rapporteren, kunnen er verdere vertragingen optreden.
We prioriteren eerst de 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
- Office
- Dynamics
- 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.
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 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 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 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 |
|---|---|---|---|---|
| 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 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 met de terminalstatus 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 | 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 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. |
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 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. |
| dataFormat | De bestandsindeling voor factureringsgegevens. Mogelijke waarden gecomprimeerdeJSONLines: elke blob is een gecomprimeerd bestand en gegevens in het bestand hebben de JSON-regelsindeling . 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 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'. 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. |
| 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": "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 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. 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 API-antwoord met de aanvraagparameter 'full' of 'basic' retourneert de volgende kenmerken:
| Attribuut | "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 |
| PCToBCExchangeRateDate | ja | nee |
| EntitlementId | ja | ja |
| EntitlementDescription | ja | nee |
| PartnerEarnedCreditPercentage | ja | nee |
| CreditPercentage | ja | ja |
| CreditType | ja | ja |
| BenefitOrderID | ja | ja |
| BenefitID | ja | nee |
| BenefitType | ja | ja |