Abgerechnete und nicht abgerechnete tägliche Nutzungsabstimmungs-API v2 (GA)
Gilt für: Partner Center (nicht verfügbar in Azure Government, Azure Deutschland oder Azure China 21Vianet.)
Unsere asynchronen APIs bieten eine schnellere und verwaltbare Möglichkeit für den Zugriff auf Abrechnungs- und Abstimmungsdaten über Azure-Blobs. Mit diesen APIs müssen Sie die Verbindung nicht stundenlang geöffnet lassen oder die Batches von 2.000 Zeilenelementen durchlaufen.
Wir haben unsere täglich bewerteten Nutzungsabstimmungs-APIs mit Valet-Schlüssel und asynchronen Anforderungsantwortmustern optimiert. Wenn Sie diese APIs verwenden, erhalten Sie ein Token, mit dem Sie entweder auf alle Attribute oder eine Teilmenge der täglich bewerteten Nutzungssausgleichsdaten zugreifen können.
Hinweis
Die neuen APIs werden nicht auf dem Partner Center-API-Host gehostet. Stattdessen finden Sie sie auf MS Graph unter Verwendung der Microsoft Graph-API zum Exportieren von Partnerabrechnungsdaten – Microsoft Graph v1.0 | Microsoft Learn. Informationen zum Zugriff auf diese APIs finden Sie in den folgenden Details.
Sie können diese APIs derzeit nur für die öffentliche/globale Cloud von MS Graph verwenden. Sie ist noch nicht für Azure Government, Azure Deutschland oder Azure China 21Vianet verfügbar.
Hinweis
Wenn Sie unsere Betaversion verwendet haben, bemerken Sie möglicherweise keine signifikanten Änderungen in der allgemein verfügbaren (GA)-Version. Es wird empfohlen , die beiden Versionen zu vergleichen , um die Unterschiede und Updates zu verstehen.
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
Um täglich bewertete Nutzungsdaten asynchron abzurufen, verwenden Sie zwei API-Endpunkte. Der Prozess hierfür ist folgender:
Endpunkt für Verwendungszeilenelemente
Verwenden Sie diese API, um berechnete oder nicht abgerechnete tägliche Nutzungspositionen abzurufen. Die API gibt einen 202 HTTP-Status und einen Speicherortheader zurück, der die URL enthält. Diese URL in regelmäßigen Abständen abfragen, bis Sie einen Erfolgsstatus mit einer Manifest-URL erhalten.
Vorgangsstatusendpunkt
Um einen Erfolgsstatus zu erhalten, rufen Sie diese API in regelmäßigen Abständen auf. Wenn die Daten nicht bereit sind, enthält die API-Antwort einen Retry-After-Header, um Ihnen mitzuteilen, wie lange sie warten müssen, bevor Sie es erneut versuchen. Wenn der Vorgang abgeschlossen ist, erhalten Sie eine Manifestressource mit einem Speicherordner, in dem Sie die Nutzungsdaten herunterladen können. Die Antwort unterteilt die Dateien in kleinere Teile für den optimierten Durchsatz und die E/A-Parallelität.
Sequenzdiagramm
Hier ist ein Sequenzdiagramm, das die Schritte zum Herunterladen der Abstimmungsdaten zeigt.
Benutzeraktionssequenz
Führen Sie die folgenden Schritte aus, um täglich bewertete Nutzungsabstimmungsdaten abzurufen:
Schritt 1: Senden einer Anforderung
Senden Sie eine POST-Anforderung an den API-Endpunkt.
Abrufen nicht abgerechneter täglich bewerteter Nutzungspositionen
Erhalten Sie nicht berechnete tägliche Nutzungspositionen für den aktuellen oder letzten Kalendermonat oder Abrechnungszeitraum.
API-Anforderung
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
Accept: application/json
Content-Type: application/json
{
"currencyCode": "USD",
"billingPeriod": "current",
"attributeSet": "basic"
}
Anforderungstext
| Attribut | Erforderlich | Type | Beschreibung |
|---|---|---|---|
| attributeSet | False | String | Wählen Sie "vollständig" für alle Attribute oder "Einfach" für einen begrenzten Satz aus. Der Standardwert ist "vollständig". (Siehe die Liste der Attribute hier). Optional. |
| billingPeriod | True | String | Verwenden Sie "current" oder "last" (identisch mit "previous" in V1-APIs), um die tägliche Bewertungsnutzung für den aktuellen oder letzten Kalendermonat oder Abrechnungszeitraum zu erhalten. Erforderlich. |
| currencyCode | True | String | Partnerabrechnungswährungscode. Erforderlich. |
Anforderungsheader
Informationen zum Anfordern von Headern für die API finden Sie unter Zuverlässigkeit und Support.
API-Antwort
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
Wenn Sie die API verwenden, wird in der Regel ein HTTP 202-Status zurückgegeben. Weitere mögliche Status basierend auf Ihren Anforderungen finden Sie unter Standard-API-Antwortstatus.
| Code | Beschreibung |
|---|---|
| 202 – Akzeptiert | Ihre Anfrage wurde angenommen. Um den Status Ihrer Anforderung zu überprüfen, fragen Sie die url ab, die im Speicherortheader angegeben ist. |
Abrufen der täglich bewerteten Nutzungspositionen
Erhalten Sie täglich bewertete Nutzungspositionen für eine Rechnung für den abgeschlossenen Abrechnungszeitraum.
API-Anforderung
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
Abfrageparameter
N/V
Anforderungstext
| Attribut | Erforderlich | Type | Beschreibung |
|---|---|---|---|
| invoiceId | True | String | Ein eindeutiger Bezeichner für jede Rechnung. Erforderlich. |
| attributeSet | False | String | Wählen Sie "vollständig" für alle Attribute oder "Einfach" für einen begrenzten Satz aus. Der Standardwert ist "vollständig". (Siehe die Liste der Attribute hier). Optional. |
Anforderungsheader
Anforderungsheader für die API. Weitere Informationen finden Sie unter Zuverlässigkeit und Support.
API-Antwort
HTTP/1.1 202 akzeptiert
Ort: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
Wenn Sie die API verwenden, wird in der Regel ein HTTP 202-Status zurückgegeben. Weitere mögliche Status basierend auf Ihren Anforderungen finden Sie unter Statuses.
| Code | Beschreibung |
|---|---|
| 202 – Akzeptiert | Ihre Anfrage wurde angenommen. Um den Status Ihrer Anforderung zu überprüfen, fragen Sie die url ab, die im Speicherortheader angegeben ist. |
Schritt 2: Überprüfen des Anforderungsstatus
Um den Status einer Anforderung zu überprüfen, warten Sie auf eine HTTP 200-Antwort mit dem Status "erfolgreich" oder "fehlgeschlagen". Wenn die Anforderung erfolgreich ist, wird die Manifest-URL im Attribut "resourceLocation" bereitgestellt.
Vorgangsstatus abrufen
Ruft den Status einer Anforderung ab.
API-Anforderung
Anforderungsparameter
| Name | Einschließen in | Erforderlich | Type | Beschreibung |
|---|---|---|---|---|
| operationId | Anforderungs-URI | True | String | Eine eindeutige ID zum Überprüfen des Anforderungsstatus. Erforderlich. |
Anforderungsheader
Informationen zum Anfordern von Headern für die API finden Sie unter Zuverlässigkeit und Support.
Anforderungstext
N/V.
Antwortstatus
Zusätzlich zu den standardmäßigen HTTP-Status kann die API den folgenden HTTP-Status zurückgeben:
| Code | Beschreibung |
|---|---|
| 410 – Nicht mehr | Der Manifestlink ist nur für eine bestimmte Dauer aktiv, die vom Server festgelegt wird. Nach ablauf dieser Zeit müssen Sie eine neue Anforderung für den Zugriff auf das Manifest übermitteln. |
Antwortnutzlast
Die API-Antwortnutzlast enthält die folgenden Attribute:
| Attribut | Erforderlich | Beschreibung |
|---|---|---|
| id | True | Eine eindeutige ID für jede Antwort. Erforderlich. |
| status | True | Werte und Aktionen (erforderlich): notstarted: Warten Sie, bis die im Header "Retry-After" angegebene Zeit angegeben ist, und führen Sie dann einen weiteren Aufruf aus, um den Status zu überprüfen. running: Wait for the time specified in the "Retry-After" header, then make another call to check the status. erfolgreich: Die Daten sind bereit. Rufen Sie die Manifestnutzlast mithilfe des in resourceLocation angegebenen URI ab. failed: The operation failed permanent. Starten Sie ihn neu. |
| createdDateTime | True | Der Zeitpunkt, zu dem die Anforderung gestellt wurde. Erforderlich. |
| lastActionDateTime | True | Der Zeitpunkt, zu dem der Status zuletzt geändert wurde. Erforderlich. |
| resourceLocation | False | Der URI für die Manifestnutzlast. Optional. |
| error | False | Wenn der Vorgang fehlschlägt, werden Fehlerdetails im JSON-Format bereitgestellt. Optional. Die folgenden Attribute können enthalten sein: message (Required): Eine detaillierte Beschreibung des Fehlers. Code (Erforderlich): Der Typ des aufgetretenen Fehlers. |
Ressourcenspeicherortobjekt
| Attribute | Beschreibung |
|---|---|
| id | Ein eindeutiger Bezeichner für das Manifest. |
| schemaVersion | Version des Manifestschemas. |
| dataFormat | Format der Abrechnungsdatendatei. compressedJSON: Data format where each blob is a compressed file that contains data in JSON lines format. Um die Daten aus jedem Blob abzurufen, dekomprimieren Sie sie. |
| createdDateTime | Datum und Uhrzeit der Erstellung der Manifestdatei. |
| eTag | Version der Manifestdaten. Eine Änderung der Abrechnungsinformationen generiert einen neuen Wert. |
| partnerTenantId | ID des Mandanten des Partners. |
| Rootdirectory | Stammverzeichnis der Datei. |
| sasToken> | SAS-Token (Freigegebene Zugriffssignatur), mit dem Sie alle Dateien unter dem Verzeichnis lesen können. |
| partitionType | Dividiert Daten basierend auf dem Attribut "partitionValue" in mehrere Blobs. Das System teilt Partitionen auf, die die unterstützte Zahl überschreiten. Standardmäßig werden Daten basierend auf der Anzahl der Zeilenelemente in der Datei partitioniert. Legen Sie im Code keine feste Anzahl von Zeilenelementen oder Dateigrößen fest, da sich diese Werte ändern können. |
| blobCount | Gesamtanzahl der Dateien für diese Partnermandanten-ID. |
| blobs | Ein JSON-Array von "blob"-Objekten, die die Dateidetails für die Partnermandanten-ID enthalten. |
| Blob-Objekt | Ein Objekt, das die folgenden Details enthält: |
| name | Der Name des Blobs. |
| partitionValue | Partition, die die Datei enthält. Die große Partition wird in mehrere Dateien aufgeteilt, wobei jede Datei denselben "partitionValue" enthält. |
API-Anforderung
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-Antwort
Die Antwort empfiehlt, auf 10 Sekunden zu warten, bevor sie beim Verarbeiten von Daten erneut versucht wird.
HTTP/1.1 200 OK
Retry-After: 10
{
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-05Z",
"status": "running"
}
API-Anforderung
(10 Sekunden nach der vorherigen Anforderung...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-Antwort
Die API gibt den Status "erfolgreich" und den URI für "resourceLocation" zurück.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",
"@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",
"id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",
"createdDateTime": "2023-12-05T21:17:29Z",
"lastActionDateTime": "2023-12-05T21:18:00.8897902Z",
"status": "succeeded",
"resourceLocation": {
"id": "44e8500b-ab92-490e-8ac3-90500a1d3427",
"createdDateTime": "2023-11-06T19:58:47.513Z",
"schemaVersion": "2",
"dataFormat": "compressedJSON",
"partitionType": "default",
"eTag": "RwDrn7fbiTXy6UULE",
"partnerTenantId": "0e195b37-4574-4539-bc42-0e539b9684c0",
"rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",
"sasToken": "{token}",
"blobCount": 1,
"blobs": \[
{
"name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",
"partitionValue": "default"
}
\]
}
}
Schritt 3: Herunterladen täglich bewerteter Nutzungssausgleichsdaten aus Azure Blob Storage
Rufen Sie das SAS-Token (Shared Access Signature) und den BLOB-Speicherort aus den Eigenschaften "sasToken" und "rootDirectory" der Manifestnutzlast-API-Antwort ab. Verwenden Sie das Azure Storage SDK/Tool, um die BLOB-Datei herunterzuladen und zu entpacken. Es befindet sich im JSONLines-Format .
Standard-API-Antwortstatus
Möglicherweise erhalten Sie diese HTTP-Status aus der API-Antwort:
| Code | Beschreibung |
|---|---|
| 400 – Ungültige Anforderung | Die Anforderung fehlt oder enthält falsche Daten. Überprüfen Sie den Antworttext auf Fehlerdetails. |
| 401 – Nicht autorisiert | Der Aufrufer ist nicht authentifiziert, und Sie müssen sich beim Partner-API-Dienst authentifizieren, bevor Sie den ersten Aufruf ausführen. |
| 403 – Unzulässig | Sie verfügen nicht über die erforderliche Autorisierung, um die Anforderung zu stellen. |
| 404 – Nicht gefunden | Die angeforderten Ressourcen sind nicht mit den bereitgestellten Eingabeparametern verfügbar. |
| 410 – Nicht mehr | Timeout des Manifestlinks oder abgelaufen. Senden Sie eine neue Anforderung. |
| 500: interner Serverfehler | Die API oder eine ihrer Abhängigkeiten kann die Anforderung im Moment nicht erfüllen. Versuchen Sie es später noch einmal. |
Vergleichen von Beta- und GA-Versionen
Sehen Sie sich die Vergleichstabelle an, um die Unterschiede zwischen den Beta- und allgemein verfügbaren (GA)-Versionen zu verstehen. Wenn Sie die Betaversion verwenden, sollte der Wechsel zur GA-Version einfach sein.
| Wichtige Informationen | Beta | Allgemein verfügbar |
|---|---|---|
| API-Hostendpunkt | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| HTTP-Methode | POST | NACHRICHT |
| Nicht abgerechneter endpunkt der täglich bewerteten Nutzungs-API | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| Eingabeparameter für die nicht berechnete tägliche Nutzungs-API | Um Parameter in der API-Anforderung anzugeben, fügen Sie sie in die Abfragezeichenfolge der Anforderungs-URL ein. Um beispielsweise die Parameter "period" und "currencyCode" anzugeben, fügen Sie sie an die Anforderungs-URL an ?period=current¤cyCode=usd . |
Um Eingaben bereitzustellen, fügen Sie ein JSON-Objekt in den Anforderungstext ein. Das JSON-Objekt sollte die folgenden Eigenschaften enthalten: * currencyCode: Der Währungscode für die Rechnung. Beispiel: USD. * billingPeriod: Der Abrechnungszeitraum für die Rechnung. Beispiel: aktuell. Hier ist ein Beispiel für ein JSON-Objekt, das die CurrencyCode- und billingPeriod-Eigenschaften enthält: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Endpunkt der täglich bewerteten Nutzungs-API | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| Eingabeparameter für die abgerechnete tägliche Nutzungs-API | Um Parameter in der API-Anforderung anzugeben, fügen Sie die invoiceId in die Anforderungs-URL ein. Darüber hinaus können Sie einen optionalen Fragmentparameter in die Abfragezeichenfolge einschließen, um den vollständigen Satz von Attributen abzurufen. Um beispielsweise den vollständigen Satz von Attributen abzurufen, hängen Sie ?fragment=full an die Anforderungs-URL an. |
Um Eingaben bereitzustellen, fügen Sie ein JSON-Objekt in den Anforderungstext ein. Das JSON-Objekt sollte die folgenden Eigenschaften enthalten: * invoiceId: Die ID der Rechnung. Beispiel: G00012345. * attributeSet: Der Satz von Attributen, die in die Antwort eingeschlossen werden sollen. Beispiel: vollständig. Hier ist ein Beispiel für ein JSON-Objekt, das die eigenschaften invoiceId und attributeSet enthält: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| Manifestressource | Verwenden Sie eine separate GET /manifests/{id}-Methode, um die Manifestressource abzurufen. | Verwenden Sie GET /operations/{Id} -Methode, die die zugehörige Manifestressource in resourceLocation zurückgibt, ohne dass ein separater Aufruf der GET /manifests/{id} -Methode erforderlich ist. |
| Änderungen am Manifestschema | ||
| "id": Nicht verfügbar | "id": Ein eindeutiger Bezeichner für die Manifestressource. | |
| "version": Verfügbar | "version": umbenannt in "schemaversion". | |
| "dataFormat": Verfügbar | "dataFormat": Verfügbar. | |
| "utcCretedDateTime": Verfügbar | "utcCretedDateTime": umbenannt in "createdDateTime". | |
| "eTag": Verfügbar | "eTag": Verfügbar. | |
| "partnerTenantId": Verfügbar | "partnerTenantId": Verfügbar | |
| "rootFolder": Verfügbar | "rootFolder": umbenannt in "rootDirectory". | |
| "rootFolderSAS": Verfügbar | "rootFolderSAS": umbenannt in "sasToken". Es stellt jetzt ein Token bereit und enthält nicht mehr den Stammverzeichnispfad. Um auf das Verzeichnis zuzugreifen, verwenden Sie stattdessen die Eigenschaft "rootDirectory". | |
| "partitionType": Verfügbar | "partitionType": Verfügbar. | |
| "blobCount": Verfügbar | "blobCount": Verfügbar. | |
| "sizeInBytes": Verfügbar | "sizeInBytes": Nicht verfügbar. | |
| "Blobs": Verfügbar | "blobs": Verfügbar. | |
| "blob-Objekt": Verfügbar | "blob-Objekt": Verfügbar. | |
| "name": Verfügbar | "name": Verfügbar. | |
| "partitionValue": Verfügbar | "partitionValue": Verfügbar. |
Täglich bewertete Nutzungsabstimmungsdatenattribute
Informationen zum Vergleichen der Attribute, die von der täglich bewerteten Verwendungssensöhn-API für die Attributsätze "full" oder "basic" zurückgegeben werden, finden Sie in den folgenden Informationen.
| Attribut | Vollständig | Grundlegend |
|---|---|---|
| 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 |
Wichtig
Notieren Sie sich diese Änderungen, wenn Sie von v1 zu API v2 wechseln.
Der Name jedes Attributs beginnt in Großbuchstaben.
unitOfMeasure ist jetzt Unit. Die Bedeutung und der Wert des Attributs sind identisch.
resellerMpnId ist jetzt Tier2MpnId. Die Bedeutung und der Wert des Attributs sind identisch.
Der Name und wert von rateOfPartnerEarnedCredit haben sich in PartnerEarnedCreditPercentage geändert. Der neue Name und wert des Attributs spiegeln den Prozentsatz anstelle des Bruchs wider. Beispielsweise ist 15 jetzt 0,15.
rateOfCredit ist jetzt CreditPercentage. Die Bedeutung und der Wert des Attributs haben sich geändert. Beispielsweise ist 1.00 jetzt 100.
Beispielcode
Weitere Informationen finden Sie unter Partner Center-API-Beispiele: Abrufen von Abrechnungsdaten.
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