Abrechnungs- und Abstimmungs-API v2 (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 asynchron abgerechnete und nicht abgerechnete Nutzungsdaten abzurufen.
Hinweis
Diese API für die abgerechnete tägliche Nutzung funktioniert nach dem 30. Juni 2024 nicht mehr. Weitere Informationen finden Sie in den folgenden Details, um zu entscheiden, welche Version Sie wann verwendet sollten.
- Wenn Sie nicht zu v2 GA gewechselt haben, verwenden Sie diese API bis zum 30. Juni 2024, um die täglich bewerteten Nutzungspositionen für Rechnungen zu erhalten, die für Abrechnungszeiträume zwischen September 2022 und Juni 2024 erstellt werden.
- Verwenden Sie nur API v2 GA nach dem 30. Juni 2024, um die täglich bewerteten Nutzungspositionen für Rechnungen zu erhalten, die ab September 2022 für Abrechnungszeiträume erstellt werden.
Diese API für nicht berechnete tägliche Nutzung funktioniert nach dem 30. Juni 2024 nicht mehr. Weitere Informationen finden Sie in den folgenden Details, um zu entscheiden, welche Version Sie wann verwendet sollten.
- Wenn Sie nicht zu v2 GA gewechselt haben, verwenden Sie diese API bis zum 30. Juni 2024, um nicht berechnete tägliche Nutzungspositionen für aktuelle und vorherige Abrechnungszeiträume zu erhalten.
- Verwenden Sie nach dem 30. Juni 2024 nur die API v2 GA, um nicht abgerechnete täglich bewertete Verbrauchspositionen für die aktuelle und vorherige Abrechnung zu erhalten.
Informationen zum Vorbereiten der Migration zu den neuen v2 GA-APIs finden Sie unter dem folgenden Link:
Abgerechnete und nicht abgerechnete tägliche Nutzungsabstimmungs-API v2 (GA)
Hinweis
Sie können Ihre täglichen unbilligten Nutzungsdaten über das API- oder Partner Center-Portal abrufen. Es kann bis zu 24 Stunden dauern, bis die Daten verfügbar sind. Je nach Standort und dem Zeitpunkt, an dem die Zähler die Nutzung melden, kann es jedoch weitere Verzögerungen geben.
Manchmal werden die neuesten nicht berechneten Nutzungsdaten möglicherweise erst angezeigt, wenn die in Rechnung gestellten Nutzungsdaten für den vorherigen Monat übermittelt werden. Dies erfolgt, um sicherzustellen, dass in Rechnung gestellte Nutzungsdaten innerhalb der vereinbarten Zeit übermittelt werden. Sobald Sie die in Rechnung gestellten Nutzungsdaten erhalten haben, sollten Sie alle aktualisierten nicht berechneten Nutzungsdaten ab Beginn des Monats abrufen können.
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 von Drittanbietern
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 zu Standard und Millionen von Transaktionen iterativ zu durchlaufen.
Wir haben die Muster für Startschlüssel und asynchrone Anforderung/Antwort verwendet, um unsere Rechnungs- und Abstimmungs-APIs zu optimieren und die Ergebnisse asynchron bereitzustellen. 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 folgenden Artikeln:
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 folgende 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 | N/V. (Es gibt alle Azure-Plannutzung zurück und entspricht dem "einmaligen" vorhandener V1-APIs.) |
| hasPartnerEarnedCredit | N/V. (gibt alle Daten unabhängig von PEC zurück.) |
| Size | N/V. |
| Abweichung | N/V. |
| seekOperation | N/V. |
Anforderungsheader
Eine Liste der Anforderungsheader für die API finden Sie in diesem Artikel.
Anforderungstext
N/V.
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 wurde 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 | N/V. (Es gibt alle Azure-Plannutzung zurück und entspricht dem "einmaligen" vorhandener V1-APIs.) |
| hasPartnerEarnedCredit | N/V. (gibt alle Daten unabhängig von PEC zurück.) |
| Size | N/V. |
| Abweichung | N/V. |
| seekOperation | N/V. |
Anforderungsheader
Eine Liste der Anforderungsheader für die API finden Sie in diesem Artikel.
Anforderungstext
N/V.
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 wurde 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 lautet "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
N/V.
Antwortstatus
Zusätzlich zum standardmäßigen HTTP-Status in diesem Artikel kann die API den HTTP-Status unter http-Status zurückgeben:
| Name | Beschreibung |
|---|---|
| 410 Nicht mehr vorhanden | Jede Vorgangsverknüpfung ist für eine bestimmte Serverzeit aktiv. Nachdem die Zeit verstrichen ist, 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
N/V.
Antwortstatus
Zusätzlich zum standardmäßigen HTTP-Status kann die API den HTTP-Status unter http-Status zurückgeben:
| Name | Beschreibung |
|---|---|
| 410 Nicht mehr vorhanden | Jede Manifestverknüpfung ist für eine bestimmte Menge servergesteuerter Zeit aktiv. Nachdem die Zeit verstrichen ist, 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 . Dekomprimieren Sie die Datei, um auf die Daten zuzugreifen. |
| 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. Die Daten werden standardmäßig durch die Anzahl der Zeilenelemente in der Datei partitioniert. Legen Sie im Code keine feste Anzahl von Zeilenelementen oder Dateigrößen fest, da sich diese ändern können. |
| 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 mal. |
| 404 Nicht gefunden | Ressource mit Eingabeparametern nicht verfügbar. |
| 410 Nicht mehr vorhanden | Der Manifestlink ist abgelaufen oder verstrichen. 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 |
| EntitlementId | ja | ja |
| EntitlementDescription | ja | Nein |
| PartnerEarnedCreditPercentage | ja | Nein |
| CreditPercentage | ja | ja |
| CreditType | ja | ja |
| BenefitOrderID | ja | ja |
| BenefitID | ja | Nein |
| BenefitType | ja | ja |
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für