Nowy interfejs API oceniania dziennego użycia w handlu w wersji 2 (beta)
Dotyczy: Centrum partnerskie | Centrum partnerskie obsługiwane przez firmę 21Vianet | Centrum partnerskie dla chmury firmy Microsoft dla instytucji rządowych USA
Użyj tych interfejsów API, aby asynchronicznie pozyskać dane nowego handlu dotyczące dobowego użycia, zarówno naliczone, jak i nienaliczone.
Uwaga
Ten interfejs API nie jest już obsługiwany i nie udostępnia żadnych informacji o użyciu po okresie rozliczeniowym z marca 2025 r. Aby bezproblemowo przełączyć się na nowe interfejsy API, skorzystaj z następującego linku: Interfejs API do uzgadniania dziennego, ocenianego użycia z funkcją rozliczania i nienaliczania w wersji 2 (GA). Dziękujemy za Państwa uwagę i czekamy na Państwa dalsze sukcesy z naszymi interfejsami API rozliczeń.
Uwaga
Dostęp do elementów wierszy dziennego użycia, które nie zostały naliczone, można uzyskać za pośrednictwem interfejsu API lub portalu Centrum partnerskiego. Aby zapewnić dokładne dane, poczekaj do 24 godzin na dostępność. W zależności od lokalizacji i momentu raportowania użycia mierników mogą wystąpić dalsze opóźnienia.
Priorytetem jest terminowe dostarczanie rozliczanych danych dziennego użycia. Od czasu do czasu najnowsze dane dotyczące dziennego użycia, które nie zostały jeszcze zafakturowane, mogą nie być widoczne, dopóki nie będą dostępne dane dotyczące użycia rozliczanego z poprzedniego miesiąca. Po otrzymaniu danych dotyczących rozliczonego użycia możesz pobrać wszystkie zaktualizowane nierozliczone dane o użyciu od początku miesiąca.
Zrozumienie i cierpliwość są doceniane, ponieważ staramy się dostarczać najdokładniejsze i terminowe informacje.
Ważne
Dane dziennego użycia nie obejmują opłat za te produkty:
- Rezerwacja platformy Azure
- Plan oszczędnościowy Azure
- Biuro
- Dynamika
- Microsoft Power Apps
- Oprogramowanie bezterminowe
- Subskrypcja oprogramowania
- Produkt SaaS firmy innej niż Microsoft lub platforma handlowa
Przegląd interfejsu API
Asynchroniczny interfejs API to nowatorska metoda szybkiego uzyskiwania dostępu do danych rozliczeń i uzgodnień w zarządzanych fragmentach. Eliminuje to konieczność utrzymywania otwartego połączenia przez wiele godzin i przetwarzania iteracyjnego milionów transakcji.
Używamy kluczyi asynchronicznych wzorców żądań-odpowiedzi , aby zoptymalizować nasze interfejsy API fakturowania i uzgodnień w celu asynchronicznego dostarczania wyników. Odpowiedzi interfejsu API dostarczają token umożliwiający dostęp do danych dotyczących uzgodnień ze wszystkimi atrybutami lub ich podzestawem.
Dane użycia można pobrać asynchronicznie przy użyciu trzech nowych kroków (punktów końcowych interfejsu API). Aby dowiedzieć się więcej, przeczytaj następujące sekcje:
Punkt końcowy elementu wiersza użycia
Użyj tego interfejsu API, aby uzyskać dostęp do rozliczanych lub nierozliczonych pozycji dotyczących użycia. Zwraca on stan HTTP 202 i nagłówek lokalizacji z adresem URL, który należy sondować w regularnych odstępach czasu, dopóki nie otrzymasz stanu powodzenia z adresem URL manifestu.
Punkt końcowy stanu operacji
Dopóki nie otrzymasz stanu powodzenia, sonduj ten interfejs API w regularnych odstępach czasu. Jeśli żądane dane są niedostępne, odpowiedź interfejsu API zawiera nagłówek Retry-After, który wskazuje, jak długo należy czekać przed wysłaniem kolejnego żądania.
Punkt końcowy manifestu
Ten punkt końcowy udostępnia folder do przechowywania, z którego można pobrać rzeczywiste dane rozliczeniowe. Odpowiedź dzieli pliki lub dzieli je na partycje, aby zoptymalizować przepływność i równoległość we/wy.
Diagram sekwencji
Diagram przedstawia kroki wymagane do pobrania danych uzgodnień.
Sekwencja akcji użytkownika
Wykonaj następujące kroki, aby pobrać dane uzgodnień.
Krok 1. Przesyłanie żądania
Prześlij żądanie POST do punktu końcowego interfejsu API.
Pobierz pozycje nierozliczonego użycia
Pobierz nierozliczone pozycje użycia dla bieżącego lub ostatniego miesiąca kalendarzowego.
Żądanie interfejsu API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
Parametry żądania
| Nazwa/nazwisko | In | Wymagane | Typ | Opis |
|---|---|---|---|---|
| fragment | Zapytanie | Fałsz | String | Wybierz pozycję "full", aby uzyskać pełną odpowiedź lub "basic" dla podzestawu atrybutów. Wartość domyślna to "full". Zobacz listę atrybutów w tym artykule. |
| okres | Zapytanie | Prawda | String | Użyj wartości "current" lub "last", aby uzyskać użycie dla bieżącego lub ostatniego miesiąca kalendarzowego. Wartość "last" jest taka sama jak "previous" w istniejących interfejsach API w wersji V1. |
| kod waluty | Zapytanie | Prawda | String | Kod waluty rozliczeniowej partnera. |
Przestarzałe parametry żądania
Nowsza wersja interfejsu API nie wymaga następujących parametrów identyfikatora URI:
| Nazwa/nazwisko | Opis |
|---|---|
| Dostawca | Nie dotyczy. (Zwraca wszystkie użycie planu platformy Azure i jest równoważne elementowi "onetime" w istniejących interfejsach API wersji V1). |
| czyPartnerZarobiłKredyt | Nie dotyczy. (zwraca wszystkie dane, niezależnie od PEC.) |
| Rozmiar | Nie dotyczy. |
| Przesunięcie | Nie dotyczy. |
| operacjaWyszukiwania | Nie dotyczy. |
Nagłówek żądania
Zobacz listę nagłówków żądań dla interfejsu API w tym artykule.
Treść żądania
Nie dotyczy.
Odpowiedź interfejsu API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
Interfejs API zwraca status HTTP 202. Na podstawie żądania interfejs API może zwrócić inny status standardowy.
| Nazwa/nazwisko | Opis |
|---|---|
| Zaakceptowano 202 | Żądanie jest akceptowane. Sprawdź adres URL nagłówka operacji, aby uzyskać stan żądania. |
Pobierz pozycje rozliczeniowe użycia
Pobierz rozliczane pozycje użycia dla zamkniętego okresu rozliczeniowego.
Żądanie interfejsu API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
Parametry żądania
| Nazwa/nazwisko | In | Wymagane | Typ | Opis |
|---|---|---|---|---|
| identyfikator faktury | Ścieżka | Prawda | String | Numer faktury w Centrum Partnerskim. |
| Fragment | Zapytanie | Fałsz | String | Wybierz pozycję "full", aby uzyskać pełną odpowiedź lub "basic" dla podzestawu atrybutów. Wartość domyślna to "full". Zobacz listę atrybutów w tym artykule. |
Przestarzałe parametry żądania
Nowsza wersja interfejsu API nie wymaga następujących parametrów identyfikatora URI:
| Nazwa/nazwisko | Opis |
|---|---|
| Dostawca | Nie dotyczy. (Zwraca wszystkie użycia planu platformy Azure i jest równoważne 'jednorazowemu' istniejącemu interfejsowi API w wersji V1). |
| czyPartnerZarobiłKredyt | Nie dotyczy. (zwraca wszystkie dane, niezależnie od PEC). |
| Rozmiar | Nie dotyczy. |
| Przesunięcie | Nie dotyczy. |
| operacja wyszukiwania | Nie dotyczy. |
Nagłówek żądania
Zobacz listę nagłówków żądań dla interfejsu API w tym artykule.
Treść żądania
Nie dotyczy.
Odpowiedź interfejsu API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
Interfejs API zwraca "HTTP 202 Zaakceptowano". W zależności od żądania API może zwrócić inny standardowy stan.
| Nazwa/nazwisko | Opis |
|---|---|
| Zaakceptowano 202 | Żądanie jest akceptowane. Sprawdź stan żądania, sondując adres URL nagłówka operation-location. |
Krok 2. Sprawdzanie stanu żądania
Poczekaj na HTTP 200 ze stanem końcowym 'succeeded' lub 'failed'. Adres URL manifestu to "resourceLocation" w przypadku sukcesu.
Uzyskiwanie stanu operacji
Pobiera stan żądania danych uzgodnień.
Żądanie interfejsu API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
Parametry żądania
| Nazwa/nazwisko | In | Wymagane | Typ | Opis |
|---|---|---|---|---|
| operationId | Ścieżka | Prawda | String | Identyfikator operacji. |
Nagłówek żądania
Zobacz listę nagłówków żądań dla interfejsu API w tym artykule.
Treść żądania
Nie dotyczy.
Stan odpowiedzi
Oprócz standardowego statusu HTTP opisanego w tym artykule, interfejs API może zwrócić następujący status HTTP:
| Nazwa/nazwisko | Opis |
|---|---|
| 410 Zniknął | Każde łącze operacyjne jest aktywne przez określony czas trwania, kontrolowany przez serwer. Po upływie czasu klient musi przesłać nowe żądanie. |
Ładunek odpowiedzi
Ładunek odpowiedzi interfejsu API zwraca następujące atrybuty:
| Nazwisko | Opcjonalnie | opis |
|---|---|---|
| czasUtworzenia | fałsz | Czas wykonania żądania |
| lastActionDateTime | fałsz | Czas zmiany stanu. |
| lokalizacja zasobów | prawda | Identyfikator URI ładunku w manifeście. |
| status | fałsz | Możliwe wartości i akcje. |
| Wartość | Akcja klienta |
|---|---|
| nierozpoczęte | Zadzwoń ponownie, aby sprawdzić status po odczekaniu czasu określonego w nagłówku "Retry-After". |
| uruchomiono | Wykonaj kolejne wywołanie, aby sprawdzić stan po oczekiwaniu na czas określony w nagłówku "Ponów próbę po". |
| Powiodło się | Końcowy stan operacji, który wskazuje, że dane są gotowe. Pobierz dane manifestu za pomocą URI określonego w resourceLocation. |
| niepowodzenie | Stan terminalu, który wskazuje trwałą awarię. Uruchom ponownie operację. |
W przypadku atrybutu błędu:
| Nazwisko | Opcjonalnie | opis |
|---|---|---|
| błąd | prawda | Szczegóły błędu podane w formacie JSON, jeśli stan operacji nie powiedzie się. |
| Nazwisko | Opcjonalnie | opis |
|---|---|---|
| wiadomość | fałsz | Opisuje szczegółowo błąd |
| kod | fałsz | Wskazuje rodzaj błędu, który wystąpił |
Żądanie interfejsu API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Odpowiedź interfejsu API
Odpowiedź sugeruje oczekiwanie 10 sekund przed ponowną próbą podczas przetwarzania danych.
HTTP/1.1 200 OK
Retry-After: 10
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime":" 2022-06-1T10-01-05Z",
"status": "running"
}
Żądanie interfejsu API
(10 sekund po wcześniejszym żądaniu)
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Odpowiedź interfejsu API
Interfejs API zwraca stan "powodzenie" i identyfikator URI "resourceLocation".
HTTP/1.1 200 OK
Content-Type: application/json
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-13Z",
"status": "succeeded",
"resourceLocation": "https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/e03e1882-ff59-4c09-882f-74e60b4d7743"
}
Krok 3. Pobieranie ładunku manifestu
Obiekt wywołujący wysyła żądanie GET do adresu URL manifestu, aby dowiedzieć się więcej o tym, gdzie dane uzgodnień są przechowywane w obiektach blob platformy Azure.
Pobieranie manifestu
Pobiera manifest zawierający informacje o lokalizacji platformy Azure, w której przechowywane są dane uzgodnień.
Żądanie interfejsu API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Parametry żądania
| Nazwa/nazwisko | In | Wymagane | Rodzaj | Opis |
|---|---|---|---|---|
| manifestId | Ścieżka | Prawda | String | Identyfikator manifestu. |
Nagłówek żądania
Zobacz [listę nagłówków żądań dla interfejsu API] w tym artykule.
Treść żądania
Nie dotyczy.
Stan odpowiedzi
Oprócz standardowego statusu HTTP interfejs API może zwrócić ten status HTTP:
| Nazwa/nazwisko | Opis |
|---|---|
| 410 Zniknął | Każdy link manifestu jest aktywny przez określoną ilość czasu kontrolowanego przez serwer. Po upływie czasu klient musi przesłać nowe żądanie. |
Ładunek odpowiedzi
Odpowiedź interfejsu API zwraca następujące atrybuty:
| Nazwa/nazwisko | Opis |
|---|---|
| Wersja | Wersja schematu manifestu. |
| format danych | Format pliku danych rozliczeniowych. Możliwe wartości skompresowaneJSONLines: każdy obiekt blob jest skompresowanym plikiem, a dane w pliku są w formacie wierszy JSON. Aby uzyskać dostęp do danych, zdekompresuj plik. |
| utcCreatedDateTime | Czas tworzenia pliku manifestu. |
| eTag | Wersja danych manifestu. Zmiana informacji rozliczeniowych generuje nową wartość elementu eTag. |
| partnerTenantId | Identyfikator dzierżawcy partnera. |
| folder główny | Katalog główny pliku. |
| rootFolderSAS | Token SAS do uzyskania dostępu do pliku. |
| typ partycji | Ta właściwość dzieli dane. Jeśli dana partycja ma więcej niż obsługiwaną liczbę, dane są podzielone na wiele plików odpowiadających wartościom "partitionValue". Domyślnie system partycjonuje dane na podstawie liczby elementów wiersza w pliku. Nie ustawiaj stałej liczby elementów wiersza ani rozmiaru pliku w kodzie, ponieważ reguła partycjonowania może ulec zmianie. |
| LiczbaBlobów | Łączna liczba plików dla tego identyfikatora dzierżawy partnera. |
| rozmiarWBajtach | Łączna liczba bajtów we wszystkich plikach. |
| obiekty blob | Tablica JSON zawierająca obiekty typu "blob" ze szczegółami wszystkich plików dla identyfikatora dzierżawy partnera. |
| Obiekt blob | |
| Nazwisko | Nazwa Blob |
| rozmiarWBajtach | Rozmiar obiektu blob w bajtach. |
| wartość partycji | Partycja zawierająca plik. Duża partycja zostanie podzielona na wiele plików, z których każda ma tę samą wartość "partitionValue". |
Przykład ładunku manifestu
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"rootFolder": "https://{billing.blob.core.windows.net}/{folder_path}",
"rootFolderSAS": "\*\*\*",
"partitionType": "ItemCount",
"blobCount": 3,
"sizeInBytes": 2000,
"blobs": [
{
"name": "{blobName1.json.gz}",
"sizeinBytes": 500,
"partitionValue": "1"
},
{
"name": "{blobName2.json.gz}",
"sizeinBytes": 1000,
"partitionValue": "2"
},
{
"name": "{blobName3.json.gz}",
"sizeinBytes": 500,
"partitionValue": "3"
}
]
}
Krok 4. Pobieranie danych uzgodnień dotyczących użycia z lokalizacji przechowywania
Pobierz token SAS i lokalizację magazynu obiektów blob z właściwości "rootFolderSAS" i "rootFolder" odpowiedzi interfejsu API ładunku manifestu. Użyj zestawu SDK/narzędzia usługi Azure Storage, aby pobrać i rozpakować plik blob. Jest w formacie wierszy JSON.
Nagłówki standardowych żądań API
Wszystkie interfejsy API akceptują następujące nagłówki:
| Nazwa/nazwisko | Wymagane | Typ | Opis |
|---|---|---|---|
| Autoryzacja | Prawda | String | Token elementu nośnego autoryzacji. |
| ms-correlationid | Fałsz | String | Wewnętrzny monitor żądań. Każde żądanie generuje nowy tracker (GUID). |
| ms-cv | Fałsz | String | Wewnętrzny monitor żądań. |
| ms-requestid | Fałsz | String | Identyfikator idempotentności żądania. |
Standardowe statusy odpowiedzi interfejsu API
Poniżej przedstawiono stany HTTP z odpowiedzi interfejsu API:
| Nazwa/nazwisko | Opis |
|---|---|
| 400 Nieprawidłowe żądanie | Brak lub niepoprawne dane. Szczegóły błędu znajdują się w treści odpowiedzi. |
| 401 Brak autoryzacji | Obiekt wywołujący nie jest uwierzytelniany i musi uwierzytelniać się w usłudze interfejsu API partnera przed wykonaniem pierwszego wywołania. |
| 403 Zabronione | Dzwoniący nie jest autoryzowany do składania żądania. |
| 500 Wewnętrzny błąd serwera | Interfejs API lub jeden z jego zależności nie może spełnić żądania. Spróbuj ponownie później. |
| 404 Nie znaleziono | Zasób jest niedostępny z parametrami wejściowymi. |
| 410 Zniknął | Limit czasu łącza manifestu został przekroczony. Prześlij nowe żądanie. |
Atrybuty danych użycia
Odpowiedź interfejsu API dotycząca użycia rozliczonego lub nierozliczonego z parametrem żądania "full" lub "basic" zwraca następujące atrybuty:
| Atrybut | "pełny" | "podstawowy" |
|---|---|---|
| PartnerId | tak | tak |
| PartnerName | tak | tak |
| Identyfikator klienta | tak | tak |
| NazwaKlienta | tak | Tak |
| Nazwadomeny klienta | tak | nie |
| KrajKlienta | tak | nie |
| Identyfikator MPN | tak | nie |
| Tier2MpnId | tak | nie |
| Numer faktury | tak | tak |
| Identyfikator produktu | tak | tak |
| Identyfikator SKU | tak | tak |
| Identyfikator dostępności | tak | nie |
| SkuName | tak | tak |
| ProductName | tak | nie |
| PublisherName | tak | tak |
| Identyfikator wydawcy | tak | nie |
| Opis Subskrypcji | tak | nie |
| SubscriptionId | tak | tak |
| DataRozpoczęciaOpłaty | tak | tak |
| Data zakończenia opłaty | tak | tak |
| Data Użytkowania | tak | tak |
| Typ Licznika | tak | nie |
| Kategoria Licznika | tak | nie |
| MeterId | tak | nie |
| Podkategoria Licznika | tak | nie |
| MeterName | tak | nie |
| MeterRegion | tak | nie |
| Jednostka | tak | tak |
| LokalizacjaZasobu | tak | nie |
| ConsumedService | tak | nie |
| ResourceGroup | tak | nie |
| Identyfikator RESOURCEURI | tak | tak |
| TypOpłaty | tak | tak |
| CenaJednostkowa | tak | tak |
| Ilość | tak | tak |
| Typ jednostki | tak | nie |
| Łączna kwota przed opodatkowaniem | tak | tak |
| WalutaRozliczeniowa | tak | tak |
| Całkowita cena przed opodatkowaniem | tak | tak |
| WalutaCenowa | tak | tak |
| ServiceInfo1 | tak | nie |
| ServiceInfo2 | tak | nie |
| Tagi | tak | nie |
| Dodatkowe Informacje | tak | nie |
| EfektywnaCenaJednostkowa | tak | tak |
| PCToBCExchangeRate | tak | tak |
| PCToBCExchangeRateDate | tak | nie |
| Identyfikator upoważnienia | tak | tak |
| Opis Uprawnienia | tak | nie |
| Procentowy udział kredytu partnera zarobionego | tak | nie |
| Procent Kredytu | tak | tak |
| Typ kredytu | tak | tak |
| BenefitOrderID | tak | tak |
| Identyfikator korzyści | tak | nie |
| TypŚwiadczeń | tak | tak |