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 będzie przestarzały. Zamiast tego użyj wersji ogólnie dostępnej. Aby uzyskać więcej informacji, zobacz następujące szczegóły.
Tego interfejsu API można używać tylko do naliczania dziennego użycia do 30 września 2024 r. Zapoznaj się ze szczegółami, aby wybrać odpowiednią wersję interfejsu API i zaplanować z wyprzedzeniem.
- Przejdź do wersji 2 ogólnie dostępnej tak szybko, jak to możliwe. Do tego czasu użyj tego interfejsu API, aby pobrać dzienne elementy wiersza użycia dla nowych faktur handlowych dla okresów rozliczeniowych od września 2022 r.
- Użyj tylko interfejsu API w wersji 2 ogólnie dostępnej od 1 października 2024 r., aby uzyskać dzienne elementy wiersza użycia dla nowych faktur handlowych dla okresów rozliczeniowych od września 2022 r.
Tego interfejsu API można używać tylko w przypadku nienaliczonego dziennego użycia do 30 września 2024 r. Zapoznaj się ze szczegółami, aby wybrać odpowiednią wersję interfejsu API i zaplanować z wyprzedzeniem.
- Przejdź do wersji 2 ogólnie dostępnej tak szybko, jak to możliwe. Do tego czasu użyj tego interfejsu API, aby uzyskać nowe pozycje wierszy dziennego użycia niezbilonego dziennego użycia dla bieżących i poprzednich okresów rozliczeniowych.
- Użyj tylko interfejsu API w wersji 2 (ogólna dostępność) od 1 października 2024 r., aby uzyskać nowe pozycje wiersza dziennego niezbilonego dziennego użycia dla bieżących i poprzednich okresów rozliczeniowych.
Aby uzyskać dostęp do nowych interfejsów API ga w wersji 2, zobacz ten link:
Rozliczane i nienaliczone dzienne interfejs API uzgodnień użycia w wersji 2 (GA)
Uwaga
Możesz pobrać codzienne niezbilone elementy wiersza użycia za pośrednictwem interfejsu API lub portalu Centrum partnerskiego. Udostępnienie danych może potrwać do 24 godzin. Jednak mogą wystąpić dalsze opóźnienia w zależności od lokalizacji i kiedy mierniki zgłaszają użycie.
Czasami może nie być widocznych najnowszych, niezaliczonych danych użycia do momentu dostarczenia rozliczanych danych użycia w poprzednim miesiącu. Jest to wykonywane w celu zapewnienia, że rozliczane dane użycia są dostarczane w uzgodnionym czasie. Po otrzymaniu rozliczanych danych użycia powinno być możliwe pobranie wszystkich zaktualizowanych, niezmierowanych danych użycia od początku miesiąca.
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
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żyliśmy wzorców asynchronicznych żądań i żądań-odpowiedzi , aby zoptymalizować nasze interfejsy API fakturowania i uzgodnień w celu asynchronicznego dostarczania wyników. Odpowiedzi interfejsu API zapewnią 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 informacje:
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. Zwróci 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 będzie 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
Na poniższym diagramie przedstawiono kroki wymagane do pobrania danych uzgodnień.
Sekwencja akcji użytkownika
Wykonaj poniższe 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 będzie mieć wartość "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ć następujący 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ć następujący 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. Dekompresuj plik w celu uzyskania dostępu do danych. |
| utcCreatedDateTime | Czas tworzenia pliku manifestu. |
| Etag | Wersja danych manifestu. Zmiana informacji rozliczeniowych generuje nową wartość elementu eTag. |
| partnerTenantId | Identyfikator dzierżawy partnera. |
| Rootfolder | 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 zostaną podzielone na wiele plików odpowiadających wartościom "partitionValue". Dane są domyślnie partycjonowane według liczby elementów wiersza w pliku. Nie ustawiaj stałej liczby elementów wiersza ani rozmiaru pliku w kodzie, ponieważ mogą one 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": "14f593ad-1edc-474d-aaa0-83abbf9638da",
"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 lub upłynął link manifestu. 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 |
| Typ miernika | 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 |
| Unittype | 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 |
| 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 |
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