Rechnungsabstimmungs-API v2 (GA)
Gilt für: Partner Center (nicht verfügbar in souveräner Cloud)
Unsere asynchrone API bietet eine schnellere und verwaltbare Möglichkeit für den Zugriff auf Abrechnungs- und Abstimmungsdaten über Azure-Blobs. Mit dieser API müssen Sie eine Verbindung nicht stundenlang geöffnet lassen oder die Batches von 2.000 Zeilenelementen gleichzeitig durchlaufen.
Wir haben unsere neue abrechnungsbasierte Rechnungsabrechnungs-API mit Valet-Schlüssel und asynchronen Anforderungsantwortmustern optimiert. Diese API stellt Ihnen ein SAS-Token (Shared Access Signature) bereit, mit dem Sie entweder auf alle Attribute oder eine Teilmenge der Rechnungsabstimmungsdaten zugreifen können.
Hinweis
Die neue API wird 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. Informationen zum Zugriff auf diese API finden Sie in den folgenden Details.
Sie können diese API nur für die öffentliche/globale CLOUD von MS Graph verwenden. Es ist noch nicht für Azure Government, Azure Deutschland oder Azure China 21Vianet verfügbar.
API-Übersicht
Verwenden Sie zwei API-Endpunkte, um asynchron abrechnungsbasierte Rechnungsabrechnungsdaten abzurufen. Der Prozess hierfür ist folgender:
Abrechnungsendpunkt für Rechnungsabrechnungen
Verwenden Sie diese API, um neue Rechnungsabrechnungspositionen abzurufen. Die API gibt einen 202 HTTP-Status und einen Speicherortheader zurück, der eine 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 neuer Rechnungsabgleichsdaten zeigt.
Benutzeraktionssequenz
Führen Sie die folgenden Schritte aus, um Rechnungsabrechnungsdaten abzurufen:
Schritt 1: Senden einer Anforderung
Senden Sie eine POST-Anforderung an den API-Endpunkt.
Rechnungsabrechnungspositionen abrufen
API-Anforderung
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
Abfrageparameter
N/V
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 in diesem Artikel). Optional. |
| invoiceId | True | String | Ein eindeutiger Bezeichner für jede Rechnung. Erforderlich. |
Anforderungsheader
Fordern Sie Kopfzeilen für die API mithilfe der Unter " Bewährte Methoden für die Verwendung von Microsoft Graph" aufgeführten Schritte an.
API-Antwort
HTTP/1.1 202 Accepted
Location: <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Die API antwortet in der Regel mit einem HTTP 202-Status. Andere mögliche Status werden basierend auf Ihren Anforderungen in den Standard-API-Antwortstatus in diesem Artikel aufgeführt.
| 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". Sie erhalten die Manifest-URL im Attribut "resourceLocation", wenn die Anforderung erfolgreich ist.
Vorgangsstatus abrufen
Ruft den Status einer Anforderung ab.
API-Anforderung
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Anforderungsparameter
| Name | Einschließen in | Erforderlich | Type | Beschreibung |
|---|---|---|---|---|
| operationId | Anforderungs-URI | True | String | Eine eindeutige ID zum Überprüfen des Anforderungsstatus. Erforderlich. |
Anforderungsheader
Fordern Sie Kopfzeilen für die API mithilfe der Unter " Bewährte Methoden für die Verwendung von Microsoft Graph" aufgeführten Schritte an.
Anforderungstext
N/V.
Antwortstatus
Zusätzlich zu den standardmäßigen HTTP-Status, die in den Standard-API-Antwortstatus in diesem Artikel aufgeführt sind, kann die API den folgenden HTTP-Status zurückgeben:
| Code | Beschreibung |
|---|---|
| 410 – Nicht mehr | Der Manifestlink läuft nach einer festgelegten Zeit ab. Um den Manifestlink erneut abzurufen, senden Sie eine neue Anforderung. |
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 sind enthalten: message: Eine detaillierte Beschreibung des Fehlers. Code: 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 partitionValue-Attribut 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: Name des BLOB. partitionValue: Partition, die die Datei enthält. Die große Partition wird in mehrere Dateien aufgeteilt, wobei jede Datei denselben "partitionValue" 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 es erneut versuchen, wenn Ihre Daten noch verarbeitet werden.
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 von Rechnungsabrechnungsdaten 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. Azure Storage SDK/Tool zum Herunterladen und Entpacken der BLOB-Datei. Sie befindet sich im JSONLines-Format .
Tipp
Sehen Sie sich unseren Beispielcode an, um die Azure-BLOB-Datei in Ihre lokale Datenbank herunterzuladen und zu entpacken.
Standard-API-Antwortstatus
Möglicherweise erhalten Sie diese HTTP-Status aus der Antwort der API:
| 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 mit den bereitgestellten Eingabeparametern nicht verfügbar. |
| 410 – Nicht mehr | Der Manifestlink ist nicht mehr gültig oder aktiv. 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. |
Rechnungsabrechnungsdatenattribute
Informationen zum Vergleichen der Attribute, die von der Rechnungsabstimmungs-API für die Attributsätze "full" oder "basic" zurückgegeben werden, finden Sie in der folgenden Tabelle.
| Attribut | Vollständig | Grundlegend |
|---|---|---|
| PartnerId | ja | ja |
| CustomerId | ja | ja |
| CustomerName | ja | ja |
| CustomerDomainName | ja | Nein |
| CustomerCountry | ja | Nein |
| InvoiceNumber | ja | ja |
| MpnId | ja | Nein |
| Tier2MpnId | ja | ja |
| OrderId | ja | ja |
| OrderDate | ja | ja |
| ProductId | ja | ja |
| SkuId | ja | ja |
| AvailabilityId | ja | ja |
| SkuName | ja | Nein |
| ProductName | ja | ja |
| ChargeType | ja | ja |
| UnitPrice | ja | ja |
| Menge | ja | Nein |
| Zwischensumme | ja | ja |
| TaxTotal | ja | ja |
| Gesamt | ja | ja |
| Währung | ja | ja |
| PriceAdjustmentDescription | ja | ja |
| PublisherName | ja | ja |
| PublisherId | ja | Nein |
| SubscriptionDescription | ja | Nein |
| SubscriptionId | ja | ja |
| ChargeStartDate | ja | ja |
| ChargeEndDate | ja | ja |
| TermAndBillingCycle | ja | ja |
| EffectiveUnitPrice | ja | ja |
| UnitType | ja | Nein |
| AlternateId | ja | Nein |
| BillableQuantity | ja | ja |
| BillingFrequency | ja | Nein |
| PricingCurrency | ja | ja |
| PCToBCExchangeRate | ja | ja |
| PCToBCExchangeRateDate | ja | Nein |
| MeterDescription | ja | Nein |
| ReservationOrderId | ja | ja |
| CreditReasonCode | ja | ja |
| SubscriptionStartDate | ja | ja |
| SubscriptionEndDate | ja | ja |
| ReferenceId | ja | ja |
| ProductQualifiers | ja | Nein |
| PromotionId | ja | ja |
| ProductCategory | ja | ja |
Beispielcode
Anleitungen zur Verwendung der API finden Sie unter dem folgenden Link, der Beispielcode in C# enthält.
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