API v2 (GA) zur Abstimmung der abgerechneten und nicht abgerechneten täglich bewerteten Nutzung

gilt für: Partner Center (nicht verfügbar in Azure Government oder Azure China 21Vianet)

Die Architektur verstehen

Die neue asynchrone API bietet erhebliche Fortschritte bei der Behandlung des Abrechnungs- und Abstimmungsdatenzugriffs. Dieser Ansatz löst Herausforderungen im Zusammenhang mit herkömmlichen synchronen Methoden, z. B. der Aufrechterhaltung langlebiger Verbindungen und der Verarbeitung großer Datenbatches. Hier sind die wichtigsten Vorteile und Mechanismen dieser API:

Wichtigste Komponenten

Sicherer Zugriff mit Valetschlüssel-Muster

Das Valetschlüssel-Muster bietet sicheren, eingeschränkten Zugriff auf Ihre Abrechnungsdaten. Ähnlich wie ein Valet-Schlüssel es jemandem ermöglicht, Ihr Auto ohne Zugriff auf den Trunk zu fahren, stellt dieses Muster eine präzise Zugriffssteuerung sicher. Statt Anmeldeinformationen freizugeben, gewährt ein SAS-Token (Shared Access Signature) begrenzten, zeitlich gebundenen Zugriff auf bestimmte Ressourcen. Dieses Muster reduziert das Risiko eines nicht autorisierten Zugriffs, indem präzise Ablaufzeiten und Zugriffsberechtigungen konfiguriert werden.

Verbesserte Effizienz durch asynchrones Anforderungsantwortmuster

Denken Sie daran, dass sie in einem ausgelasteten Restaurant bestellt wird. Anstatt auf den Schalter zu warten, erhalten Sie einen Buzzer und können andere Dinge tun, während Ihre Bestellung vorbereitet ist. Wenn die Daten bereit sind, benachrichtigt Sie das System.

Die asynchrone Art der API bedeutet, dass Sie eine Anforderung stellen und das System sie im Hintergrund verarbeitet. Diese asynchrone Anforderungsantwort verwendet Ressourcen effizient, reduziert die Serverlast und minimiert sowohl Timeouts als auch Fehler, die oft bei synchronen Datenabrufen auftreten.

Flexibilität bei Datenzugriffsberechtigungen

SAS-Token bieten Flexibilität beim Verwalten von Datenzugriffsberechtigungen. Sie können Token generieren, die Zugriff auf alle Attribute der Rechnungsabrechnungsdaten gewähren oder den Zugriff auf bestimmte Teilmengen beschränken. Diese Granularität ermöglicht Es Organisationen, den Datenzugriff gemäß internen Richtlinien und behördlichen Anforderungen anzupassen, um Sicherheit und Compliance zu verbessern.

Vereinfachter Workflow und verbesserte Datenverarbeitungszeiten

Das asynchrone Anforderungsantwortmuster optimiert die Datenverarbeitung, indem der dynamische Zugriff anstelle von festen Batches von 2.000 Zeilenelementen ermöglicht wird. Dieser Ansatz führt zu schnelleren Ergebnissen und verbesserten Verarbeitungszeiten und vereinfacht die Integration von Abrechnungs- und Abstimmungsdaten in bestehende Systeme und Workflows.

Vorteile

1. Leistungsvorteile

   Anstatt langlebige Verbindungen beizubehalten und feste Batches zu verarbeiten, ermöglicht Ihnen das neue System Folgendes:

   • Erstellen Sie eine schnelle anfängliche Anforderung.
   • Empfangen eines sicheren Zugriffstokens.
   • Verarbeiten Sie Daten in Ihrem eigenen Tempo.
   • Greifen Sie genau darauf zu, was Sie benötigen.

2. Sicherheitsverbesserungen

   Das Valet-Schlüsselmuster, das über SAS-Token implementiert wird, bietet Folgendes:

   • Zeitlich begrenzter Zugriff.
   • Eingeschränkte Berechtigungen.
   • Abschaffung der Weitergabe oder Speicherung von dauerhaften Zugangsdaten.
   • Differenzierte Zugriffssteuerung

3. Architekturvorteile

   Das asynchrone Anforderungsantwortmuster verhält sich wie ein persönlicher Assistent, der:

   • Nimmt Ihre Anforderung an
   • Führt die Aufgabe im Hintergrund aus
   • Benachrichtigt Sie, wenn alles bereit ist.

Einführen optimierter APIs für eine verbesserte Leistung

Durch die Einführung dieser optimierten APIs wird der Workflow optimiert und die Gesamtleistung in der Datenverwaltung verbessert. Mit der sicheren Zugriffssteuerung und effizienten Abrufmechanismen erzielen Sie bessere Ergebnisse mit weniger Aufwand, was zu einer verbesserten Betrieblichen Effizienz führt.

Abschließend ist die neue asynchrone API für den Zugriff auf Abrechnungs- und Abstimmungsdaten über Azure-Blobs ein leistungsfähiges Tool. Es bietet sicheren, effizienten Zugriff auf Finanzdaten, straffende Workflows, Reduzierung der Serverlasten und Verbesserung der Verarbeitungszeiten, alles mit hoher Sicherheit und Compliance.

Sie können diese APIs nur für die öffentliche globale MS Graph-Cloud verwenden. Sie sind noch nicht für Azure Government oder Azure China verfügbar.

Zulassen, dass Ihre App auf Partnerabrechnungsdaten zugreifen kann

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

Zuweisen der Berechtigung PartnerBilling.Read.All

Weisen Sie die Berechtigung "PartnerBilling.Read.All" entweder über das Azure-Portal oder das Microsoft Entra Admin Center zu. Diese Schritte stellen sicher, dass Ihre App über den erforderlichen Zugriff auf die Partnerabrechnungsdaten verfügt.

1. Registrieren Sie Ihre App auf der Microsoft Entra-Homepage unter dem Abschnitt App-Registrierungen.
2. Erteilen Sie die erforderlichen Berechtigungen, indem Sie zur Seite "Microsoft Entra App" 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.

Grundlegendes zu den Unterschieden zwischen beta- und GA-Versionen

Wenn Sie unsere Betaversion verwendet haben, werden Sie den Übergang zur allgemein verfügbaren Version (GA) wahrscheinlich als reibungslos und intuitiv empfinden. Damit Sie die Aktualisierungen und Verbesserungen besser verstehen, empfehlen wir Ihnen, die Beta- und GA-Versionen zu vergleichen. Wenn Sie diese Updates verstehen, können Sie die neuen Features und Verbesserungen maximieren, die in der GA-Version verfügbar sind.

Verstehen und Verwenden der API-Endpunkte

Zum asynchronen Abruf der täglich abgerechneten Nutzungspositionen im Bereich New Commerce bieten wir zwei wichtige API-Endpunkte an. Folgen Sie diesem optimierten Leitfaden, um schnell loszulegen.

Verwenden Sie den Zeilenelement-Endpunkt

Verwenden Sie zunächst diese API, um neue Positionen für die tägliche Nutzung von New Commerce abzurufen. Wenn Sie eine Anforderung stellen, erhalten Sie einen 202 HTTP-Status und einen Location-Header mit einer URL. Rufen Sie diese URL regelmäßig ab, bis Sie einen Erfolgsstatus und eine Manifest-URL erhalten.

Verwenden Sie den Betriebsstatus-Endpunkt

Wenn Sie diese Schritte befolgen, können Sie Ihren Rechnungsabgleichsprozess effizient verwalten.

Überprüfen Sie 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 Sie warten müssen, bevor Sie es erneut versuchen können. Nach Abschluss des Vorgangs erhalten Sie eine Manifestressource mit einem Speicherordnerlink zum Herunterladen der Nutzungsdaten. Die Antwort segmentiert die Dateien, um den Durchsatz zu erhöhen und eine E/A-Parallelität zu ermöglichen.

Überprüfung des Sequenzdiagramms der Abstimmungsdaten

Hier sehen Sie ein Sequenzdiagramm, das die Schritte zum Herunterladen der Abstimmungsdaten zeigt.

Befolgen Sie die Benutzeraktionssequenz

Dies sind die Schritte für den Benutzer, um neue Commerce-Bestellpositionen zur Abstimmung der täglich bewerteten Nutzung abzurufen:

• Senden einer Anforderung
• Überprüfen des Anforderungsstatus
• Herunterladen von Abstimmungspositionen aus Azure Blob Storage

Einreichen einer Anforderung

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

Abrufen der nicht fakturierten täglichen Nennverbrauchspositionen

Rufen Sie die noch nicht abgerechneten New Commerce-Tagesverbrauchspositionen für den aktuellen oder letzten Kalendermonat oder Abrechnungszeitraum ab.

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

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

Die API antwortet normalerweise mit einem HTTP 202 Status. Abhängig von Ihren Anforderungen können Sie auch andere Status erhalten. Diese Status sind im Abschnitt Standard-API-Antwortstatus aufgeführt.

Täglich abgerechnete Verbrauchspositionen abrufen

Rufen Sie täglich neu abgerechnete New Commerce-Verbrauchspositionen für eine Rechnung für den abgeschlossenen Abrechnungszeitraum ab.

API-Anforderung

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

Abfrageparameter

n/v

Anforderungstext

Anforderungsheader

Anforderungsheader für die API. Weitere Informationen finden Sie unter Zuverlässigkeit und Support.

API-Antwort

HTTP/1.1 202 akzeptiert
Standort: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Wenn Sie die API verwenden, wird normalerweise der Status HTTP 202 zurückgegeben. Weitere mögliche Statusmeldungen, die auf Ihren Anforderungen basieren, finden Sie unter Status.

Ü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 bietet einen Endpunkt für den Zugriff auf die erforderlichen Informationen.

Vorgangsstatus abrufen

Ruft den Status einer Anforderung ab.

API-Anforderung

ERHALTEN https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Anforderungsparameter

Anforderungsheader

Informationen zum Anfordern von Headern für die API finden Sie unter Zuverlässigkeit und Support.

Anforderungstext

n/v

Antwortstatus

Neben den Standard-HTTP-Status, die unter Standard-API-Antwortstatus aufgeführt sind, kann die API auch den folgenden HTTP-Status zurückgeben:

Nutzlast der Antwort

Die API-Antwortnutzlast enthält die folgenden Attribute:

Ressourcenspeicherort-Objekt

API-Anforderung

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

API-Antwort

Die Antwort empfiehlt, 10 Sekunden zu warten, bevor Sie es erneut versuchen, wenn Sie Daten verarbeiten.

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 letzten 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 von Abstimmungszeilenelementen aus Azure Blob Storage

Zuerst müssen Sie das SAS-Token (Shared Access Signature) und den Blobspeicherort abrufen (kombinieren Sie das Stammverzeichnis und den Blobnamen). Sie finden diese Details in der sasTokenrootDirectoryManifestnutzlast-API-Antwort und blobs den Eigenschaften der Manifestnutzlast-API.

Führen Sie die folgenden Schritte aus, um fortzufahren:

1. Laden Sie die BLOB-Datei mit dem Azure Storage SDK/Tool herunter.
2. Entzippen Sie die Datei, die sich im JSONLines- Format befindet.

Grundlegendes zu den Standardmäßigen API-Antwortstatus

Möglicherweise erhalten Sie diese HTTP-Status aus der API-Antwort:

Vergleichen von Beta- und GA-Versionen

Schauen Sie sich die folgende Vergleichstabelle an, um die Unterschiede zwischen der Betaversion und den allgemein verfügbaren (GA)-Versionen zu sehen. Wenn Sie derzeit die Betaversion verwenden, dürfte der Übergang zur GA-Version einfach und unkompliziert sein.

Vergleichen Sie die Attribute für den Abgleich zwischen der basic und full täglich abgerechneten Nutzung

Informationen zum Vergleichen der Attribute, die von der abgerechneten oder nicht abgerechneten Nutzungsabstimmungs-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 in der Datei Felder in der Abstimmung zur täglich abgerechneten Nutzung.

Beispielcode

Wenn Sie Unterstützung bei der Migration zu dieser API benötigen, lesen Sie den Link, der C#-Beispielcode enthält.

Partner Center-API-Beispiele: Abrufen von Abrechnungsdaten.

Verwandte Inhalte

• Microsoft Graph-API zum Exportieren von Partnerabrechnungsdaten
• Azure Storage SDK/Tool