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 obsługuje 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.
Zezwalaj aplikacji na bezpieczny dostęp do danych rozliczeniowych partnerów
Aby zezwolić aplikacji na dostęp do danych rozliczeniowych partnerów, użyj tego linku 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.
Zarejestruj aplikację i przypisz uprawnienie PartnerBilling.Read.All
Możesz przypisać uprawnienie "PartnerBilling.Read.All" przy użyciu witryny Azure Portal lub centrum administracyjnego firmy Microsoft Entra. Wykonując te kroki, możesz upewnić się, że aplikacja ma wymagany dostęp do danych rozliczeniowych partnerów. Oto, jak to zrobić:
- Zarejestruj aplikację na stronie głównej Microsoft Entra w sekcji Rejestracje aplikacji.
- Udziel niezbędnych uprawnień, przechodząc do strony Microsoft Entra App. W sekcji Uprawnienia API wybierz Dodaj uprawnienie, a następnie wybierz zakres PartnerBilling.Read.All.
Dowiedz się więcej o kluczowych punktach końcowych interfejsu API
Aby ułatwić asynchroniczne pobieranie rozliczanych elementów wiersza faktur handlowych , oferujemy dwa kluczowe punkty końcowe interfejsu API. Te punkty końcowe ułatwiają efektywne zarządzanie procesem uzgadniania faktur. Postępuj zgodnie z tym uproszczonym przewodnikiem, aby szybko rozpocząć pracę.
Użyj punktu końcowego do uzgadniania faktur
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.
Używanie punktu końcowego 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 manifest z linkiem do folderu przechowywania do pobrania danych użycia. Odpowiedź segmentuje pliki w celu zwiększenia przepływności i umożliwienia równoległości we/wy.
Przegląd diagramu sekwencji
Oto diagram sekwencji przedstawiający kroki pobierania nowych danych uzgodnień faktur handlowych.
Postępuj zgodnie z sekwencją działań użytkownika, aby pobrać dane uzgodnienia faktur.
Oto sekwencja akcji użytkownika umożliwiająca pobranie danych uzgodnień rozliczonych faktur:
- prześlij żądanie POST
- sprawdź stan żądania
- Pobierz rozliczane elementy wiersza uzgodnień faktur z usługi Azure Blob Storage
Przesyłanie żądania POST
Prześlij żądanie POST do punktu końcowego interfejsu API.
Pobieranie rozliczanych elementów wierszy uzgodnień faktur
Pobierz rozliczane elementy wiersza 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 statusy w zależności od twoich żą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. |
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"
}
\]
}
}
Pobierz pozycje rozliczonych faktur z usługi Azure Blob Storage
Najpierw należy uzyskać token zezwolenia na dostęp (SAS) oraz lokalizację magazynu danych 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 rozpakować 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 blob Azure do lokalnej bazy danych.
Stany odpowiedzi interfejsu API w warstwie Standardowa
Z odpowiedzi interfejsu API możesz otrzymać następujące stany HTTP:
| 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 i użyj pliku uzgodnień.
| 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ść.
Pobieranie przykładowego kodu interfejsu API
Aby użyć tego interfejsu API, zobacz następujący link, który zawiera przykładowy kod języka C#.
Przykłady API do pobierania danych uzgodnień rozliczeń z Centrum Partnerskiego.
Powiązana zawartość
- Azure Storage SDK/narzędzie
- Eksportowanie danych rozliczeniowych partnerów za pomocą interfejsu API programu Microsoft Graph