Interfejs API uzgadniania faktur rozliczanych w wersji 2 (GA)

Dotyczy: Centrum partnerskie (niedostępne w suwerennej chmurze)

Nasz nowy asynchroniczny interfejs API oferuje szybszy i bardziej wydajny sposób uzyskiwania dostępu do danych rozliczeń i uzgodnień za pośrednictwem obiektów blob platformy Azure. Zamiast utrzymywać połączenie otwarte przez wiele godzin lub przetwarzać partie 2000 wierszy, możesz teraz usprawnić przepływ pracy, zmniejszyć obciążenie serwera i skrócić czas przetwarzania danych.

Nowy interfejs API uzgodnień faktur rozliczanych za pomocą nowego handlu korzysta z zaawansowanych technik, takich jak klucz valet i asynchroniczne wzorce żądań i odpowiedzi . Wzorzec klucza valet umożliwia bezpieczny dostęp do zasobów bez udostępniania poświadczeń, podczas gdy asynchroniczny wzorzec żądania-odpowiedzi umożliwia wydajną komunikację między systemami.

Ten interfejs API udostępnia token sygnatury dostępu współdzielonego (SAS), którego można użyć do uzyskiwania dostępu do wszystkich atrybutów lub podzestawu rozliczanych danych uzgodnień faktur. Ten token zwiększa bezpieczeństwo, udzielając ograniczonego dostępu czasowego i zapewniając elastyczność zarządzania uprawnieniami dostępu do danych.

Dzięki wdrożeniu zoptymalizowanych interfejsów API możesz uzyskać szybsze wyniki dzięki mniejszemu nakładowi pracy, uprościć dostęp do danych i zwiększyć ogólną wydajność. Wykorzystaj te narzędzia, aby usprawnić przepływ pracy i efektywniej zarządzać uprawnieniami.

Uwaga

Nowy interfejs API nie jest hostowany na hoście interfejsu API Centrum partnerskiego. Zamiast tego można go znaleźć w programie MS Graph na stronie Używanie interfejsu API programu Microsoft Graph do eksportowania danych rozliczeń partnerów — Microsoft Graph w wersji 1.0. Aby uzyskać dostęp do tego interfejsu API, zapoznaj się z poniższymi szczegółami.

Ważne

Aby zezwolić aplikacji na dostęp do danych rozliczeniowych partnerów, postępuj zgodnie z tym linkiem i zapoznaj się z podstawami uwierzytelniania i autoryzacji dla programu Microsoft Graph. Ten krok ma kluczowe znaczenie, ponieważ gwarantuje, że aplikacja będzie mogła bezpiecznie uzyskiwać dostęp do niezbędnych danych.

Możesz przypisać uprawnienie "PartnerBilling.Read.All" przy użyciu witryny Azure Portal lub Centrum administracyjnego firmy Entra. Oto, jak to zrobić:

• Zarejestruj aplikację na stronie głównej Microsoft Entra w sekcji Rejestracje aplikacji.
• Aby udzielić niezbędnych uprawnień, przejdź do strony Microsoft Entra App. W sekcji Uprawnienia interfejsu API wybierz pozycję "Dodaj uprawnienie" i wybierz zakres "PartnerBilling.Read.All".

Wykonując te kroki, upewnij się, że aplikacja ma wymagany dostęp do danych rozliczeniowych partnerów.

Przegląd interfejsu API

Aby ułatwić asynchroniczne pobieranie rozliczanych elementów wiersza faktur handlowych , oferujemy dwa kluczowe punkty końcowe interfejsu API. Postępuj zgodnie z tym uproszczonym przewodnikiem, aby szybko i wydajnie rozpocząć pracę.

Punkt końcowy uzgadniania faktur rozliczanych

Najpierw użyj tego interfejsu API, aby pobrać nowe pozycje wierszy rozliczeń faktur rozliczanych w handlu . Po wysłaniu żądania otrzymasz stan HTTP 202 i nagłówek lokalizacji z adresem URL. Regularnie sonduj ten adres URL do momentu uzyskania stanu powodzenia i adresu URL manifestu.

Punkt końcowy stanu operacji

Następnie należy sprawdzić stan operacji, wywołując ten interfejs API w regularnych odstępach czasu. Jeśli dane nie są gotowe, odpowiedź zawiera nagłówek Ponów próbę po zakończeniu wskazujący, jak długo czekać przed ponowną próbą. Po zakończeniu operacji otrzymasz zasób manifestu z linkiem folderu magazynu, aby pobrać dane użycia. Odpowiedź segmentuje pliki w celu zwiększenia przepływności i umożliwienia równoległości we/wy.

Wykonując te kroki, możesz efektywnie zarządzać procesem uzgadniania faktur.

Diagramów sekwencji

Oto diagram sekwencji przedstawiający kroki pobierania nowych danych uzgodnień faktur handlowych.

Sekwencja akcji użytkownika

Aby pobrać rozliczane dane uzgodnień faktur, wykonaj następujące kroki:

Krok 1. Przesyłanie żądania

Prześlij żądanie POST do punktu końcowego interfejsu API.

Pobieranie rozliczanych elementów wierszy uzgodnień faktur

Żądanie interfejsu API

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

Accept: application/json

Content-Type: application/json

{

"invoiceId": "G016907411",

"attributeSet": "basic"

}

Parametry zapytań

Nie dotyczy

Treść żądania

Atrybut	Wymagania	Type	Opis
attributeSet	Fałsz	String	Wybierz pozycję "full" dla wszystkich atrybutów lub "basic" dla ograniczonego zestawu. Jeśli nie zostanie określony, "full" jest wartością domyślną. Sprawdź listę atrybutów w tej sekcji. Opcjonalne.
invoiceId	Prawda	String	Unikatowy identyfikator każdej faktury. Wymagany.

Nagłówki żądań

Zażądaj nagłówków dla interfejsu API, wykonując kroki wymienione w artykule Najlepsze rozwiązania dotyczące korzystania z programu Microsoft Graph. Postępując zgodnie z tymi wytycznymi, upewnij się, że niezawodność i obsługa aplikacji. Uwagę na szczegóły w tym kroku ma kluczowe znaczenie dla bezproblemowej integracji i optymalnej wydajności.

Odpowiedź interfejsu API

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

Interfejs API zwykle odpowiada stanem HTTP 202. Możesz również napotkać inne stany w zależności od żądań. Te stany są wyświetlane w sekcji Stan odpowiedzi interfejsu API w warstwie Standardowa.

Kod	Opis
202 — zaakceptowane	Twoje żądanie zostało zaakceptowane. Aby sprawdzić stan żądania, wykonaj zapytanie o adres URL podany w nagłówku lokalizacji.

Krok 2. Sprawdzanie stanu żądania

Aby śledzić stan żądania, upewnij się, że otrzymasz odpowiedź HTTP 200, która jest standardowym kodem stanu wskazującym "powodzenie" lub "niepowodzenie". W przypadku pomyślnego znalezienia adresu URL manifestu w atrybucie "resourceLocation". Ten atrybut zapewnia punkt końcowy umożliwiający uzyskanie dostępu do wymaganych informacji.

Uzyskiwanie stanu operacji

Pobiera stan żądania.

Żądanie interfejsu API

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

Parametry żądania

Nazwisko	Uwzględnij w	Wymagania	Type	Opis
operationId	Identyfikator URI żądania	Prawda	String	Unikatowy identyfikator do sprawdzania stanu żądania. Wymagany.

Nagłówek żądania

Zażądaj nagłówków dla interfejsu API, wykonując kroki wymienione w artykule Najlepsze rozwiązania dotyczące korzystania z programu Microsoft Graph. Postępując zgodnie z tymi wytycznymi, upewnij się, że niezawodność i obsługa aplikacji. Uwagę na szczegóły w tym kroku ma kluczowe znaczenie dla bezproblemowej integracji i optymalnej wydajności.

Treść żądania

Nie dotyczy.

Stan odpowiedzi

Oprócz standardowych stanów HTTP wymienionych w stanach odpowiedzi interfejsu API w warstwie Standardowa interfejs API może również zwrócić następujący stan HTTP:

Kod	Opis
410 – Zniknął	Link manifestu wygasa po upływie określonego czasu. Aby ponownie uzyskać link manifestu, wyślij nowe żądanie.

Ładunek odpowiedzi

Ładunek odpowiedzi interfejsu API zawiera następujące atrybuty:

Atrybut	Wymagania	Opis
identyfikator	Prawda	Unikatowy identyfikator każdej odpowiedzi Wymagany.
status	Prawda	Wartości i akcje: wymagane. nieuruchomiony: Poczekaj na określony czas podany w nagłówku "Retry-After", a następnie wykonaj kolejne wywołanie, aby sprawdzić stan. uruchomione: Poczekaj na określony czas podany w nagłówku "Retry-After", a następnie wykonaj kolejne wywołanie, aby sprawdzić stan. powodzenie: dane są gotowe. Pobierz ładunek manifestu przy użyciu identyfikatora URI określonego w obszarze resourceLocation. niepowodzenie: operacja nie powiodła się trwale. Uruchom go ponownie.
createdDateTime	Prawda	Czas wysłania żądania. Wymagany.
lastActionDateTime	Prawda	Czas ostatniej zmiany stanu. Wymagany.
resourceLocation	Fałsz	Identyfikator URI ładunku manifestu. Opcjonalne.
error	Fałsz	Szczegółowe informacje o wszelkich błędach podanych w formacie JSON. Opcjonalne. Uwzględnione atrybuty: message: Opis błędu. code: typ błędu.

Obiekt lokalizacji zasobu

Atrybut	Opis
identyfikator	Unikatowy identyfikator manifestu.
schemaVersion	Wersja schematu manifestu.
dataFormat	Format pliku danych rozliczeniowych. compressedJSON: format danych, w którym każdy obiekt blob jest skompresowanym plikiem zawierającym dane w formacie wierszy JSON . Aby pobrać dane z każdego obiektu blob, zdekompresuj je.
createdDateTime	Data i godzina utworzenia pliku manifestu.
eTag	Wersja danych manifestu. Nowa wartość jest generowana za każdym razem, gdy nastąpi zmiana informacji rozliczeniowych.
partnerTenantId	Microsoft Entra ID dzierżawy partnera.
rootDirectory	Katalog główny pliku.
sasToken	Token sygnatury dostępu współdzielonego (sygnatura dostępu współdzielonego), który umożliwia odczytywanie wszystkich plików w katalogu.
partitionType	Dzieli dane na wiele obiektów blob na podstawie atrybutu partitionValue . System dzieli partycje, które przekraczają obsługiwaną liczbę. Domyślnie dane są partycjonowane na podstawie liczby elementów wiersza w pliku. Unikaj zakodowania na sztywno liczby pozycji na liście lub rozmiarów plików, ponieważ mogą się one zmieniać.
BlobCount	Łączna liczba plików dla tego identyfikatora dzierżawy partnera.
obiekty blob	Tablica JSON obiektów "blob", które zawierają szczegóły pliku dla identyfikatora dzierżawy partnera.
Obiekt blob	Obiekt zawierający następujące szczegóły: name and partitionValue
name	Nazwa obiektu blob.
partitionValue	Partycja zawierająca plik. Duża partycja jest dzielona na wiele plików na podstawie określonych kryteriów, takich jak rozmiar pliku lub liczba rekordów, przy czym każdy plik zawiera tę samą "partitionValue".

Żądanie interfejsu API

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

Odpowiedź interfejsu API

Odpowiedź zaleca oczekiwanie na 10 sekund przed ponowną próbą, gdy dane są nadal przetwarzane.

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

Żądanie interfejsu API

(10 sekund po poprzednim żądaniu...)

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

Odpowiedź interfejsu API

Interfejs API zwraca stan "powodzenie" i identyfikator URI dla "resourceLocation".

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"

            }

        \]

    }

}

Krok 3. Pobieranie rozliczanych elementów wierszy uzgodnień faktur z usługi Azure Blob Storage

Najpierw należy uzyskać token sygnatury dostępu współdzielonego (SAS) i lokalizację magazynu obiektów blob. Te szczegóły można znaleźć we właściwościach "sasToken" i "rootDirectory" odpowiedzi interfejsu API ładunku manifestu. Następnie, aby pobrać i rozpakuć plik obiektu blob, użyj zestawu SDK/narzędzia usługi Azure Storage. Jest on w formacie JSONLines .

Napiwek

Pamiętaj, aby zapoznać się z naszym przykładowym kodem. Pokazano w nim, jak pobrać i rozpakować plik obiektu blob platformy Azure do lokalnej bazy danych.

Stany odpowiedzi interfejsu API w warstwie Standardowa

Możesz uzyskać następujące stany HTTP z odpowiedzi interfejsu API:

Kod	Opis
400 — nieprawidłowe żądanie	Brak żądania lub zawiera nieprawidłowe dane. Sprawdź treść odpowiedzi, aby uzyskać szczegółowe informacje o błędzie.
401 — Brak autoryzacji	Uwierzytelnianie jest wymagane przed wykonaniem pierwszego wywołania. Uwierzytelnianie za pomocą usługi interfejsu API partnera.
403 — Zabronione	Nie masz niezbędnej autoryzacji, aby wysłać żądanie.
404 — nie znaleziono	Żądane zasoby nie są dostępne z podanymi parametrami wejściowymi.
410 – Zniknął	Link manifestu nie jest już prawidłowy ani aktywny. Prześlij nowe żądanie.
500 — wewnętrzny błąd serwera	Interfejs API lub jego zależności nie mogą teraz spełnić żądania. Spróbuj ponownie później.
5000 — brak dostępnych danych	System nie ma danych dla podanych parametrów wejściowych.

Atrybuty elementu wiersza uzgadniania faktur rozliczanych

Aby porównać atrybuty zwracane przez interfejs API uzgadniania faktur rozliczanych dla "pełnych" lub "podstawowych" zestawów atrybutów, zapoznaj się z tą tabelą. Aby dowiedzieć się więcej o tych atrybutach i ich znaczeniach, zobacz ten przewodnik .

Atrybut	Pełny	Podstawowy
PartnerId	tak	tak
Identyfikator klienta	tak	tak
CustomerName	tak	tak
Nazwadomeny klienta	tak	nie
CustomerCountry	tak	nie
Numer faktury	tak	tak
Identyfikator mpn	tak	nie
Tier2MpnId	tak	tak
OrderId (Identyfikator zamówienia)	tak	tak
OrderDate (Data zamówienia)	tak	tak
Identyfikator produktu	tak	tak
Identyfikator sku	tak	tak
Identyfikator dostępności	tak	tak
SkuName	tak	nie
ProductName	tak	tak
ChargeType	tak	tak
UnitPrice	tak	tak
Ilość	tak	nie
Suma częściowa	tak	tak
TaxTotal	tak	tak
Łącznie	tak	tak
Waluta	tak	tak
PriceAdjustmentDescription	tak	tak
PublisherName	tak	tak
Identyfikator wydawcy	tak	nie
SubscriptionDescription	tak	nie
SubscriptionId	tak	tak
ChargeStartDate	tak	tak
ChargeEndDate	tak	tak
TerminAndBillingCycle	tak	tak
EffectiveUnitPrice	tak	tak
Typ jednostki	tak	nie
Identyfikator alternatywny	tak	nie
BillableQuantity	tak	tak
RozliczeniaFrequency	tak	nie
PricingCurrency	tak	tak
PCToBCExchangeRate	tak	tak
PCToBCExchangeRateDate	tak	nie
MeterDescription	tak	nie
ReservationOrderId	tak	tak
CreditReasonCode	tak	tak
Data rozpoczęcia subskrypcji	tak	tak
Data subskrypcji	tak	tak
Identyfikator odwołania	tak	tak
ProductQualifiers	tak	nie
Identyfikator promocji	tak	tak
ProductCategory	tak	tak

Ważne

Zanotuj te zmiany podczas przechodzenia z interfejsu API w wersji 1 do wersji 2.

• Każda nazwa atrybutu zaczyna się teraz od wielkie litery, aby zachować spójność z plikiem i zwiększyć czytelność.

Przykładowy kod

Aby użyć tego interfejsu API, zobacz następujący link, który zawiera przykładowy kod języka C#.

Partner-Center-Billing-Recon-Samples: Samples for API for Getting Billing recon data from Partner Center (github.com): Samples for API for Billing recon-data from Partner Center (github.com).