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
Te interfejsy API umożliwiają asynchronicznie naliczanie opłat za nowy handel i nienaliczone dane dziennego użycia.
Uwaga
Ten interfejs API zostanie wkrótce przestarzały. Aby zapewnić bezproblemowe operacje, zalecamy migrację do wersji ogólnie dostępnej. Poniżej przedstawiono szczegółowe informacje, które należy zaplanować przed nami:
Cel: Pobierz rozliczane dzienne elementy wierszy użycia dla okresów rozliczeniowych od września 2022 r. przed 21 stycznia 2025 r.
Akcja: użyj tego interfejsu API, ale zmigruj go do wersji 2 tak szybko, jak to możliwe.
Cel: od 21 stycznia 2025 r. pobierz rozliczane dzienne elementy wiersza użycia dla okresów rozliczeniowych z września 2022 r.
Akcja: użyj tylko interfejsu API w wersji 2 (ogólna dostępność).
Cel: Pobierz niezbiloną liczbę dziennych elementów wierszy użycia dla bieżących i poprzednich okresów rozliczeniowych przed 21 stycznia 2025 r.
Akcja: użyj tego interfejsu API, ale zmigruj go do wersji 2 tak szybko, jak to możliwe.
Cel: Od 21 stycznia 2025 r. pobierz niezaliczone dzienne elementy wierszy użycia dla bieżących i poprzednich okresów rozliczeniowych.
Akcja: użyj tylko interfejsu API w wersji 2 (ogólna dostępność).
Aby bezproblemowo przejść do nowych interfejsów API, postępuj zgodnie z tym linkiem: Rozliczane i nienaliczone codziennie interfejs API uzgodnień użycia w wersji 2 (GA).
Dziękujemy za twoją uwagę i czekamy na twój ciągły sukces z naszymi interfejsami API rozliczeń.
Uwaga
Dostęp do nienaliczonych elementów wierszy dziennego użycia 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 dane dotyczące użycia rozliczanego w poprzednim miesiącu mogą nie być widoczne dla najnowszych nienaliczonych danych dziennego użycia. Po otrzymaniu rozliczanych danych użycia możesz pobrać wszystkie zaktualizowane niezliczone dane użycia 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
- Office
- Dynamics
- 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ść obsługi otwartego połączenia przez wiele godzin i pętli przez miliony transakcji iteracyjne.
Używamy kluczy i asynchronicznych wzorców żądań-odpowiedzi , aby zoptymalizować nasze interfejsy API fakturowania i uzgodnień w celu asynchronicznego dostarczania wyników. Odpowiedzi interfejsu API zapewniają token umożliwiający dostęp do danych uzgodnień ze wszystkimi atrybutami lub 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 niezaliczonych elementów wiersza 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 Ponów próbę po zakończeniu wskazujący, jak długo należy czekać przed wysłaniem innego żądania.
Punkt końcowy manifestu
Ten punkt końcowy udostępnia folder magazynu, 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ów 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.
Pobieranie nierozliczonych elementów wiersza użycia
Pobierz nierozliczone elementy wiersza 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 | Type | Opis |
|---|---|---|---|---|
| fragment | Query | 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 | Query | 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 1. |
| currencyCode | Query | 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 |
|---|---|
| Provider | Nie dotyczy. (Zwraca wszystkie użycie planu platformy Azure i jest równoważne "jednorazowym" istniejącym interfejsom API w wersji 1). |
| hasPartnerEarnedCredit | Nie dotyczy. (zwraca wszystkie dane, niezależnie od pec). |
| Rozmiar | Nie dotyczy. |
| Przesunięcie | Nie dotyczy. |
| seekOperation | 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 stan HTTP 202. Na podstawie żądania interfejs API może zwrócić inny stan standardowy.
| Nazwa/nazwisko | Opis |
|---|---|
| Zaakceptowano 202 | Żądanie jest akceptowane. Wykonaj zapytanie względem adresu URL nagłówka lokalizacji operacji, aby uzyskać stan żądania. |
Pobieranie rozliczanych elementów wiersza użycia
Pobierz rozliczane pozycje wierszy 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 | Type | Opis |
|---|---|---|---|---|
| invoiceId | Ścieżka | Prawda | String | Numer faktury w Centrum partnerskim. |
| Fragment | Query | 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 |
|---|---|
| Provider | Nie dotyczy. (Zwraca wszystkie użycie planu platformy Azure i jest równoważne "jednorazowym" istniejącym interfejsom API w wersji 1). |
| hasPartnerEarnedCredit | Nie dotyczy. (zwraca wszystkie dane, niezależnie od pec). |
| Rozmiar | Nie dotyczy. |
| Przesunięcie | Nie dotyczy. |
| seekOperation | 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 wartość "Zaakceptowano protokół HTTP 202". Na podstawie interfejsu API żądania może zwrócić inny stan standardowy.
| 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 terminalu zakończonym powodzeniem lub niepowodzeniem. Adres URL manifestu to "resourceLocation" w stanie powodzenia.
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 | Type | 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 stanu HTTP w tym artykule interfejs API może zwrócić ten stan HTTP:
| Nazwa/nazwisko | Opis |
|---|---|
| 410 Zniknął | Każde łącze operacji jest aktywne przez określoną ilość czasu kontrolowanego 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 |
|---|---|---|
| createdDateTime | fałsz | Czas żądania. |
| lastActionDateTime | fałsz | Czas zmiany stanu. |
| resourceLocation | prawda | Identyfikator URI ładunku manifestu. |
| status | fałsz | Możliwe wartości i akcje. |
| Wartość | Akcja klienta |
|---|---|
| niestartowane | Wykonaj inne wywołanie, aby sprawdzić stan po oczekiwaniu na czas określony w nagłówku "Ponów próbę po". |
| uruchomiono | Wykonaj inne wywołanie, aby sprawdzić stan po oczekiwaniu na czas określony w nagłówku "Ponów próbę po". |
| Zakończyła się pomyślnie | Końcowy stan operacji, który wskazuje, że dane są gotowe. Pobierz ładunek manifestu przy użyciu identyfikatora URI określonego w obszarze resourceLocation. |
| niepowodzenie | Stan terminalu, który wskazuje trwałą awarię. Uruchom ponownie operację. |
W przypadku atrybutu błędu:
| Nazwisko | Opcjonalnie | opis |
|---|---|---|
| error | 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 |
| code | 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 z informacjami o lokalizacji magazynu platformy Azure danych uzgodnień.
Żądanie interfejsu API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Parametry żądania
| Nazwa/nazwisko | In | Wymagane | Type | 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 stanu HTTP interfejs API może zwrócić ten stan 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. |
| dataFormat | 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żawy partnera. |
| folder główny | Katalog główny pliku. |
| rootFolderSAS | Token SYGNATURy dostępu współdzielonego do uzyskiwania dostępu do pliku. |
| partitionType | 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. |
| BlobCount | Łączna liczba plików dla tego identyfikatora dzierżawy partnera. |
| sizeInBytes | Łączna liczba bajtów we wszystkich plikach. |
| obiekty blob | Tablica JSON obiektów "blob" ze szczegółami wszystkich plików identyfikatora dzierżawy partnera. |
| Obiekt blob | |
| Nazwisko | Nazwa obiektu blob. |
| sizeInBytes | Rozmiar obiektu blob w bajtach. |
| partitionValue | Partycja zawierająca plik. Duża partycja zostanie podzielona na wiele plików, z których każda ma tę samą wartość "partitionValue". |
Przykładowy ładunek 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ń użycia z lokalizacji magazynu
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 rozpakuj plik obiektu blob. Jest w formacie wierszy JSON.
Nagłówki żądań interfejsu API w warstwie Standardowa
Wszystkie interfejsy API akceptują następujące nagłówki:
| Nazwa/nazwisko | Wymagane | Type | 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. |
Stany odpowiedzi interfejsu API w warstwie Standardowa
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 | Obiekt wywołujący nie ma autoryzacji 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ął | Upłynął limit czasu łącza manifestu lub upłynął. Prześlij nowe żądanie. |
Atrybuty danych użycia
Odpowiedź interfejsu API użycia rozliczanego lub niezaliczonego z parametrem żądania "full" lub "basic" zwraca następujące atrybuty:
| Atrybut | "full" | "basic" |
|---|---|---|
| PartnerId | tak | tak |
| PartnerName | tak | tak |
| Identyfikator klienta | tak | tak |
| CustomerName | tak | Tak |
| Nazwadomeny klienta | tak | nie |
| CustomerCountry | 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 |
| SubscriptionDescription | tak | nie |
| SubscriptionId | tak | tak |
| ChargeStartDate | tak | tak |
| ChargeEndDate | tak | tak |
| UsageDate | tak | tak |
| MeterType | tak | nie |
| MeterCategory | tak | nie |
| MeterId | tak | nie |
| MeterSubCategory | tak | nie |
| MeterName | tak | nie |
| MeterRegion | tak | nie |
| Jednostka | tak | tak |
| ResourceLocation | tak | nie |
| ConsumedService | tak | nie |
| ResourceGroup | tak | nie |
| Identyfikator RESOURCEURI | tak | tak |
| ChargeType | tak | tak |
| UnitPrice | tak | tak |
| Ilość | tak | tak |
| Typ jednostki | tak | nie |
| BillingPreTaxTotal | tak | tak |
| BillingCurrency | tak | tak |
| PricingPreTaxTotal | tak | tak |
| PricingCurrency | tak | tak |
| ServiceInfo1 | tak | nie |
| ServiceInfo2 | tak | nie |
| Tagi | tak | nie |
| AdditionalInfo | tak | nie |
| EffectiveUnitPrice | tak | tak |
| PCToBCExchangeRate | tak | tak |
| PCToBCExchangeRateDate | tak | nie |
| Identyfikator upoważnienia | tak | tak |
| EntitlementDescription | tak | nie |
| PartnerEarnedCreditPercentage | tak | nie |
| CreditPercentage | tak | tak |
| Typ środków | tak | tak |
| BenefitOrderID | tak | tak |
| Identyfikator korzyści | tak | nie |
| BenefitType | tak | tak |