Interfejs API uzgadniania faktur rozliczanych w wersji 2 (GA)
Dotyczy: Centrum partnerskie (niedostępne w suwerennej chmurze)
Nasz asynchroniczny interfejs API oferuje szybszy i bardziej zarządzany sposób uzyskiwania dostępu do danych rozliczeń i uzgodnień za pośrednictwem obiektów blob platformy Azure. W przypadku tego interfejsu API nie musisz utrzymywać otwartego połączenia przez wiele godzin ani pętli przez partie 2000 elementów wiersza jednocześnie.
Zoptymalizowaliśmy nasz nowy interfejs API uzgodnień faktur rozliczanych za pomocą klucza valet i asynchronicznych wzorców żą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.
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.
Ten interfejs API można teraz używać tylko dla chmury publicznej/globalnej programu MS Graph. Nie jest jeszcze dostępna dla platformy Azure Government, Azure (Niemcy) ani Azure (Chiny 21Vianet).
Przegląd interfejsu API
Aby pobrać rozliczane nowe dane uzgodnień faktur handlowych asynchronicznie, użyj dwóch punktów końcowych interfejsu API. Proces jest następujący:
Punkt końcowy uzgadniania faktur rozliczanych
Użyj tego interfejsu API, aby pobrać nowe pozycje wierszy rozliczeń faktur rozliczanych w handlu . Interfejs API zwraca stan HTTP 202 i nagłówek lokalizacji zawierający adres URL. Sonduj ten adres URL w regularnych odstępach czasu, aż otrzymasz stan powodzenia z adresem URL manifestu.
Punkt końcowy stanu operacji
Aby uzyskać stan powodzenia, należy regularnie wywoływać ten interfejs API. Jeśli dane nie są gotowe, odpowiedź interfejsu API zawiera nagłówek Ponów próbę po, aby poinformować, jak długo czekać przed ponowną próbą. Po zakończeniu operacji uzyskasz zasób manifestu z folderem magazynu, w którym można pobrać dane użycia. Odpowiedź dzieli pliki na mniejsze elementy pod kątem zoptymalizowanej przepływności i równoległości we/wy.
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.
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. Inne możliwe stany, na podstawie żądań, są wymienione w stanach odpowiedzi interfejsu API w warstwie Standardowa w tym artykule.
| 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 sprawdzić stan żądania, poczekaj na odpowiedź HTTP 200 ze stanem "powodzenie" lub "niepowodzenie". Adres URL manifestu zostanie wyświetlony w atrybucie "resourceLocation", jeśli żądanie zakończy się pomyślnie.
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.
Treść żądania
Nie dotyczy.
Stan odpowiedzi
Oprócz standardowych stanów HTTP wymienionych w stanach odpowiedzi interfejsu API w warstwie Standardowa w tym artykule interfejs API może 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. Opcjonalny. |
| error | Fałsz | Jeśli operacja nie powiedzie się, szczegóły błędu są podane w formacie JSON. Opcjonalny. Uwzględniane są następujące atrybuty: komunikat: szczegółowy opis błędu. code: typ błędu, który wystąpił. |
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. Zmiana informacji rozliczeniowych generuje nową wartość. |
| partnerTenantId | Identyfikator 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: nazwa obiektu blob. partitionValue: partycja zawierająca plik. Duża partycja jest podzielona na wiele plików, z każdym plikiem zawierającym tę samą wartość "partitionValue". |
| name | Nazwa obiektu blob. |
| partitionValue | Partycja zawierająca plik. Duża partycja jest podzielona na wiele plików, z każdym plikiem zawierającym 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 danych uzgodnień faktur z usługi Azure Blob Storage
Pobierz token sygnatury dostępu współdzielonego (SAS) i lokalizację magazynu obiektów blob z właściwości "sasToken" i "rootDirectory" odpowiedzi interfejsu API ładunku manifestu. Zestaw SDK/narzędzie usługi Azure Storage do pobrania i rozpakuj plik obiektu blob. Jest on w formacie JSONLines .
Napiwek
Zapoznaj się z naszym przykładowym kodem , aby pobrać i rozpakować plik obiektu blob platformy Azure do lokalnej bazy danych.
Stany odpowiedzi interfejsu API w warstwie Standardowa
Możesz uzyskać te 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 | Obiekt wywołujący nie jest uwierzytelniany i musisz uwierzytelnić się w usłudze interfejsu API partnera przed wykonaniem pierwszego wywołania. |
| 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 jedna z jego zależności nie może teraz spełnić żądania. Spróbuj ponownie później. |
Atrybuty danych 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ą.
| 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 |
| Unittype | 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 uzyskać wskazówki dotyczące korzystania z interfejsu API, zobacz poniższy link zawierający przykładowy kod w języku C#.
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla