Udostępnij za pośrednictwem

API rozliczeń mierzonych na platformie Marketplace

  • Artykuł

Interfejsy API fakturowania według stawek powinny być używane, gdy wydawca tworzy niestandardowe wymiary pomiaru do publikacji oferty w Centrum partnerskim. Integracja z interfejsami API fakturowania zależnego od zużycia jest wymagana, aby emitować zdarzenia użycia w przypadku każdej zakupionej oferty z co najmniej jednym planem i niestandardowymi wymiarami.

Ważny

Musisz śledzić użycie w swoim kodzie i wysyłać zdarzenia użycia tylko do firmy Microsoft dla użycia przekraczającego opłatę podstawową.

Aby uzyskać więcej informacji na temat tworzenia niestandardowych wymiarów pomiaru dla modelu SaaS, zobacz rozliczanie oparte na metrykach SaaS.

Aby uzyskać więcej informacji na temat tworzenia niestandardowych wymiarów pomiaru dla oferty aplikacji platformy Azure z planem aplikacji zarządzanej, zobacz Konfigurowanie szczegółów konfiguracji oferty aplikacji platformy Azure.


Wymuszanie protokołu TLS 1.2 Uwaga

Protokół TLS w wersji 1.2 jest wymuszany jako minimalna wersja komunikacji HTTPS. Upewnij się, że używasz tej wersji protokołu TLS w kodzie. Protokoły TLS w wersji 1.0 i 1.1 są przestarzałe, a próby nawiązania połączenia zostaną odrzucone.

Zdarzenie pojedynczego użycia zgodnie z taryfą

Interfejs API zdarzenia użycia powinien być wywoływany przez wydawcę w celu emitowania zdarzeń użycia względem aktywnego zasobu (subskrybowanego) dla planu zakupionego przez określonego klienta. Zdarzenie użycia jest emitowane oddzielnie dla każdego niestandardowego wymiaru planu zdefiniowanego przez wydawcę podczas publikowania oferty.

Tylko jedno zdarzenie użycia może być emitowane na godzinę każdego dnia kalendarzowego dla każdego zasobu i wymiaru. Jeśli więcej niż jedna jednostka jest zużywana w ciągu godziny, zgromadź wszystkie jednostki zużyte w ciągu godziny, następnie wyemituj je w jednym zdarzeniu. Zdarzenia użycia mogą być emitowane tylko przez ostatnie 24 godziny. Jeśli w dowolnym momencie wyemitujesz zdarzenie użycia w zakresie od 8:00 do 8:59:59 (i zostanie ono zaakceptowane) oraz wyślesz dodatkowe zdarzenie tego samego dnia w tym samym przedziale czasowym, zostanie ono odrzucone jako duplikat.

POST: https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>

Parametry zapytania:

Parametr Zalecenie
ApiVersion Użyj 2018-08-31.

Nagłówki żądań:

Typ zawartości Korzystanie z application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikalna wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Unikatowy token dostępu identyfikujący niezależnego dostawcę oprogramowania, który wykonuje to wywołanie interfejsu API. Format jest "Bearer <access_token>", gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono dla danego przypadku.

Przykład treści żądania:

{
  "resourceId": <guid>, // unique identifier of the resource against which usage is emitted. 
  "quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
  "dimension": "dim1", // custom dimension identifier
  "effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, from now and until 24 hours back
  "planId": "plan1", // id of the plan purchased for the offer
}

W przypadku planów usługi Azure Application Managed Apps resourceId to zarządzana aplikacja resource group Id. Przykładowy skrypt można znaleźć w , korzystając z tokenu tożsamości zarządzanych przez platformę Azure.

W przypadku ofert SaaS resourceId jest identyfikatorem subskrypcji SaaS. Aby uzyskać więcej informacji na temat subskrypcji SaaS, zobacz list subscriptions.

Odpowiedzi

Kod: 200
OK. Emisja użycia została zaakceptowana i zarejestrowana po stronie firmy Microsoft w celu dalszego przetwarzania i rozliczeń.

Przykład ładunku odpowiedzi:

{
  "usageEventId": <guid>, // unique identifier associated with the usage event in Microsoft records
  "status": "Accepted" // this is the only value in case of single usage event
  "messageTime": "2020-01-12T13:19:35.3458658Z", // time in UTC this event was accepted
  "resourceId": <guid>, // unique identifier of the resource against which usage is emitted. For SaaS it's the subscriptionId.
  "quantity": 5.0, // amount of emitted units as recorded by Microsoft
  "dimension": "dim1", // custom dimension identifier
  "effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, as sent by the ISV
  "planId": "plan1", // id of the plan purchased for the offer
}

Kod: 400
Nieprawidłowe żądanie.

  • Brak lub podano nieprawidłowe dane żądania.
  • effectiveStartTime to ponad 24 godziny temu. Zdarzenie wygasło.
  • Subskrypcja SaaS nie jest w statusie Subskrybowane.

Przykład ładunku odpowiedzi:

{
  "message": "One or more errors have occurred.",
  "target": "usageEventRequest",
  "details": [
    {
      "message": "The resourceId is required.",
      "target": "ResourceId",
      "code": "BadArgument"
    }
  ],
  "code": "BadArgument"
}

Kod: 401 Brak autoryzacji. Token autoryzacji jest nieprawidłowy lub wygasł. Żądanie próbuje uzyskać dostęp do subskrypcji SaaS dla oferty opublikowanej przy użyciu innego identyfikatora aplikacji Microsoft Entra z tej, która została użyta do utworzenia tokenu uwierzytelniania.

Kod: 403 Zabronione. Token autoryzacji jest nieprawidłowy, nie został podany lub został dostarczony z niewystarczającymi uprawnieniami. Pamiętaj, aby podać prawidłowy token autoryzacji.

Kod: 409
Konflikt. Zdarzenie użycia zostało już pomyślnie zgłoszone dla określonego identyfikatora zasobu, obowiązującej daty użycia i godziny.

Przykład ładunku odpowiedzi:

{
  "additionalInfo": {
    "acceptedMessage": {
      "usageEventId": "<guid>", //unique identifier associated with the usage event in Microsoft records
      "status": "Duplicate",
      "messageTime": "2020-01-12T13:19:35.3458658Z",
      "resourceId": "<guid>", //unique identifier of the resource against which usage is emitted.
      "quantity": 1.0,
      "dimension": "dim1",
      "effectiveStartTime": "2020-01-12T11:03:28.14Z",
      "planId": "plan1"
    }
  },
  "message": "This usage event already exist.",
  "code": "Conflict"
}

Zdarzenie rozliczenia według zużycia wsadowego

Interfejs API zdarzeń użycia grupowego umożliwia generowanie zdarzeń użycia dla więcej niż jednego zakupionego zasobu jednocześnie. Umożliwia również emitowanie kilku zdarzeń użycia dla tego samego zasobu, o ile są one przeznaczone dla różnych godzin kalendarzowych. Maksymalna liczba zdarzeń w pojedynczej partii wynosi 25.

POST:https://marketplaceapi.microsoft.com/api/batchUsageEvent?api-version=<ApiVersion>

Parametry zapytania:

Parametr Zalecenie
ApiVersion Użyj 2018-08-31.

Nagłówki żądań:

Typ zawartości Korzystanie z application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikalna wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Unikatowy token dostępu identyfikujący niezależnego dostawcę oprogramowania, który wykonuje to wywołanie interfejsu API. Format jest Bearer <access_token>, gdy wartość tokenu jest pobierana przez wydawcę zgodnie z opisem

Notatka

W treści żądania identyfikator zasobu ma różne znaczenie dla aplikacji SaaS i aplikacji zarządzanej platformy Azure emitujących miernik niestandardowy. Identyfikator zasobu aplikacji SaaS to resourceID. Identyfikator zasobu dla planów zarządzanych aplikacji Azure to resourceUri. Aby uzyskać więcej informacji na temat identyfikatorów zasobów, zobacz Rozliczenia taryfowe w Azure Marketplace — wybieranie poprawnego identyfikatora przy przesyłaniu zdarzeń użycia.

W przypadku ofert SaaS resourceId jest identyfikatorem subskrypcji SaaS. Aby uzyskać więcej informacji na temat subskrypcji SaaS, zobacz list subscriptions.

Przykład treści żądania dla aplikacji SaaS:

{
  "request": [ // list of usage events for the same or different resources of the publisher
    { // first event
      "resourceId": "<guid1>", // Unique identifier of the resource against which usage is emitted. 
      "quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
      "dimension": "dim1", //Custom dimension identifier
      "effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
      "planId": "plan1", // id of the plan purchased for the offer
    },
    { // next event
      "resourceId": "<guid2>", 
      "quantity": 39.0, 
      "dimension": "email", 
      "effectiveStartTime": "2018-11-01T23:33:10
      "planId": "gold", // id of the plan purchased for the offer
    }
  ]
}

W przypadku planów usługi Azure Application Managed Apps resourceUri to Zarządzana Aplikacja resourceUsageId. Przykładowy skrypt pobierania można znaleźć w przy użyciu tokenu zarządzanej tożsamości Azure.

Przykład treści żądania dla aplikacji zarządzanych przez aplikację platformy Azure:

{
  "request": [ // list of usage events for the same or different resources of the publisher
    { // first event
      "resourceUri": "<fullyqualifiedname>", // Unique identifier of the resource against which usage is emitted. 
      "quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
      "dimension": "dim1", //Custom dimension identifier
      "effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
      "planId": "plan1", // id of the plan purchased for the offer
    }
  ]
}

Odpowiedzi

Kod: 200
OK. Emisja użycia partii została zaakceptowana i zarejestrowana po stronie firmy Microsoft w celu dalszego przetwarzania i rozliczeń. Lista odpowiedzi jest zwracana z informacją o stanie dla każdego pojedynczego zdarzenia w wsadzie. Należy przejrzeć ładunek odpowiedzi, aby zrozumieć odpowiedzi dla każdego pojedynczego zdarzenia użycia wysyłanego w ramach zdarzenia zbiorczego.

Przykład ładunku odpowiedzi:

{
  "count": 2, // number of records in the response
  "result": [
    { // first response
      "usageEventId": "<guid>", // unique identifier associated with the usage event in Microsoft records
      "status": "Accepted" // see list of possible statuses below,
      "messageTime": "2020-01-12T13:19:35.3458658Z", // Time in UTC this event was accepted by Microsoft,
      "resourceId": "<guid1>", // unique identifier of the resource against which usage is emitted.
      "quantity": 5.0, // amount of emitted units as recorded by Microsoft 
      "dimension": "dim1", // custom dimension identifier
      "effectiveStartTime": "2018-12-01T08:30:14",// time in UTC when the usage event occurred, as sent by the ISV
      "planId": "plan1", // id of the plan purchased for the offer
    },
    { // second response
      "status": "Duplicate",
      "messageTime": "0001-01-01T00:00:00",
      "error": {
        "additionalInfo": {
          "acceptedMessage": {
            "usageEventId": "<guid>",
            "status": "Duplicate",
            "messageTime": "2020-01-12T13:19:35.3458658Z",
            "resourceId": "<guid2>",
            "quantity": 1.0,
            "dimension": "email",
            "effectiveStartTime": "2020-01-12T11:03:28.14Z",
            "planId": "gold"
          }
        },
        "message": "This usage event already exist.",
        "code": "Conflict"
      },
      "resourceId": "<guid2>",
      "quantity": 1.0,
      "dimension": "email",
      "effectiveStartTime": "2020-01-12T11:03:28.14Z",
      "planId": "gold"
    }
  ]
}

Opis kodu stanu, do którego odnosi się odpowiedź interfejsu API BatchUsageEvent.

Kod stanu Opis
Accepted Akceptowane.
Expired Przeterminowane użycie.
Duplicate Podane zduplikowane użycie.
Error Kod błędu.
ResourceNotFound Podany zasób użycia jest nieprawidłowy.
ResourceNotAuthorized Nie masz uprawnień do udostępniania użycia tego zasobu.
ResourceNotActive Zasób jest zawieszony lub nigdy nie został aktywowany.
InvalidDimension Wymiar, dla którego przekazano użycie, jest nieprawidłowy dla tej oferty/planu.
InvalidQuantity Przekazana ilość jest niższa lub równa 0.
BadArgument Brak danych wejściowych lub nieprawidłowo sformułowanych.

Kod: 400
Nieprawidłowe żądanie. Partia zawierała ponad 25 zdarzeń użycia.

Kod: 401 Brak autoryzacji. Token autoryzacji jest nieprawidłowy lub wygasł. Żądanie próbuje uzyskać dostęp do subskrypcji SaaS dla oferty opublikowanej przy użyciu innego identyfikatora aplikacji Microsoft Entra z tej, która została użyta do utworzenia tokenu uwierzytelniania.

Kod: 403 Zabronione. Token autoryzacji jest nieprawidłowy, nie został podany lub został dostarczony z niewystarczającymi uprawnieniami. Pamiętaj, aby podać prawidłowy token autoryzacji.

Rozliczanie na podstawie zużycia pobiera zdarzenia związane z użyciem

Aby uzyskać listę zdarzeń użycia, możesz wywołać interfejs API zdarzeń użycia. Niezależni dostawcy oprogramowania mogą używać tego interfejsu API do wyświetlania zdarzeń użycia, które zostały opublikowane przez określony czas trwania, oraz stanu tych zdarzeń w momencie wywoływania interfejsu API.

GET: https://marketplaceapi.microsoft.com/api/usageEvents

parametry zapytania:

Parametr Zalecenie
ApiVersion Użyj 2018-08-31.
dataRozpoczęciaUżytkowania Data/godzina w formacie ISO8601. Na przykład 2020-12-03T15:00 lub 2020-12-03
UsageEndDate (opcjonalnie) Data/godzina w formacie ISO8601. Wartość domyślna = bieżąca data
offerId (opcjonalnie) Ustawienie domyślne = wszystkie dostępne
planId (opcjonalnie) Ustawienie domyślne = wszystkie dostępne
wymiar (opcjonalnie) Ustawienie domyślne = wszystkie dostępne
azureSubscriptionId (opcjonalnie) Ustawienie domyślne = wszystkie dostępne
reconStatus (opcjonalnie) Ustawienie domyślne = wszystkie dostępne

możliwe wartości reconStatus:

ReconStatus Opis
Złożone Jeszcze nie przetworzone przez usługę PC Analytics
Akceptowane Dopasowane do PC Analytics
Odrzucone Odrzucone w potoku. Skontaktuj się z pomocą techniczną firmy Microsoft, aby zbadać przyczynę.
Niezgodność Ilości w interfejsie MarketplaceAPI i analizie Centrum partnerskiego są obie większe od zera, jednak nie są zgodne.

nagłówki żądania:

Typ zawartości Używanie pliku application/json
x-ms-requestid Unikalna wartość ciągu znaków (najlepiej identyfikator GUID) służąca do śledzenia żądania od klienta. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
autoryzacja Unikatowy token dostępu identyfikujący niezależnego dostawcę oprogramowania, który wykonuje to wywołanie interfejsu API. Format jest Bearer <access_token>, gdy wartość tokenu jest pobierana przez wydawcę. Aby uzyskać więcej informacji, zobacz:

Odpowiedzi

Przykłady ładunku odpowiedzi:

zaakceptowane*

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
   "planName": "Silver",
    "offerId": "mycooloffer",
    "offerName": "My Cool Offer",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Accepted",
    "submittedQuantity": 17.0,
    "processedQuantity": 17.0,
    "submittedCount": 17
  }
]

przesłane

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
    "planName": "",
    "offerId": "mycooloffer",
    "offerName": "",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Submitted",
    "submittedQuantity": 17.0,
    "processedQuantity": 0.0,
    "submittedCount": 17
  }
]

niezgodność

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
    "planName": "Silver",
    "offerId": "mycooloffer",
    "offerName": "My Cool Offer",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Mismatch",
    "submittedQuantity": 17.0,
    "processedQuantity": 16.0,
    "submittedCount": 17
  }
]

odrzucone

[
  {
    "usageDate": "2020-11-30T00:00:00Z",
    "usageResourceId": "11111111-2222-3333-4444-555555555555",
    "dimension": "tokens",
    "planId": "silver",
    "planName": "",
    "offerId": "mycooloffer",
    "offerName": "",
    "offerType": "SaaS",
    "azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
    "reconStatus": "Rejected",
    "submittedQuantity": 17.0,
    "processedQuantity": 0.0,
    "submittedCount": 17
  }
]

kody stanu

Kod: 401 Brak autoryzacji. Token autoryzacji jest nieprawidłowy lub wygasł. Żądanie próbuje uzyskać dostęp do subskrypcji SaaS dla oferty opublikowanej przy użyciu innego identyfikatora aplikacji Microsoft Entra z tej, która została użyta do utworzenia tokenu uwierzytelniania.

Kod: 403 Zabronione. Token autoryzacji jest nieprawidłowy, nie został podany lub został dostarczony z niewystarczającymi uprawnieniami. Pamiętaj, aby podać prawidłowy token autoryzacji.

Najlepsze rozwiązania dotyczące programowania i testowania

Aby zaimplementować integrację z API do pomiaru i przetestować emisję miernika niestandardowego, utwórz plan dla opublikowanej oferty SaaS z zerową ceną za jednostkę i zdefiniowanymi wymiarami niestandardowymi. Opublikuj tę ofertę jako wersję zapoznawcza, aby tylko ograniczeni użytkownicy mogli uzyskiwać dostęp do integracji i testować ją.

Możesz również użyć planu prywatnego dla istniejącej oferty na żywo, aby ograniczyć dostęp do tego planu podczas testowania dla ograniczonej liczby odbiorców.

Uzyskiwanie pomocy technicznej

Postępuj zgodnie z instrukcjami w artykule Wsparcie dla programu komercyjnego marketplace w Centrum partnerskim, aby zrozumieć opcje wsparcia wydawcy i otworzyć zgłoszenie pomocy technicznej w firmie Microsoft.

Powiązana zawartość

Aby uzyskać więcej informacji na temat interfejsów API usługi pomiarów, zobacz Interfejsy API usługi pomiaru użytkowania witryny Marketplace — często zadawane pytania.