Neue Commerce täglich bewertete Nutzung v2-API (Beta)
Gilt für: Partner Center | Partner Center-Betrieb durch 21Vianet | Partner Center für Microsoft Cloud for US Government
Verwenden Sie diese APIs, um asynchrone, abgerechnete und nicht berechnete E-Commerce-Nutzungsdaten zu erhalten.
Hinweis
Diese API wird in Kürze nicht mehr unterstützt. Um einen nahtlosen Betrieb sicherzustellen, empfehlen wir die Migration zur GA-Version. Hier sind die Details, die Sie vorausplanen müssen:
Ziel: Abrufen der täglich bewerteten Nutzungspositionen für Abrechnungszeiträume vom September 2022 vor dem 21. Januar 2025.
Aktion: Verwenden Sie diese API, migrieren Sie jedoch so bald wie möglich zu v2 GA.
Ziel: Abrufen der ab dem 21. Januar 2025 ab dem 21. Januar 2025 berechneten Täglich bewerteten Nutzungspositionen für Abrechnungszeiträume.
Aktion: Verwenden Sie nur API v2 GA.
Ziel: Abrufen nicht berechneter täglich bewerteter Nutzungspositionen für die aktuellen und vorherigen Abrechnungszeiträume vor dem 21. Januar 2025.
Aktion: Verwenden Sie diese API, migrieren Sie jedoch so bald wie möglich zu v2 GA.
Ziel: Abrufen nicht berechneter täglich bewerteter Nutzungspositionen für die aktuellen und vorherigen Abrechnungszeiträume ab dem 21. Januar 2025.
Aktion: Verwenden Sie nur API v2 GA.
Für einen nahtlosen Übergang zu den neuen APIs folgen Sie diesem Link: Abgerechnete und nicht abgerechnete tägliche Nutzungsabstimmungs-API v2 (GA).
Vielen Dank für Ihre Aufmerksamkeit, und wir freuen uns auf Ihren fortgesetzten Erfolg mit unseren Abrechnungs-APIs.
Hinweis
Sie können über das API- oder Partner Center-Portal auf Ihre nicht abgerechneten täglich bewerteten Nutzungspositionen zugreifen. Um genaue Daten zu gewährleisten, können Sie bis zu 24 Stunden für die Verfügbarkeit zulassen. Je nach Standort und dem Zeitpunkt, an dem die Zähler die Nutzung melden, kann es weitere Verzögerungen geben.
Wir priorisieren zuerst die Rechtzeitige Lieferung von in Rechnung gestellten täglich bewerteten Nutzungsdaten. Gelegentlich werden die neuesten nicht abgerechneten täglich bewerteten Nutzungsdaten möglicherweise erst angezeigt, wenn die in Rechnung gestellten Nutzungsdaten des vorherigen Monats verfügbar sind. Nachdem Sie die in Rechnung gestellten Nutzungsdaten erhalten haben, können Sie alle aktualisierten nicht berechneten Nutzungsdaten ab Dem Anfang des Monats abrufen.
Ihr Verständnis und Ihre Geduld werden geschätzt, da wir uns bemühen, möglichst genaue und zeitnahe Informationen bereitzustellen.
Wichtig
Die täglich bewerteten Nutzungsdaten enthalten keine Gebühren für diese Produkte:
- Azure-Reservierung
- Azure-Sparplan
- Office
- Dynamics
- Microsoft Power Apps
- Unbefristete Software
- Softwareabonnement
- SaaS-Produkt ohne Microsoft oder Marketplace
API-Übersicht
Die asynchrone API ist eine neuartige Methode für den schnellen Zugriff auf Abrechnungs- und Abstimmungsdaten in verwaltbaren Blöcken. Es beseitigt die Notwendigkeit, eine offene Verbindung für Stunden aufrechtzuerhalten und Millionen von Transaktionen iterativ zu durchlaufen.
Wir verwenden Valet-Schlüssel und asynchrone Anforderungsantwortmuster , um unsere Rechnungs- und Abstimmungs-APIs zu optimieren, um die Ergebnisse asynchron zu liefern. API-Antworten bieten ein Token für den Zugriff auf die Abstimmungsdaten mit allen Attributen oder einer Teilmenge.
Sie können die Nutzungsdaten asynchron mit drei neuen Schritten (API-Endpunkte) herunterladen. Weitere Informationen finden Sie in den folgenden Abschnitten:
Endpunkt für Verwendungszeilenelemente
Verwenden Sie diese API, um auf rechnungsierte oder nicht abgerechnete Verbrauchspositionen zuzugreifen. Er gibt einen 202 HTTP-Status und einen Speicherortheader mit der URL zurück, die Sie in regelmäßigen Abständen abfragen müssen, bis Sie einen Erfolgsstatus mit einer Manifest-URL erhalten.
Vorgangsstatusendpunkt
Bis Sie den Erfolgsstatus erhalten, müssen Sie diese API in regelmäßigen Abständen abrufen. Wenn die angeforderten Daten nicht verfügbar sind, enthält die API-Antwort einen Retry-After-Header , der angibt, wie lange Sie warten sollten, bevor Sie eine andere Anforderung senden.
Manifestendpunkt
Dieser Endpunkt stellt einen Speicherordner bereit, aus dem tatsächliche Abrechnungsdaten heruntergeladen werden können. Die Antwort teilt oder partitioniert die Dateien, um den Durchsatz und die E/A-Parallelität zu optimieren.
Sequenzdiagramm
Das Diagramm zeigt die Schritte zum Herunterladen von Abstimmungsdaten.
Benutzeraktionssequenz
Führen Sie die folgenden Schritte aus, um Abstimmungsdaten abzurufen.
Schritt 1: Senden einer Anforderung
Senden Sie eine POST-Anforderung an den API-Endpunkt.
Abrufen nicht abgerechneter Nutzungspositionen
Erhalten Sie nicht berechnete Nutzungspositionen für den aktuellen oder letzten Kalendermonat.
API-Anforderung
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
Anforderungsparameter
| Name | In | Erforderlich | Typ | Beschreibung |
|---|---|---|---|---|
| fragment | Abfrage | False | String | Wählen Sie "vollständig" für eine vollständige Antwort oder "einfach" für eine Teilmenge von Attributen aus. Der Standardwert ist "vollständig". Eine Liste der Attribute finden Sie in diesem Artikel. |
| period | Abfrage | True | String | Verwenden Sie "current" oder "last", um die Verwendung für den aktuellen oder letzten Kalendermonat zu erhalten. Der Wert "last" ist identisch mit "previous" in vorhandenen V1-APIs. |
| currencyCode | Abfrage | True | String | Partnerabrechnungswährungscode. |
Veraltete Anforderungsparameter
Für die neuere API-Version sind die folgenden URI-Parameter nicht erforderlich:
| Name | Beschreibung |
|---|---|
| Anbieter | Nicht zutreffend. (Es gibt alle Azure-Plannutzung zurück und entspricht dem "einmaligen" vorhandener V1-APIs.) |
| hasPartnerEarnedCredit | Nicht zutreffend. (gibt alle Daten unabhängig von PEC zurück.) |
| Größe | Nicht zutreffend. |
| Abweichung | Nicht zutreffend. |
| seekOperation | Nicht zutreffend. |
Anforderungsheader
Eine Liste der Anforderungsheader für die API finden Sie in diesem Artikel.
Anforderungstext
Nicht zutreffend.
API-Antwort
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
DIE API gibt DEN HTTP-Status 202 zurück. Basierend auf der Anforderung kann die API einen anderen Standardstatus zurückgeben.
| Name | Beschreibung |
|---|---|
| 202 – Akzeptiert | Die Anforderung wird akzeptiert. Fragen Sie die URL des Vorgangsspeicherortheaders nach dem Anforderungsstatus ab. |
Abrufen von Abrechnungspositionen
Rufen Sie bewertete Nutzungspositionen für den abgeschlossenen Abrechnungszeitraum ab.
API-Anforderung
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
Anforderungsparameter
| Name | In | Erforderlich | Typ | Beschreibung |
|---|---|---|---|---|
| invoiceId | Pfad | True | String | Die Partner Center-Rechnungsnummer. |
| Fragment | Abfrage | False | String | Wählen Sie "vollständig" für eine vollständige Antwort oder "einfach" für eine Teilmenge von Attributen aus. Der Standardwert ist "vollständig". Eine Liste der Attribute finden Sie in diesem Artikel. |
Veraltete Anforderungsparameter
Für die neuere API-Version sind die folgenden URI-Parameter nicht erforderlich:
| Name | Beschreibung |
|---|---|
| Anbieter | Nicht zutreffend. (Es gibt alle Azure-Plannutzung zurück und entspricht dem "einmaligen" vorhandener V1-APIs.) |
| hasPartnerEarnedCredit | Nicht zutreffend. (gibt alle Daten unabhängig von PEC zurück.) |
| Größe | Nicht zutreffend. |
| Abweichung | Nicht zutreffend. |
| seekOperation | Nicht zutreffend. |
Anforderungsheader
Eine Liste der Anforderungsheader für die API finden Sie in diesem Artikel.
Anforderungstext
Nicht zutreffend.
API-Antwort
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
DIE API gibt "HTTP 202 Accepted" zurück. Basierend auf der Anforderungs-API kann ein anderer Standardstatus zurückgegeben werden.
| Name | Beschreibung |
|---|---|
| 202 – Akzeptiert | Die Anforderung wird akzeptiert. Überprüfen Sie den Anforderungsstatus, indem Sie die URL des Vorgangsspeicherortheaders abrufen. |
Schritt 2: Überprüfen des Anforderungsstatus
Warten Sie, bis ein HTTP 200 mit einem Terminalstatus erfolgreich war oder fehlgeschlagen ist. Die Manifest-URL ist die "resourceLocation" im Erfolgsstatus.
Abrufen des Vorgangsstatus
Ruft den Status einer Abstimmungsdatenanforderung ab.
API-Anforderung
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
Anforderungsparameter
| Name | In | Erforderlich | Typ | Beschreibung |
|---|---|---|---|---|
| operationId | Pfad | True | String | Vorgangs-ID. |
Anforderungsheader
Eine Liste der Anforderungsheader für die API finden Sie in diesem Artikel.
Anforderungstext
Nicht zutreffend.
Antwortstatus
Zusätzlich zum standardmäßigen HTTP-Status in diesem Artikel kann die API diesen HTTP-Status zurückgeben:
| Name | Beschreibung |
|---|---|
| 410 Nicht mehr vorhanden | Jede Vorgangsverknüpfung ist für eine bestimmte Serverzeit aktiv. Nach Ablauf der Zeit muss der Client eine neue Anforderung senden. |
Antwortnutzlast
Die API-Antwortnutzlast gibt die folgenden Attribute zurück:
| Name | Optional | Beschreibung |
|---|---|---|
| createdDateTime | false | Anforderungszeit. |
| lastActionDateTime | false | Statusänderungszeit. |
| resourceLocation | true | Der Manifestnutzlast-URI. |
| status | false | Mögliche Werte und Aktionen. |
| Wert | Clientaktion |
|---|---|
| nicht gestartet | Führen Sie einen weiteren Aufruf aus, um den Status zu überprüfen, nachdem Sie auf die im Header "Retry-After" angegebene Zeit gewartet haben. |
| „Wird ausgeführt“ | Führen Sie einen weiteren Aufruf aus, um den Status zu überprüfen, nachdem Sie auf die im Header "Retry-After" angegebene Zeit gewartet haben. |
| succeeded | Der endgültige Betriebszustand, der angibt, dass Daten bereit sind. Rufen Sie die Manifestnutzlast mithilfe des in resourceLocation angegebenen URI ab. |
| „Fehlgeschlagen“ | Terminalstatus, der einen dauerhaften Fehler angibt. Starten Sie den Vorgang neu. |
Für Fehlerattribute:
| Name | Optional | Beschreibung |
|---|---|---|
| error | true | Fehlerdetails im JSON-Format, wenn der Status des Vorgangs fehlgeschlagen ist. |
| Name | Optional | Beschreibung |
|---|---|---|
| message | false | Beschreibt den Fehler im Detail. |
| code | false | Gibt die Art des aufgetretenen Fehlers an. |
API-Anforderung
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
API-Antwort
Die Antwort schlägt vor, 10 Sekunden zu warten, bevor sie beim Verarbeiten von Daten erneut versucht wird.
HTTP/1.1 200 OK
Retry-After: 10
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime":" 2022-06-1T10-01-05Z",
"status": "running"
}
API-Anforderung
(10 Sekunden nach der früheren Anforderung)
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
API-Antwort
Die API gibt den Status "erfolgreich" und den URI "resourceLocation" zurück.
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"
}
Schritt 3: Abrufen der Manifestnutzlast
Der Aufrufer sendet eine GET-Anforderung an die Manifest-URL, um mehr darüber zu erfahren, wo die Abstimmungsdaten in Azure-Blobs gespeichert sind.
Abrufen des Manifests
Ruft das Manifest mit Informationen zum Azure-Speicherort der Abstimmungsdaten ab.
API-Anforderung
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Anforderungsparameter
| Name | In | Erforderlich | Typ | Beschreibung |
|---|---|---|---|---|
| manifestId | Pfad | True | String | Die Manifest-ID. |
Anforderungsheader
Siehe die [Liste der Anforderungsheader für die API] in diesem Artikel.
Anforderungstext
Nicht zutreffend.
Antwortstatus
Zusätzlich zum standardmäßigen HTTP-Status kann die API diesen HTTP-Status zurückgeben:
| Name | Beschreibung |
|---|---|
| 410 Nicht mehr vorhanden | Jede Manifestverknüpfung ist für eine bestimmte Menge servergesteuerter Zeit aktiv. Nach Ablauf der Zeit muss der Client eine neue Anforderung senden. |
Antwortnutzlast
Die API-Antwort gibt die folgenden Attribute zurück:
| Name | Beschreibung |
|---|---|
| Version | Die Manifestschemaversion. |
| dataFormat | Das Dateiformat für Abrechnungsdaten. Mögliche Werte komprimiertJSONLines: Jedes Blob ist eine komprimierte Datei und Daten in der Datei im JSON-Zeilenformat . Um auf die Daten zuzugreifen, dekomprimieren Sie die Datei. |
| utcCreatedDateTime | Erstellungszeit der Manifestdatei. |
| eTag | Manifestdatenversion. Eine Änderung der Abrechnungsinformationen generiert einen neuen eTag-Wert. |
| partnerTenantId | Partnermandanten-ID. |
| rootFolder | Das Stammverzeichnis der Datei. |
| rootFolderSAS | Das SAS-Token für den Zugriff auf die Datei. |
| partitionType | Diese Eigenschaft dividiert die Daten. Wenn eine angegebene Partition mehr als die unterstützte Zahl aufweist, werden die Daten in mehrere Dateien aufgeteilt, die dem "partitionValue" entsprechen. Standardmäßig partitioniert das System Daten basierend auf der Anzahl der Zeilenelemente in der Datei. Legen Sie im Code keine feste Anzahl von Zeilenelementen oder Dateigrößen fest, da sich das Partitionierungsprinzip ändern kann. |
| blobCount | Gesamtanzahl der Dateien für diese Partnermandanten-ID. |
| sizeInBytes | Gesamtanzahl der Bytes in allen Dateien. |
| blobs | Ein JSON-Array von "blob"-Objekten mit den Details aller Dateien für die Partnermandanten-ID. |
| Blob-Objekt | |
| Name | Blobs Name. |
| sizeInBytes | BLOB-Größe in Byte. |
| partitionValue | Die Partition, die die Datei enthält. Eine große Partition wird in mehrere Dateien aufgeteilt, jeweils mit demselben "partitionValue". |
Beispielmanifestnutzlast
{
"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"
}
]
}
Schritt 4: Herunterladen von Nutzungsabstimmungsdaten vom Speicherort
Rufen Sie das SAS-Token und den Blobspeicherort aus den Eigenschaften "rootFolderSAS" und "rootFolder" der Manifestnutzlast-API-Antwort ab. Verwenden Sie das Azure Storage SDK/Tool, um die BLOB-Datei herunterzuladen und zu entpacken. Es befindet sich im JSON-Zeilenformat .
Standard-API-Anforderungsheader
Alle APIs akzeptieren die folgenden Header:
| Name | Erforderlich | Typ | Beschreibung |
|---|---|---|---|
| Autorisierung | True | String | Autorisierungs-Bearertoken. |
| ms-correlationid | False | String | Eine interne Anforderungsverfolgung. Jede Anforderung generiert einen neuen Tracker (GUID). |
| ms-cv | False | String | Eine interne Anforderungsverfolgung. |
| ms-requestid | False | String | Die Anforderungs-Idempotency-ID. |
Standard-API-Antwortstatus
Im Folgenden sind die HTTP-Status aus der API-Antwort aufgeführt:
| Name | Beschreibung |
|---|---|
| 400 – Ungültige Anforderung | Es fehlen oder falsche Daten. Die Fehlerdetails sind im Antworttext enthalten. |
| 401 – Nicht autorisiert | Der Aufrufer ist nicht authentifiziert und muss sich vor dem ersten Aufruf beim Partner-API-Dienst authentifizieren. |
| 403 Verboten | Der Anrufer ist nicht berechtigt, die Anforderung zu stellen. |
| 500: Interner Serverfehler | Die API oder eine ihrer Abhängigkeiten kann die Anforderung nicht erfüllen. Versuchen Sie es später noch einmal. |
| 404 Nicht gefunden | Ressource mit Eingabeparametern nicht verfügbar. |
| 410 Nicht mehr vorhanden | Timeout oder Verstrichen des Manifestlinks. Senden Sie eine neue Anforderung. |
Verwendungsdatenattribute
Die Antwort der abgerechneten oder nicht abgerechneten Verwendungs-API mit dem Anforderungsparameter "full" oder "basic" gibt die folgenden Attribute zurück:
| Attribut | "vollständig" | "einfach" |
|---|---|---|
| PartnerId | ja | ja |
| PartnerName | ja | ja |
| CustomerId | ja | ja |
| CustomerName | ja | Ja |
| CustomerDomainName | ja | Nein |
| CustomerCountry | ja | Nein |
| MpnId | ja | Nein |
| Tier2MpnId | ja | Nein |
| InvoiceNumber | ja | ja |
| ProductId | ja | ja |
| SkuId | ja | ja |
| AvailabilityId | ja | Nein |
| SkuName | ja | ja |
| ProductName | ja | Nein |
| PublisherName | ja | ja |
| PublisherId | ja | Nein |
| SubscriptionDescription | ja | Nein |
| SubscriptionId | ja | ja |
| ChargeStartDate | ja | ja |
| ChargeEndDate | ja | ja |
| UsageDate | ja | ja |
| MeterType | ja | Nein |
| MeterCategory | ja | Nein |
| MeterId | ja | Nein |
| MeterSubCategory | ja | Nein |
| MeterName | ja | Nein |
| MeterRegion | ja | Nein |
| Einheit | ja | ja |
| ResourceLocation | ja | Nein |
| ConsumedService | ja | Nein |
| ResourceGroup | ja | Nein |
| ResourceURI | ja | ja |
| ChargeType | ja | ja |
| UnitPrice | ja | ja |
| Menge | ja | ja |
| UnitType | ja | Nein |
| BillingPreTaxTotal | ja | ja |
| BillingCurrency | ja | ja |
| PricingPreTaxTotal | ja | ja |
| PricingCurrency | ja | ja |
| ServiceInfo1 | ja | Nein |
| ServiceInfo2 | ja | Nein |
| `Tags` | ja | Nein |
| AdditionalInfo | ja | Nein |
| EffectiveUnitPrice | ja | ja |
| PCToBCExchangeRate | ja | ja |
| PCToBCExchangeRateDate | ja | Nein |
| EntitlementId | ja | ja |
| EntitlementDescription | ja | Nein |
| PartnerEarnedCreditPercentage | ja | Nein |
| CreditPercentage | ja | ja |
| CreditType | ja | ja |
| BenefitOrderID | ja | ja |
| BenefitID | ja | Nein |
| BenefitType | ja | ja |