Rozliczane i nienaliczone dzienne interfejs API uzgodnień użycia w wersji 2 (GA)
Dotyczy: Centrum partnerskie (niedostępne w usłudze Azure Government, Azure (Niemcy) lub Azure (Chiny 21Vianet).
Nasze asynchroniczne interfejsy API oferują szybszy i bardziej zarządzany sposób uzyskiwania dostępu do danych rozliczeń i uzgodnień za pośrednictwem obiektów blob platformy Azure. Dzięki tym interfejsom API nie trzeba utrzymywać otwartego połączenia przez wiele godzin ani pętli w partiach 2000 elementów wiersza.
Zoptymalizowaliśmy nasze nowe interfejsy API uzgadniania dziennego użycia przy użyciu klucza valet i asynchronicznych wzorców żądań-odpowiedzi . Korzystając z tych interfejsów API, otrzymujesz token, którego można użyć do uzyskania dostępu do wszystkich atrybutów lub podzestawu danych uzgodnień dziennego użycia.
Uwaga
Nowe interfejsy API nie są hostowane na hoście interfejsu API Centrum partnerskiego. Zamiast tego można je 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 | Microsoft Learn. Aby uzyskać dostęp do tych interfejsów API, zapoznaj się z poniższymi szczegółami.
Możesz używać tych interfejsów API dla chmury publicznej/globalnej programu MS Graph dopiero teraz. Nie są one jeszcze dostępne dla platformy Azure Government, Azure (Niemcy) ani Azure (Chiny 21Vianet).
Uwaga
Jeśli używasz naszej wersji beta, możesz nie zauważyć znaczących zmian w ogólnie dostępnej wersji . Zalecamy porównanie dwóch wersji, aby zrozumieć różnice i aktualizacje.
Ważne
Nowe dzienne użycie handlu nie obejmuje 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
Aby asynchronicznie pobrać nowe elementy wierszy użycia oceniane codziennie w handlu , użyj dwóch punktów końcowych interfejsu API. Proces jest następujący:
Punkt końcowy elementu wiersza użycia
Użyj tego interfejsu API, aby pobrać rozliczane lub nienaliczone dzienne elementy wierszy użycia. W nagłówku lokalizacji otrzymasz stan HTTP 202 i 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 danych uzgodnień.
Sekwencja akcji użytkownika
Aby pobrać nowe elementy wierszy uzgodnień dziennego użycia ocenianego użycia w handlu , wykonaj następujące kroki:
Krok 1. Przesyłanie żądania
Prześlij żądanie POST do punktu końcowego interfejsu API.
Pobieranie nienaliczonych elementów wierszy dziennego użycia
Pobierz nowe pozycje wierszy dziennego użycia dla bieżącego lub ostatniego miesiąca kalendarzowego lub okresu rozliczeniowego, które nie są rozliczane codziennie.
Żądanie interfejsu API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
Accept: application/json
Content-Type: application/json
{
"currencyCode": "USD",
"billingPeriod": "current",
"attributeSet": "basic"
}
Treść żądania
Nagłówki żądań
Aby zażądać nagłówków dla interfejsu API, zobacz Niezawodność i obsługa techniczna.
Odpowiedź interfejsu API
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
W przypadku korzystania z interfejsu API zazwyczaj zwraca on stan HTTP 202. Aby wyświetlić inne możliwe stany na podstawie żądań, zobacz Stan odpowiedzi interfejsu API w warstwie Standardowa.
| Kod | opis |
|---|---|
| 202 — zaakceptowane | Twoje żądanie zostało zaakceptowane. Aby sprawdzić stan żądania, wykonaj zapytanie o adres URL podany w nagłówku lokalizacji. |
Pobieranie rozliczanych elementów wierszy dziennego użycia
Pobierz nowy handel rozliczany codziennie pozycje wierszy użycia dla faktury za zamknięty okres rozliczeniowy.
Żądanie interfejsu API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
Parametry zapytań
Nie dotyczy
Treść żądania
Nagłówek żądania
Nagłówki żądań dla interfejsu API. Aby dowiedzieć się więcej, zobacz niezawodność i obsługa techniczna.
Odpowiedź interfejsu API
Zaakceptowano protokół HTTP/1.1 202
Lokalizacja: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
W przypadku korzystania z interfejsu API zazwyczaj zwraca on stan HTTP 202. Aby uzyskać inne możliwe stany na podstawie żądań, zobacz Statuses (Stany).
| 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". Jeśli żądanie zakończy się pomyślnie, adres URL manifestu zostanie podany w atrybucie "resourceLocation".
Uzyskiwanie stanu operacji
Pobiera stan żądania.
Żądanie interfejsu API
Parametry żądania
| Nazwisko | Uwzględnij w | Wymagania | Type | Opis |
|---|---|---|---|---|
| operationId | Identyfikator URI żądania | Prawda | String | Unikatowy identyfikator sprawdzania stanu żądania. Wymagany. |
Nagłówek żądania
Aby zażądać nagłówków dla interfejsu API, zobacz Niezawodność i obsługa techniczna.
Treść żądania
Nie dotyczy.
Stan odpowiedzi
Oprócz standardowych stanów HTTP interfejs API może zwrócić następujący stan HTTP:
| Kod | opis |
|---|---|
| 410 – Zniknął | Link manifestu jest aktywny tylko przez określony czas trwania ustawiony przez serwer. Po upływie tego czasu należy przesłać nowe żądanie dostępu do manifestu. |
Ł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. Mogą zostać uwzględnione następujące atrybuty: komunikat (wymagany): szczegółowy opis błędu. code (Wymagane): 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 ten sam "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ą podczas przetwarzania danych.
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 elementów wiersza uzgadniania dziennego użycia 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. Użyj zestawu SDK/narzędzia usługi Azure Storage, aby pobrać i rozpakuj plik obiektu blob. Ma format 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
Te stany HTTP mogą zostać odebrane 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ął | Upłynął limit czasu lub upłynął limit czasu łącza manifestu. 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. |
| 5000 — brak dostępnych danych | System nie ma danych dla podanych parametrów wejściowych. |
Porównanie wersji beta i ogólnie dostępnej wersji
Zapoznaj się z tabelą porównawczą, aby zrozumieć różnice między wersjami beta i ogólnie dostępnymi (GA). Jeśli używasz wersji beta, przełączenie do wersji ogólnodostępnej powinno być proste.
| Ważna informacja | Beta | Ogólnie dostępne |
|---|---|---|
| Punkt końcowy hosta interfejsu API | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| Metoda HTTP | POST | POST |
| Punkt końcowy interfejsu API nienaliczonego dziennego użycia | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| Parametry wejściowe dla interfejsu API nienadającego się dziennego użycia ocenianego | Aby określić parametry w żądaniu interfejsu API, uwzględnij je w ciągu zapytania adresu URL żądania. Aby na przykład określić parametr period i currencyCode, dołącz ?period=current¤cyCode=usd go do adresu URL żądania. |
Aby podać dane wejściowe, dołącz obiekt JSON do treści żądania. Obiekt JSON powinien zawierać następujące właściwości: * currencyCode: kod waluty faktury. Na przykład USD. * billingPeriod: okres rozliczeniowy dla faktury. Na przykład bieżący. Oto przykład obiektu JSON, który zawiera właściwości currencyCode i billingPeriod: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Punkt końcowy interfejsu API rozliczanego dziennego użycia | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| Parametry wejściowe dla interfejsu API rozliczanego dziennego użycia | Aby określić parametry w żądaniu interfejsu API, dołącz identyfikator invoiceId w adresie URL żądania. Ponadto można dołączyć opcjonalny parametr fragmentu w ciągu zapytania, aby pobrać pełny zestaw atrybutów. Aby na przykład pobrać pełny zestaw atrybutów, dołącz ?fragment=full go do adresu URL żądania. |
Aby podać dane wejściowe, dołącz obiekt JSON do treści żądania. Obiekt JSON powinien zawierać następujące właściwości: * invoiceId: identyfikator faktury. Na przykład G00012345. * attributeSet: zestaw atrybutów do uwzględnienia w odpowiedzi. Na przykład pełne. Oto przykład obiektu JSON, który zawiera właściwości invoiceId i attributeSet: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| Zasób manifestu | Użyj oddzielnej metody GET /manifests/{id}, aby pobrać zasób manifestu. | Użyj metody GET /operations/{Id}, która zwraca powiązany zasób manifestu w elemencie resourceLocation eliminując potrzebę oddzielnego wywołania metody GET /manifests/{id}. |
| Zmiany schematu manifestu | ||
| "id": Niedostępny | "id": unikatowy identyfikator zasobu manifestu. | |
| "version": Available | "version": zmieniono nazwę na "schemaversion". | |
| "dataFormat": dostępny | "dataFormat": dostępny. | |
| "utcCretedDateTime": Dostępne | "utcCretedDateTime": zmieniono nazwę na "createdDateTime". | |
| "eTag": dostępny | "eTag": dostępne. | |
| "partnerTenantId": Dostępny | "partnerTenantId": Dostępny | |
| "rootFolder": Dostępny | "rootFolder": zmieniono nazwę na "rootDirectory". | |
| "rootFolderSAS": dostępny | "rootFolderSAS": zmieniono nazwę na "sasToken". Teraz udostępnia token i nie zawiera już ścieżki katalogu głównego. Aby uzyskać dostęp do katalogu, zamiast tego użyj właściwości "rootDirectory". | |
| "partitionType": dostępny | "partitionType": dostępny. | |
| "blobCount": dostępny | "blobCount": dostępny. | |
| "sizeInBytes": Dostępny | "sizeInBytes": Niedostępne. | |
| "Obiekty blob": dostępne | "Obiekty blob": dostępne. | |
| "Obiekt blob": dostępny | "Obiekt blob": dostępny. | |
| "name": Dostępne | "name": Dostępne. | |
| "partitionValue": dostępne | "partitionValue": dostępne. |
Atrybuty elementu wiersza uzgadniania dziennego użycia
Aby porównać atrybuty zwracane przez interfejs API uzgadniania dziennego użycia dla zestawów atrybutów "full" lub "basic", zapoznaj się z poniższymi informacjami.
| Atrybut | Pełny | Podstawowy |
|---|---|---|
| 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 |
| 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 |
| 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 |
Ważne
Zanotuj te zmiany podczas przechodzenia do interfejsu API w wersji 2 z wersji 1.
Nazwa każdego atrybutu rozpoczyna się wielkimi literami.
unitOfMeasure jest teraz jednostką. Znaczenie i wartość atrybutu są takie same.
resellerMpnId to teraz identyfikator Tier2MpnId. Znaczenie i wartość atrybutu są takie same.
Nazwa i wartość rateOfPartnerEarnedCredit zostały zmienione na PartnerEarnedCreditPercentage. Nowa nazwa i wartość atrybutu odzwierciedlają wartość procentową zamiast ułamka. Na przykład 0,15 wynosi teraz 15.
rateOfCredit to teraz CreditPercentage. Znaczenie i wartość atrybutu uległy zmianie. Na przykład wartość 1.00 to teraz 100.
Przykładowy kod
Aby dowiedzieć się więcej, zobacz Przykłady interfejsu API Centrum partnerskiego: Pobieranie danych ponownego tworzenia rozliczeń.
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