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.
Nowy interfejs API uzgodnień faktur rozliczanych za pomocą nowego handlu korzysta z zaawansowanych technik, takich jak klucz valet i asynchroniczne wzorce żądań i odpowiedzi . 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.
Nasz interfejs API używa zoptymalizowanych technik w celu zwiększenia wydajności, dzięki czemu można osiągnąć szybsze wyniki przy mniejszym nakładzie pracy. Przyjmij ten interfejs API, aby uprościć dostęp do danych i zwiększyć ogólną wydajność.
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.
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. Oto usprawniony przewodnik, aby 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
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 wskazującą "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 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. notstarted: Poczekaj na czas określony w nagłówku "Ponów próbę po", a następnie wykonaj kolejne wywołanie, aby sprawdzić stan. running: Zaczekaj na czas określony w nagłówku "Ponów próbę po", 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. Nie ustawiaj stałej liczby elementów wiersza ani rozmiaru pliku w kodzie, ponieważ te wartości mogą ulec zmianie. |
| 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. Partycja zawierająca plik. Duże partycje są podzielone na wiele plików, z których każda zawiera tę samą wartość "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": "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"
}
\]
}
}
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 poniższą tabelą. Aby dowiedzieć się więcej o tych atrybutach, zobacz Using the recon file (Używanie pliku recon).
| 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 |
Przykładowy kod
Aby użyć tego interfejsu API, zobacz następujący link, który zawiera przykładowy kod języka C#.