Interfejs API uzgadniania faktur w wersji 2 (GA)

Dotyczy: Centrum Partnerskiego (niedostępne w usługach Azure Government lub Azure China 21Vianet)

Omówienie architektury

Nowy asynchroniczny interfejs API oferuje znaczne postępy w sposobie obsługi dostępu do danych rozliczeń i uzgodnień. Takie podejście rozwiązuje problemy związane z tradycyjnymi metodami synchronicznymi, takimi jak utrzymywanie długotrwałych połączeń i przetwarzanie dużych partii danych. Oto najważniejsze korzyści i mechanizmy tego interfejsu API:

Kluczowe składniki

Bezpieczny dostęp za pomocą wzorca klucza valet

Wzorzec klucza valet zapewnia bezpieczny, ograniczony dostęp do danych rozliczeniowych. Podobnie jak klucz valet pozwala komuś jeździć samochodem bez dostępu do bagażnika, ten wzorzec zapewnia szczegółową kontrolę dostępu. Zamiast udostępniać poświadczenia, token sygnatury dostępu współdzielonego (SAS) udziela ograniczonego, ograniczonego czasu dostępu do określonych zasobów. Ten wzorzec zmniejsza ryzyko nieautoryzowanego dostępu, konfigurując dokładne czasy wygaśnięcia i uprawnienia dostępu.

Ulepszona wydajność za pomocą asynchronicznego wzorca żądania-odpowiedzi

Pomyśl o tym jak o zamawianiu w ruchliwej restauracji. Zamiast czekać przy ladzie, otrzymujesz brzęczyk i możesz zająć się innymi rzeczami, podczas gdy zamówienie jest przygotowywane. Gdy dane będą gotowe, system powiadomi Cię.

Asynchroniczny charakter interfejsu API oznacza, że wysyłasz żądanie, a system przetwarza je w tle. To asynchroniczne żądanie-odpowiedź efektywnie wykorzystuje zasoby, zmniejsza obciążenie serwera oraz minimalizuje przekroczenia limitu czasu i awarie, które są typowe dla synchronicznego pobierania danych.

Elastyczność uprawnień dostępu do danych

Tokeny SAS zapewniają elastyczność zarządzania uprawnieniami dostępu do danych. Możesz wygenerować tokeny, które udzielają dostępu do wszystkich atrybutów rozliczanych danych uzgodnień faktur lub ograniczyć dostęp do określonych podzestawów. Ten stopień szczegółowości umożliwia organizacjom dostosowanie dostępu do danych zgodnie z wewnętrznymi zasadami i wymaganiami prawnymi, zwiększenie bezpieczeństwa i zgodności.

Uproszczony przepływ pracy i ulepszone czasy przetwarzania danych

Wzorzec asynchronicznego żądania-odpowiedzi usprawnia przetwarzanie danych, umożliwiając dostęp dynamiczny zamiast stałych partii 2000 elementów wiersza. Takie podejście prowadzi do szybszych wyników i ulepszonych czasów przetwarzania, upraszczając integrację danych rozliczeń i uzgodnień z istniejącymi systemami i przepływami pracy.

Korzyści

1. korzyści z wydajności

   Zamiast utrzymywać długotrwałe połączenia i przetwarzać stałe partie, nowy system umożliwia:

   • Utwórz szybkie żądanie początkowe.
   • Odbieranie bezpiecznego tokenu dostępu.
   • Przetwarzanie danych we własnym tempie.
   • Uzyskaj dostęp do dokładnie tego, czego potrzebujesz, gdy tego potrzebujesz.

2. ulepszenia zabezpieczeń

   Wzorzec klucza valet zaimplementowany za pomocą tokenów SAS zapewnia:

   • Ograniczony czasowo dostęp.
   • Ograniczone uprawnienia.
   • Eliminacja udostępniania lub przechowywania stałych poświadczeń.
   • Szczegółowa kontrola dostępu.

3. zalety architektury

   Wzorzec asynchronicznej odpowiedzi na żądanie działa jak osobisty asystent, który:

   • Przyjmuję twoją prośbę.
   • Obsługuje zadanie w tle.
   • Powiadamia Cię, gdy wszystko jest gotowe.

Wdrażanie zoptymalizowanych interfejsów API w celu zwiększenia wydajności

Korzystanie z tych zoptymalizowanych interfejsów API usprawnia przepływ pracy i zwiększa ogólną wydajność zarządzania danymi. Korzystanie z bezpiecznej kontroli dostępu i wydajnych mechanizmów pobierania pozwala uzyskać lepsze wyniki dzięki mniejszemu nakładowi pracy, co prowadzi do poprawy wydajności operacyjnej.

Podsumowując, nowy asynchroniczny interfejs API umożliwiający uzyskiwanie dostępu do danych rozliczeń i uzgodnień za pośrednictwem obiektów blob platformy Azure to zaawansowane narzędzie. Oferuje bezpieczny, wydajny dostęp do danych finansowych, usprawnianie przepływów pracy, zmniejszanie obciążeń serwera i skracanie czasu przetwarzania, a wszystko to dzięki wysokim bezpieczeństwu i zgodności.

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ć:

1. Zarejestruj aplikację na stronie głównej Microsoft Entra w sekcji Rejestracje aplikacji.
2. 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 fakturowanych faktur

Najpierw użyj tego interfejsu API, aby pobrać pozycje nowych faktur handlowych do uzgodnienia. 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żyj 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 Retry-After, który wskazuje, jak długo czekać przed podjęciem ponownej próby. 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, aby uzyskać dane dotyczące rozliczeń wystawionych faktur:

• prześlij żądanie POST
• sprawdź stan żądania
• Pobieranie elementów wiersza uzgodnień z usługi Azure Blob Storage

Przesyłanie żądania POST

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

Pobierz elementy z wierszy uzgodnień faktur

Pobierz pozycje rozliczeniowe faktury.

Żą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, zapewnisz niezawodność i wsparcie dla swojej aplikacji. Twoja uwaga na szczegóły w tym kroku jest kluczowa 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 kodem statusu HTTP 202. Możesz również napotkać inne statusy w zależności od twoich żądań. Statusy te są wymienione w sekcji Standardowe statusy odpowiedzi interfejsu API.

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

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, zapewniasz niezawodność i wsparcie dla swojej aplikacji. Twoja uwaga 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 Standardowa odpowiedzi interfejsu API, interfejs API może również zwrócić następujący stan HTTP:

Ładunek odpowiedzi

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

Obiekt lokalizacji zasobu

Żą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 elementy wiersza uzgodnień z usługi Azure Blob Storage

Najpierw należy uzyskać token sygnatury dostępu współdzielonego (SAS) i lokalizację magazynu obiektów blob (połącz katalog główny i nazwę obiektu blob). Znajdź te szczegóły w właściwościach sasToken, rootDirectoryi blobs odpowiedzi API ładunku manifestu.

Aby kontynuować, wykonaj następujące kroki:

1. Pobierz plik obiektu blob przy użyciu zestawu SDK/narzędzia usługi Azure Storage .
2. Rozpakuj plik, który znajduje się w formacie JSONLines.

Standardowe statusy odpowiedzi interfejsu API

Z odpowiedzi interfejsu API możesz otrzymać następujące stany HTTP:

Porównanie podstawowych i pełnych atrybutów uzgodnień faktur

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 , jak używać pliku uzgodnień.

Przykładowy kod

Jeśli potrzebujesz pomocy dotyczącej migracji do tego interfejsu API, zapoznaj się z linkiem zawierającym 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