Omówienie interfejsu API przesyłania ofert prywatnych
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.
- Oferta prywatna wielopartyjna (MPO) — niestandardowa transakcja skonfigurowana wspólnie przez niezależnego dostawcę oprogramowania i preferowany partner kanału 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 kanału 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 kanału 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 handlowy, 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
- Tworzenie oferty prywatnej dla klienta
- Tworzenie oferty prywatnej dla odsprzedawcy
- Tworzenie wieloczęściowej oferty prywatnej dla klienta
- Usuwanie oferty prywatnej
- Wycofanie oferty prywatnej
- Zapytanie dotyczące listy ofert prywatnych z wieloma częściami
- Wykonywanie zapytań dotyczących listy produktów i planów
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. |
| Ukończone | 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. |
| Niepowodzenie | 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 partnera kanału powinni wspólnie używać interfejsu API dla oferty prywatnej wieloczęściowej
Zarówno niezależne dostawcy oprogramowania, jak i partnera kanału mogą używać tych samych interfejsów API do tworzenia i zarządzania danym mpO. 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 (jednostki źródłowej) lub partnera kanału (sprzedawcy) mpO. Ten sam przepływ publikowania niezależnego dostawcy oprogramowania/partnera kanału 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 kanału (sprzedawca) |
|---|---|---|
| Utworzenie |
|
|
| Delete |
|
|
| Wycofać |
|
|