Omówienie interfejsu API przesyłania ofert prywatnych

Artykuł
11/10/2023

Oferty prywatne umożliwiają wydawcom i klientom transakcje co najmniej jednego produktu w witrynie Azure Marketplace przez utworzenie cennika powiązanego czasowo przy użyciu dostosowanych terminów. Interfejsy API przesyłania ofert prywatnych umożliwiają wydawcom programowe tworzenie ofert prywatnych dla klientów i/lub partnerów CSP oraz zarządzanie nimi. Ten interfejs API używa identyfikatora Entra firmy Microsoft do uwierzytelniania wywołań z aplikacji lub usługi.

Istnieją trzy główne typy ofert prywatnych dostępnych w Centrum partnerskim i obsługiwane przez interfejs API przesyłania ofert prywatnych:

Prywatna oferta niezależnego dostawcy oprogramowania — określana również jako prywatna oferta klienta w Centrum partnerskim. Jest to niestandardowa transakcja między niezależnego dostawcy oprogramowania a określonym klientem z dostosowanymi terminami i cenami dla określonego produktu w witrynie Azure Marketplace. Dowiedz się więcej o prywatnej ofercie niezależnego dostawcy oprogramowania do klienta.
Prywatna oferta niezależnego dostawcy oprogramowania do partnera CSP — określana również prywatną ofertę CSP Partners w Centrum partnerskim. Ten typ oferty prywatnej umożliwia niezależnemu dostawcy oprogramowania określenie marży czasowej w celu utworzenia ceny hurtowej dla partnera CSP. Dowiedz się więcej o ofercie prywatnej partnera isV to CSP.
Wielopartyjna oferta prywatna (MPO) — niestandardowa transakcja wspólnie skonfigurowana przez niezależnego dostawcę oprogramowania i preferowanego partnera sprzedaży określonego klienta z dostosowanymi warunkami i cenami określonych produktów w witrynie Azure Marketplace. IsV definiuje obniżoną cenę hurtową udostępnioną partnerowi, partner sprzedaży może następnie dodać marżę na podstawie ceny hurtowej, aby uzyskać ostateczną cenę klienta i przedstawi klientowi ofertę akceptacji i zakupu. Akceptacja i zakup mpo jest zgodny z tym samym przepływem co niezależnego dostawcy oprogramowania do ofert prywatnych klientów. Dowiedz się więcej o wieloczęściowej ofercie prywatnej.

Terminologia

Inicjator MPO — MPO to współpraca między isv i partnerem sprzedaży w ramach tej samej niestandardowej transakcji dla określonego klienta, strony, która po raz pierwszy tworzy MPO, jest wyznaczona jako "inicjator" oferty, zazwyczaj niezależnego dostawcy oprogramowania zawartego w MPO. Dla danego MPO może istnieć tylko jeden obiekt źródłowy.
Sprzedawca MPO — partner sprzedaży, który przygotowuje ofertę z ostateczną ceną klienta i przedstawia ofertę klientowi, jest sprzedawcą MPO. Może istnieć tylko jeden sprzedawca dla danego MPO.
Product — pojedyncza jednostka reprezentująca ofertę w witrynie Azure Marketplace. Na stronie listy znajduje się jeden produkt.
Plan — pojedyncza wersja określonego produktu. Istnieje wiele planów dla danego produktu, które reprezentują różne poziomy cen lub terminów.
Zadanie — zadanie utworzone podczas tworzenia żądania w tym interfejsie API. W przypadku korzystania z tego interfejsu API do zarządzania ofertami prywatnymi i ofertami prywatnymi wielopartyjnym zostaje utworzone zadanie w celu ukończenia żądania. Po zakończeniu zadania możesz uzyskać więcej informacji na temat odpowiedniej oferty prywatnej (wieloczęściowej).

Obsługiwane scenariusze

Przygotuj się do korzystania z tego interfejsu API

Przed napisanie kodu w celu wywołania interfejsu API ofert prywatnych upewnij się, że zostały spełnione następujące wymagania wstępne. Te same wymagania wstępne dotyczą wszystkich partnerów publikacji.

Krok 1. Pełne wymagania wstępne dotyczące korzystania z interfejsu API pozyskiwania produktów firmy Microsoft (jednorazowy)

Ty lub Twoja organizacja musi mieć uprawnienia do katalogu Microsoft Entra i administratora globalnego. Jeśli korzystasz już z platformy Microsoft 365 lub innych usług biznesowych, masz już katalog Firmy Microsoft Entra. Jeśli nie, możesz bezpłatnie utworzyć nowy identyfikator Firmy Microsoft Entra w Centrum partnerskim.

Musisz skojarzyć aplikację Microsoft Entra ID z kontem Centrum partnerskiego i uzyskać identyfikator dzierżawy, identyfikator klienta i klucz. Te wartości są potrzebne do uzyskania tokenu dostępu firmy Microsoft Entra, który będzie używany w wywołaniach do prywatnego interfejsu API ofert.

Krok 2. Uzyskiwanie tokenu dostępu firmy Microsoft (za każdym razem)

Przed wywołaniem dowolnej metody w interfejsie API przesyłania sklepu Microsoft Store należy przekazać token dostępu firmy Microsoft Entra do nagłówka autoryzacji każdej metody w interfejsie API. Przed wygaśnięciem tokenu należy użyć 60 minut. Po wygaśnięciu możesz odświeżyć token, aby móc nadal używać go w kolejnych wywołaniach interfejsu API.

Aby uzyskać token dostępu, zobacz Service to Service To Service Calls using Client Credentials to send an HTTP POST to the tenant_id/oauth2/token endpoint (Wywołania usługi do usługi przy użyciu poświadczeń klienta w celu wysłania żądania HTTP POST do punktu końcowego https://login.microsoftonline.com/<tenant_id>/oauth2/tokenu ). Oto przykładowe żądanie:

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://graph.microsoft.com/

Dla wartości tenant_id w identyfikatorze URI POST oraz parametrach client_id i client_secret określ identyfikator dzierżawy, identyfikator klienta i klucz aplikacji pobranej z Centrum partnerskiego w poprzedniej sekcji. Dla parametru zasobu należy określić wartość https://graph.microsoft.com/.

Znajdowanie identyfikatorów produktów, planów i ofert prywatnych

Identyfikator	Gdzie je znaleźć
client_id	Zobacz Kojarzenie aplikacji Microsoft Entra z kontem Centrum partnerskiego.
tenant_id	Zobacz Kojarzenie aplikacji Microsoft Entra z kontem Centrum partnerskiego.
client_secret	Zobacz Kojarzenie aplikacji Microsoft Entra z kontem Centrum partnerskiego.
productId	Zobacz Pobieranie produktów w tym artykule.
identyfikator planu	Zobacz Pobieranie planów dla określonego produktu w tym artykule.
privateofferId	Zobacz Pobieranie ofert prywatnych w tym artykule.

Pobieranie produktów

Oferta prywatna jest oparta na istniejącym produkcie na koncie Centrum partnerskiego. Aby wyświetlić listę produktów skojarzonych z kontem Centrum partnerskiego, użyj tego wywołania interfejsu API:

GET https://graph.microsoft.com/rp/product-ingestion/product?$version=2022-07-01

Odpowiedź jest wyświetlana w następującym formacie przykładowym:

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/product/2022-07-01",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "type": "enum",
      "alias": "string"
    }
  ],
  "@nextLink": "opaque_uri"
}

Pobieranie planów dla określonego produktu

W przypadku produktów zawierających więcej niż jeden plan możesz utworzyć ofertę prywatną na podstawie jednego konkretnego planu. Jeśli tak, potrzebujesz identyfikatora tego planu. Uzyskaj listę planów (takich jak warianty lub jednostki SKU) dla produktu przy użyciu następującego wywołania interfejsu API:

GET https://graph.microsoft.com/rp/product-ingestion/plan?product=<product-id>&$version=2022-07-01

Odpowiedź jest wyświetlana w następującym formacie przykładowym:

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-07-01",
      "product": "string",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "alias": "string"
    }
  ]
}

Pobieranie ofert prywatnych

Aby wyświetlić listę wszystkich ofert prywatnych, w tym wieloczęściowych ofert prywatnych skojarzonych z Twoim kontem, użyj następującego wywołania interfejsu API:

GET https://graph.microsoft.com/rp/product-ingestion/private-offer/query?$version=2023-07-15

Jak używać interfejsu API

Interfejs API oferty prywatnej umożliwia tworzenie ofert prywatnych skojarzonych z produktami i planami oraz zarządzanie nimi na koncie Centrum partnerskiego. Poniżej przedstawiono podsumowanie typowego wzorca wywoływania podczas korzystania z tego interfejsu API.

Krok 1. Wysyłanie żądania

Po utworzeniu wywołania interfejsu API w celu utworzenia, usunięcia, wycofania lub uaktualnienia oferty prywatnej zostanie utworzone nowe zadanie w celu ukończenia żądanego zadania. Odpowiedź interfejsu API zawiera identyfikator zadania skojarzony z zadaniem.

Krok 2. Sonduj stan zadania

Używając identyfikatora jobId z początkowej odpowiedzi interfejsu API, sonduj, aby uzyskać stan zadania. Stan zadania będzie mieć wartość Uruchomiono lub Ukończono. Po zakończeniu zadania wynik będzie mieć wartość Powodzenie lub Niepowodzenie. Aby uniknąć problemów z wydajnością, nie sonduj zadania więcej niż raz na minutę.

jobStatus	opis
Nierozpoczęte	Zadanie nie zostało jeszcze uruchomione; jest to część odpowiedzi w początkowym żądaniu.
Uruchomiono	Zadanie jest nadal uruchomione.
Zakończono	Zadanie zostało ukończone. Zobacz jobResult, aby uzyskać więcej szczegółów.
jobResult	Opis
Oczekująca	Zadanie nie zostało jeszcze ukończone.
Powodzenie	Zadanie zostało ukończone pomyślnie. To zadanie zwraca również identyfikator resourceURI, który odwołuje się do oferty prywatnej powiązanej z zadaniem. Użyj tego identyfikatora resourceURI, aby uzyskać pełne szczegóły oferty prywatnej.
Nie działa	Zadanie nie powiodło się. Zwraca również wszelkie istotne błędy, aby pomóc w ustaleniu przyczyny awarii.

Aby uzyskać więcej informacji, zobacz Zapytanie o stan istniejącego zadania.

Krok 3. Uzyskiwanie informacji z ukończonych zadań

Pomyślne zadanie zwraca identyfikator resourceUri odwołujące się do odpowiedniej oferty prywatnej. Użyj tego identyfikatora URI zasobu, aby uzyskać więcej szczegółów dotyczących oferty prywatnej w przyszłości, takich jak privateofferId.

Zadanie, które zakończyło się niepowodzeniem, zawiera błędy, które zawierają szczegółowe informacje o tym, dlaczego zadanie nie powiodło się i jak rozwiązać problem.

Aby uzyskać więcej informacji, zobacz Uzyskiwanie szczegółów istniejącej oferty prywatnej.

W jaki sposób niezależne dostawcy oprogramowania i partner sprzedaży powinni wspólnie korzystać z interfejsu API dla wieloczęściowej oferty prywatnej

Zarówno niezależne dostawcy oprogramowania, jak i partner sprzedaży mogą używać tych samych interfejsów API do tworzenia danych MPO i zarządzania nimi. Jednak zasoby w mpo, które mogą mieć wpływ na interfejs API, zależą od tego, czy obiekt wywołujący interfejs API jest niezależnego dostawcy oprogramowania (niezależnych dostawców) lub partnera sprzedaży (sprzedawcy) mpO. Ten sam przepływ publikowania niezależnych dostawców oprogramowania/sprzedaży i reguły biznesowe zarządzające Centrum partnerskiego są dublowane w interfejsie API. Oto omówienie:

Operacja interfejsu API	Niezależnego dostawcy oprogramowania (inicjator)	Partner sprzedaży (sprzedawca)
Utworzenie	Docelowi odbiorcy to partner sprzedaży(sprzedawca) po wysłaniu wywołania interfejsu API, klient końcowy nie będzie widzieć oferty prywatnej, dopóki partner sprzedaży nie prześle Edytowalne zasoby: Daty wejścia w życie Zamierzony beneficjent (klient) Sprzedaż partnera do współpracy nad ofertą, ograniczona do 1 na ofertę prywatną Dodatkowe kontakty niezależnego dostawcy oprogramowania do powiadamiania o stanie oferty prywatnej Niestandardowe warunki i postanowienia niezależnego dostawcy oprogramowania Produkty/plany uwzględnione w ofercie prywatnej Czasy trwania kontraktu dla każdego produktu/planu Uwzględnione ilości dla każdego produktu (jeśli dotyczy) Atrybuty planu nieoprowadujące (jeśli dotyczy) Obniżona cena hurtowa dostępna dla partnera sprzedaży w ramach uwzględnionych produktów/planu Uwagi dotyczące sprzedaży niezależnego dostawcy oprogramowania	Docelowi odbiorcy to klient końcowy po wysłaniu wywołania interfejsu API Edytowalne zasoby: Niestandardowe warunki i postanowienia dotyczące sprzedaży partnera Przygotowane przez Korekta klienta (procent narzutu) na podstawie ceny hurtowej niezależnego dostawcy oprogramowania dla każdego produktu/planu uwzględnionego w ofercie prywatnej, określa ostateczną cenę klienta końcowego Dodatkowe kontakty z partnerami sprzedaży, które mają zostać powiadomione o stanie oferty prywatnej Sprzedaż notatek sprzedaży partnerów
Delete	Obsługiwane w przypadku ofert prywatnych w stanie wersji roboczej	Nieobsługiwane
Wycofać	Obsługiwane w przypadku ofert prywatnych opublikowanych przez niezależnego dostawcę oprogramowania, ale nie zostały jeszcze opublikowane przez partnera sprzedaży lub w przypadku wycofania przez partnera sprzedaży	Obsługiwane w przypadku ofert prywatnych opublikowanych i dostępnych dla klientów końcowych, ale nie zostały jeszcze zaakceptowane

Operacja interfejsu API

Niezależnego dostawcy oprogramowania (inicjator)

Partner sprzedaży (sprzedawca)

Utworzenie

Docelowi odbiorcy to partner sprzedaży(sprzedawca) po wysłaniu wywołania interfejsu API, klient końcowy nie będzie widzieć oferty prywatnej, dopóki partner sprzedaży nie prześle

Edytowalne zasoby:

Daty wejścia w życie
Zamierzony beneficjent (klient)
Sprzedaż partnera do współpracy nad ofertą, ograniczona do 1 na ofertę prywatną
Dodatkowe kontakty niezależnego dostawcy oprogramowania do powiadamiania o stanie oferty prywatnej
Niestandardowe warunki i postanowienia niezależnego dostawcy oprogramowania
Produkty/plany uwzględnione w ofercie prywatnej
Czasy trwania kontraktu dla każdego produktu/planu
Uwzględnione ilości dla każdego produktu (jeśli dotyczy)
Atrybuty planu nieoprowadujące (jeśli dotyczy)
Obniżona cena hurtowa dostępna dla partnera sprzedaży w ramach uwzględnionych produktów/planu
Uwagi dotyczące sprzedaży niezależnego dostawcy oprogramowania

Docelowi odbiorcy to klient końcowy po wysłaniu wywołania interfejsu API