Freigeben über


Rechnungsabstimmungs-API v2 (GA)

Gilt für: Partner Center (nicht verfügbar in souveräner Cloud)

Unsere neue asynchrone API bietet eine schnellere und effizientere Möglichkeit, über Azure-Blobs auf Ihre Abrechnungs- und Abstimmungsdaten zuzugreifen. Anstatt eine Verbindung für Stunden offen zu halten oder Batches von 2.000 Zeilenelementen zu verarbeiten, können Sie ihren Workflow jetzt optimieren, die Serverlast reduzieren und Datenverarbeitungszeiten verbessern.

Die neue Abrechnungs-API für die Rechnungsabrechnung verwendet erweiterte Techniken wie Valet-Schlüssel und asynchrone Anforderungsantwortmuster . Das Valet-Schlüsselmuster unterstützt den sicheren Zugriff auf Ressourcen ohne Freigabe von Anmeldeinformationen, während das asynchrone Anforderungsantwortmuster eine effiziente Kommunikation zwischen Systemen ermöglicht.

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. Dieses Token verbessert die Sicherheit, indem ein zeitlich beschränkter Zugriff gewährt und das Verwalten von Datenzugriffsberechtigungen flexibel gestaltet wird.

Durch die Nutzung unserer optimierten APIs können Sie schnellere Ergebnisse mit weniger Aufwand erzielen, den Datenzugriff vereinfachen und die Gesamteffizienz verbessern. Nutzen Sie diese Tools, um Ihren Workflow zu optimieren und Berechtigungen effektiver zu verwalten.

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.

Zulassen, dass Ihre App sicher auf Partnerabrechnungsdaten zugreifen kann

Um Ihrer App den Zugriff auf Partnerabrechnungsdaten zu ermöglichen, klicken auf Sie diesen Link, und machen Sie sich mit den Authentifizierungs- und Autorisierungsgrundlagen für Microsoft Graph vertraut. Dieser Schritt ist entscheidend, da so sichergestellt wird, dass Ihre App sicher auf die erforderlichen Daten zugreifen kann.

Registrieren Sie Ihre App und weisen Sie die Berechtigung "PartnerBilling.Read.All" zu.

Sie können die Berechtigung "PartnerBilling.Read.All" entweder über das Azure-Portal oder das Microsoft Entra Admin Center zuweisen. Durch Ausführen dieser Schritte können Sie sicherstellen, dass Ihre App über den erforderlichen Zugriff auf Partnerabrechnungsdaten verfügt. Gehen Sie dazu wie folgt vor:

  1. Registrieren Sie Ihre App auf der Microsoft Entra-Startseite unter dem Abschnitt App-Registrierungen.
  2. Weisen Sie die erforderlichen Berechtigungen zu, indem Sie zur Microsoft Entra App-Seite wechseln. Wählen Sie im Abschnitt zu den API-Berechtigungen zunächst die Option Berechtigung hinzufügen und dann den Bereich PartnerBilling.Read.All aus.

Informationen zu den wichtigsten API-Endpunkten

Um Ihnen beim asynchronen Abrufen neuer Rechnungsabrechnungspositionen zu helfen, bieten wir zwei wichtige API-Endpunkte an. Diese Endpunkte helfen Ihnen bei der effizienten Verwaltung Ihres Rechnungsausgleichsprozesses. Befolgen Sie diesen optimierten Leitfaden, um schnell loszulegen.

Verwenden des Rechnungsabstimmungsendpunkts

Verwenden Sie zunächst diese API, um neue Rechnungsabgleichspositionen abzurufen. Wenn Sie eine Anforderung stellen, erhalten Sie einen HTTP-Status 202 und einen Speicherortheader mit einer URL. Rufen Sie diese URL regelmäßig ab, bis Sie einen Erfolgsstatus und eine Manifest-URL erhalten.

Verwenden Sie den Betriebsstatus-Endpunkt

Überprüfen Sie als Nächstes den Vorgangsstatus, indem Sie diese API in regelmäßigen Abständen aufrufen. Wenn die Daten nicht bereit sind, enthält die Antwort einen Retry-After-Header , der angibt, wie lange gewartet werden soll, bevor sie es erneut versuchen. Nach Abschluss des Vorgangs erhalten Sie eine Manifestressource mit einem Speicherordnerlink zum Herunterladen der Nutzungsdaten. Die Antwortsegmente der Dateien, um den Durchsatz zu verbessern und die E/A-Parallelität zu ermöglichen.

Überprüfen des Sequenzdiagramms

Hier ist ein Sequenzdiagramm, das die Schritte zum Herunterladen neuer Rechnungsabgleichsdaten zeigt.

Diagramm, das die Schritte zum Herunterladen von Abstimmungsdaten zeigt.

Folgen Sie der Benutzeraktionssequenz, um Rechnungsabgleichungsdaten abzurufen.

Dies ist die Aktionssequenz des Benutzers zum Abrufen von Rechnungsabgleichsdaten:

Senden einer POST-Anforderung

Senden Sie eine POST-Anforderung an den API-Endpunkt.

Rechnungsabrechnungspositionen abrufen

Rufen Sie die Rechnungsabstimmungspositionen ab.

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. Wenn nicht angegeben, ist "full" der Standardwert. Überprüfen Sie die Liste der Attribute in diesem Abschnitt. 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. Durch die Einhaltung dieser Richtlinien stellen Sie Zuverlässigkeit und Unterstützung für Ihre Anwendung sicher. Ihre Aufmerksamkeit auf Details in diesem Schritt ist entscheidend für die nahtlose Integration und optimale Leistung.

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. Gemäß Ihren Anforderungen können auch andere Status auftreten. Diese Status werden im Abschnitt "Standard-API-Antwortstatus" 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.

Überprüfen des Anforderungsstatus

Um den Status einer Anforderung nachzuverfolgen, stellen Sie sicher, dass Sie eine HTTP 200-Antwort erhalten. Dabei handelt es sich um einen Standardstatuscode, der den Status „erfolgreich“ oder „fehlgeschlagen“ angibt. Bei erfolgreichem Status finden Sie die Manifest-URL im Attribut „resourceLocation“. Dieses Attribut stellt einen Endpunkt für den Zugriff auf die erforderlichen Informationen bereit.

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 Ein eindeutiger Bezeichner, um den Anforderungsstatus zu überprüfen. 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. Durch die Einhaltung dieser Richtlinien stellen Sie Zuverlässigkeit und Unterstützung für Ihre Anwendung sicher. Ihre Aufmerksamkeit auf Details in diesem Schritt ist entscheidend für die nahtlose Integration und optimale Leistung.

Anforderungstext

Nicht zutreffend.

Antwortstatus

Abgesehen von den standardmäßigen HTTP-Status, die in Standard-API-Antwortstatus aufgeführt sind, kann die API auch 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 Ein eindeutiger Bezeichner für jede Antwort
Erforderlich.
status True Werte und Aktionen: Erforderlich.
notstarted: Warten Sie die im Retry-After-Header angegebene Zeit ab, und führen Sie dann einen weiteren Aufruf aus, um den Status zu überprüfen.
running: Warten Sie die im Retry-After-Header angegebene Zeit ab, und führen Sie dann einen weiteren Aufruf aus, um den Status zu überprüfen.
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 Das letzte Mal, wenn der Status geändert wurde.
Erforderlich.
resourceLocation False Der URI für die Manifestnutzlast.
Optional.
error False Details zu Fehlern, die im JSON-Format bereitgestellt werden.
Optional.
Enthaltene Attribute:
message: Beschreibung des Fehlers.
code: Der Typ des Fehlers.

Ressourcenspeicherortobjekt

Attribut 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. Bei jeder Änderung der Abrechnungsinformationen wird ein neuer Wert generiert.
partnerTenantId Microsoft Entra-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. Vermeiden Sie es, die Anzahl von Zeilenposten oder Dateigrößen hart zu kodieren, da sie sich ä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 mit den folgenden Details:
name und partitionValue
name Der Name des Blobs.
partitionValue Partition, die die Datei enthält. Die große Partition wird basierend auf bestimmten Kriterien, wie Dateigröße oder Anzahl von Datensätzen, 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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",

        "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"

            }

        \]

    }

}

Herunterladen der Rechnungsabstimmungspositionen aus Azure Blob Storage

Zuerst müssen Sie das SAS-Token (Shared Access Signature) und den Blobspeicherort abrufen. Sie finden diese Details in den Eigenschaften sasToken und rootDirectory der API-Antwort auf die Manifestnutzlast. Verwenden Sie dann das Azure Storage SDK/Tool, um die Blobdatei herunterzuladen und zu entpacken. Sie befindet sich im JSONLines-Format .

Tipp

Schauen Sie sich unbedingt unseren Beispielcodean. Es zeigt, wie Sie die Azure-BLOB-Datei in Ihre lokale Datenbank herunterladen und entzippen.

Standard-API-Antwortstatus

Möglicherweise erhalten Sie die folgenden 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 Die Authentifizierung ist erforderlich, bevor der erste Anruf erfolgt. Authentifizieren mit dem Partner-API-Dienst.
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 ihre Abhängigkeiten können die Anforderung im Moment nicht erfüllen. Versuchen Sie es später noch einmal.
5000 – Keine Daten verfügbar Das System hat keine Daten für die bereitgestellten Eingabeparameter.

Attribute der Rechnungsabrechnungsposition

Informationen zum Vergleichen der Attribute, die von der abgerechneten Rechnungsabstimmungs-API für die Attributsätze „full“ oder „basic“ zurückgegeben werden, finden Sie in dieser Tabelle. Weitere Informationen zu diesen Attributen und ihren Bedeutungen finden Sie unter Verwenden der Abstimmungsdatei.

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

Wichtig

Notieren Sie sich diese Änderungen, wenn Sie von API v1 zu v2 wechseln.

  • Jeder Attributname beginnt jetzt mit einem Großbuchstaben, um die Konsistenz mit der Datei aufrechtzuerhalten und die Lesbarkeit zu verbessern.

Rufen Sie den API-Beispielcode ab

Informationen zur Verwendung dieser API finden Sie unter dem folgenden Link, der C#-Beispielcode enthält.

API-Beispiele für das Abrufen von Abrechnungsabstimmungsdaten aus Partner Center.