Interfejsy API rozliczeń mierzonych w witrynie Marketplace

  • Artykuł

Interfejsy API rozliczeń taryfowych powinny być używane, gdy wydawca tworzy niestandardowe wymiary pomiaru, aby oferta została opublikowana w Centrum partnerskim. Integracja z mierzonymi interfejsami API rozliczeń jest wymagana dla każdej zakupionej oferty, która ma co najmniej jeden plan z wymiarami niestandardowymi w celu emitowania zdarzeń użycia.

Ważne

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

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

Aby uzyskać więcej informacji na temat tworzenia niestandardowych wymiarów pomiaru dla oferty aplikacja systemu 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 z użyciem pojedynczego użycia rozliczanego taryfowego

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.

Dla każdej godziny dnia kalendarzowego na zasób i wymiar można emitować tylko jedno zdarzenie użycia. Jeśli więcej niż jedna jednostka jest zużywana w ciągu godziny, zgromadz wszystkie jednostki zużyte w ciągu godziny, a następnie emitują je w jednym zdarzeniu. Zdarzenia użycia mogą być emitowane tylko przez ostatnie 24 godziny. Jeśli w dowolnym momencie emitujesz zdarzenie użycia z zakresu od 8:00 do 8:59:59:59 (i jest akceptowane) i wyślesz dodatkowe zdarzenie tego samego dnia między 8:00 a 8:59:59, zostanie 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 polecenia 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 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.
authorization Unikatowy token dostępu identyfikujący niezależnego dostawcę oprogramowania, który wykonuje to wywołanie interfejsu API. Format jest "Bearer <access_token>" następujący, gdy wartość tokenu jest pobierana przez wydawcę zgodnie z opisem

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 resourceId aplikacja systemu Azure Managed Apps jest to aplikacja resource group Idzarządzana . Przykładowy skrypt służący do pobierania go można znaleźć w artykule przy użyciu tokenu tożsamości zarządzanych przez platformę Azure.

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

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 jest ponad 24 godziny w przeszłości. Zdarzenie wygasło.
  • Subskrypcja SaaS nie jest w stanie 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: 403

Zakazane. Token autoryzacji nie jest podany, jest nieprawidłowy lub wygasł. Lub żądanie próbuje uzyskać dostęp do subskrypcji dla oferty, która została opublikowana przy użyciu innego identyfikatora aplikacji Microsoft Entra z tego, który został użyty do utworzenia tokenu 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 użycia wsadowego taryfowego rozliczeń

Interfejs API zdarzeń użycia wsadowego umożliwia emitowanie 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 polecenia 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 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.
authorization Unikatowy token dostępu identyfikujący niezależnego dostawcę oprogramowania, który wykonuje to wywołanie interfejsu API. Format jest Bearer <access_token> następujący, gdy wartość tokenu jest pobierana przez wydawcę zgodnie z opisem

Uwaga

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 aplikacja systemu Azure Managed Apps to resourceUri. Aby uzyskać więcej informacji na temat identyfikatorów zasobów, zobacz Rozliczenia taryfowe w witrynie Azure Marketplace — wybieranie poprawnego identyfikatora podczas przesyłania zdarzeń użycia.

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

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 resourceUri aplikacja systemu Azure Managed Apps jest to aplikacja resourceUsageIdzarządzana . Przykładowy skrypt służący do pobierania go można znaleźć w artykule przy użyciu tokenu tożsamości zarządzanych przez platformę Azure.

Przykład treści żądania dla aplikacji zarządzanych aplikacja systemu 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 ze stanem dla każdego pojedynczego zdarzenia w partii. Należy wykonać iterację ładunku odpowiedzi, aby zrozumieć odpowiedzi dla każdego pojedynczego zdarzenia użycia wysyłanego w ramach zdarzenia wsadowego.

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órych odwołuje się BatchUsageEvent odpowiedź interfejsu API:

Kod stanu opis
Accepted Akceptowane.
Expired Wygasłe 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: 403
Zakazane. Token autoryzacji nie jest podany, jest nieprawidłowy lub wygasł. Lub żądanie próbuje uzyskać dostęp do subskrypcji dla oferty, która została opublikowana przy użyciu innego identyfikatora aplikacji Microsoft Entra z tego, który został użyty do utworzenia tokenu autoryzacji.

Rozliczenia taryfowe pobierają zdarzenia użycia

Aby uzyskać listę zdarzeń użycia, możesz wywołać interfejs API zdarzeń użycia. Dostawcy oprogramowania mogą używać tego interfejsu API do wyświetlenia zdarzeń użycia, które zostały opublikowane przez określony konfigurowalny czas i 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.
usageStartDate 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
Przesłane Jeszcze nie przetworzone przez usługę PC Analytics
Zaakceptowany Dopasowane do usługi PC Analytics
Odrzucona Odrzucone w potoku. Skontaktuj się z pomocą techniczną firmy Microsoft, aby zbadać przyczynę.
Niezgodność Ilości interfejsu MarketplaceAPI i analizy Centrum partnerskiego nie są jednak zgodne

Nagłówki żądań:

Typ zawartości Używanie pliku application/json
x-ms-requestid Unikatowa wartość ciągu (najlepiej identyfikator GUID) 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> następujący, gdy wartość tokenu jest pobierana przez wydawcę. Aby uzyskać więcej informacji, zobacz:

Odpowiedzi

Przykłady ładunku odpowiedzi:

Akceptowane*

[
  {
    "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łano

[
  {
    "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: 403 Zabronione. Token autoryzacji nie jest podany, jest nieprawidłowy lub wygasł. Lub żądanie próbuje uzyskać dostęp do subskrypcji dla oferty, która została opublikowana przy użyciu innego identyfikatora aplikacji Microsoft Entra z tego, który został użyty do utworzenia tokenu autoryzacji.

Najlepsze rozwiązania dotyczące programowania i testowania

Aby przetestować emisję miernika niestandardowego, zaimplementuj integrację z interfejsem API pomiaru, utwórz plan dla opublikowanej oferty SaaS z wymiarami niestandardowymi zdefiniowanymi w nim z zerową ceną za jednostkę. 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.

Uzyskaj pomoc techniczną

Postępuj zgodnie z instrukcjami w temacie Pomoc techniczna dla programu platformy handlowej w Centrum partnerskim, aby zrozumieć opcje pomocy technicznej wydawcy i otworzyć bilet pomocy technicznej dla firmy Microsoft.

Następne kroki

Aby uzyskać więcej informacji na temat interfejsów API usługi pomiarów, zobacz Marketplace metering service APIs FAQ (Interfejsy API usługi pomiarów w witrynie Marketplace — często zadawane pytania).