Interfejs API pozyskiwania produktów dla komercyjnej platformy handlowej
Interfejs API pozyskiwania produktów to zmodernizowany interfejs API, który łączy wszystkie istniejące interfejsy API przesyłania we wszystkich produktach platformy handlowej. Interfejs API umożliwia tworzenie i publikowanie zasobów skojarzonych z produktami i planami oraz zarządzanie nimi na koncie Centrum partnerskiego. Używa on wzorca deklaratywnego do przesyłania żądań, w których wskazywany jest żądany stan, w przeciwieństwie do określania poszczególnych kroków w celu osiągnięcia żądanego stanu.
Ten artykuł zawiera wskazówki dotyczące rozpoczynania pracy z interfejsami API dla dowolnego typu oferty na platformie handlowej. Interfejs API pozyskiwania produktów jest obecnie obsługiwany dla typów ofert SaaS, maszyn wirtualnych, ofert prywatnych i kontenerów oraz jest dostępny w wersji zapoznawczej. Aby uzyskać wskazówki dotyczące oferty, zapoznaj się ze wskazówkami dotyczącymi interfejsu API dla typu oferty.
Ważne
Usługa Azure Active Directory (Azure AD) Graph jest przestarzała od 30 czerwca 2023 r. W przyszłości nie dokonujemy dalszych inwestycji w usłudze Azure AD Graph. Interfejsy API programu Graph usługi Azure AD nie mają umowy SLA ani zobowiązania do konserwacji poza poprawkami związanymi z zabezpieczeniami. Inwestycje w nowe funkcje i funkcje zostaną dokonane tylko w programie Microsoft Graph.
Wycofamy program Azure AD Graph w krokach przyrostowych, aby mieć wystarczający czas na migrację aplikacji do interfejsów API programu Microsoft Graph. W późniejszym terminie ogłosimy, że zablokujemy tworzenie nowych aplikacji przy użyciu usługi Azure AD Graph.
Aby dowiedzieć się więcej, zobacz Ważne: wycofanie programu Azure AD Graph i wycofanie modułu powershell.
Wprowadzenie
Dostęp do interfejsu API pozyskiwania produktów można uzyskać przy użyciu interfejsu API MSGraph pod nazwą obciążenia "pozyskiwanie produktów". Podstawowy adres URL to https://graph.microsoft.com/rp/product-ingestion.
Aby użyć interfejsu API pozyskiwania produktów, należy najpierw uzyskać następujące elementy:
- Identyfikator Entra firmy Microsoft i upewnij się, że masz uprawnienia administratora globalnego dla katalogu
- Aplikacja Firmy Microsoft Entra
- Token dostępu firmy Microsoft Entra
Krok 1. Ukończenie wymagań wstępnych
Przed rozpoczęciem pisania kodu w celu wywołania interfejsu API pozyskiwania produktów upewnij się, że zostały spełnione następujące wymagania wstępne.
- Użytkownik (lub twoja organizacja) musi mieć katalog Firmy Microsoft Entra i musisz mieć uprawnienia administratora globalnego dla katalogu. Jeśli korzystasz już z platformy Microsoft 365 lub innych usług biznesowych, masz już katalog Firmy Microsoft Entra. W przeciwnym razie możesz utworzyć nowy identyfikator Entra firmy Microsoft w Centrum partnerskim bez dodatkowych opłat.
- Musisz skojarzyć aplikację Microsoft Entra z kontem Centrum partnerskiego i uzyskać identyfikator dzierżawy, identyfikator klienta i klucz. Będą one potrzebne do uzyskania tokenu dostępu firmy Microsoft Entra, który będzie używany w wywołaniach interfejsu API przesyłania do sklepu Microsoft Store.
Kojarzenie aplikacji Microsoft Entra z kontem Centrum partnerskiego
Aby korzystać z interfejsu API pozyskiwania produktów, musisz skojarzyć aplikację Firmy Microsoft Entra z kontem Centrum partnerskiego, pobrać identyfikator dzierżawy i identyfikator klienta dla aplikacji i wygenerować klucz. Aplikacja Microsoft Entra reprezentuje aplikację lub usługę, z której chcesz wywołać interfejs API pozyskiwania produktów. Aby uzyskać token dostępu firmy Microsoft Entra do przekazania do interfejsu API, potrzebny jest identyfikator dzierżawy, identyfikator klienta i klucz.
Uwaga
To zadanie trzeba wykonać tylko raz. Po utworzeniu identyfikatora dzierżawy, identyfikatora klienta i klucza możesz użyć ich ponownie w dowolnym momencie, gdy musisz utworzyć nowy token dostępu firmy Microsoft Entra.
- W Centrum partnerskim skojarz konto Centrum partnerskie organizacji z katalogiem Microsoft Entra w organizacji.
- Na stronie Użytkownicy w sekcji Ustawienia konta Centrum partnerskiego dodaj aplikację Microsoft Entra reprezentującą aplikację lub usługę, której będziesz używać do uzyskiwania dostępu do przesyłania danych dla konta Centrum partnerskiego. Upewnij się, że przypiszesz tę aplikację rolę Menedżer . Jeśli aplikacja jeszcze nie istnieje w katalogu Microsoft Entra, utwórz nową aplikację Microsoft Entra w Centrum partnerskim. Centrum partnerskie utworzy dwa typy wpisów dla aplikacji jako jednostkę usługi, a drugi jako typ aplikacji Microsoft Entra.
- Wróć do strony Użytkownicy , wybierz nazwę aplikacji Microsoft Entra, aby przejść do ustawień aplikacji, a następnie skopiować wartości Identyfikator dzierżawy i Identyfikator klienta.
- Wybierz pozycję Dodaj nowy klucz. Na poniższym ekranie skopiuj wartość Klucz . Po opuszczeniu tej strony nie będzie można ponownie uzyskać dostępu do tych informacji. Aby uzyskać więcej informacji, zobacz Zarządzanie kluczami dla aplikacji Firmy Microsoft Entra.
Krok 2. Uzyskiwanie tokenu dostępu firmy Microsoft
Aby wywołać dowolną metodę w interfejsie API pozyskiwania produktów, należy najpierw uzyskać token dostępu firmy Microsoft Entra, aby przekazać go do nagłówka Autoryzacja każdej metody w interfejsie API. Token dostępu wygasa 60 minut po wystawieniu. Następnie możesz go odświeżyć, aby można było go używać w przyszłych wywołaniach interfejsu API.
Aby uzyskać token dostępu, postępuj zgodnie z instrukcjami w temacie Service to Service Calls Using Client Credentials (Wywołania usługi do usługi przy użyciu poświadczeń klienta), aby wysłać element HTTP POST do punktu końcowego https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token . Oto przykładowe żądanie:
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded;
grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&scope=https://graph.microsoft.com/.default
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 zakresu należy określić wartość https://graph.microsoft.com/.default.
Pojęcia
Przed rozpoczęciem należy zrozumieć niektóre podstawowe pojęcia.
Zasoby
Interfejs API jest ustrukturyzowany wokół typów zasobów, gdzie każdy typ jest opisywany przy użyciu dedykowanej definicji schematu, do której odwołuje się właściwość "$schema". Schemat składa się z właściwości konfiguracji tego zasobu. Zasoby są podstawowe w tworzeniu i aktualizowaniu konfiguracji różnych aspektów danego produktu. Aby uzyskać pełną listę typów zasobów i ich schematów, zobacz dokumentację interfejsu API zasobów.
Trwały identyfikator
Trwały identyfikator to system wygenerowany identyfikator globalny używany do unikatowego identyfikowania dowolnego zasobu. Każdy zasób ma skojarzoną właściwość "ID", która w połączeniu z nazwą typu zasobu tworzy trwały identyfikator zasobu. Trwały identyfikator jest używany podczas odwoływania się do zasobów w celu pobrania lub zmodyfikowania.
Format:
\<resource-type>/\<id>
Przykład:
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"id": "product/12345678-abcd-efgh-1234-12345678901", // durable ID
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService", // Product types that can be specified include azureContainer, azureVirtualMachine, softwareAsAService
"alias": "Contoso Image Resizing Service"
}
Identyfikator zewnętrzny
Identyfikator zewnętrzny to inny unikatowy identyfikator, który może służyć do odwołowania się do określonych produktów lub planów. Jest to alternatywny sposób odwołowania się do tych zasobów zamiast używania trwałego identyfikatora. Identyfikator zewnętrzny produktu przekłada się na jego "offerID", a zewnętrzny identyfikator planu przekłada się na jego "planID", zgodnie z definicją podczas tworzenia w ramach właściwości "identity".
Przykład:
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/12345678-abcd-efgh-1234-12345678901/4e0bfefa-b993-4b79-a426-871c3bf236a5",
"identity": {
"externalID": "gold-annual"
},
"azureRegions": [
"azureGlobal"
],
"alias": "Gold - Annual payment",
"product": "product/12345678-abcd-efgh-1234-12345678901",
}
Metody interfejsu API
Istnieją cztery interfejsy API zarządzania, które mogą służyć do wykonywania różnych akcji, takich jak wykonywanie zapytań dotyczących istniejących zasobów, aktualizowanie konfiguracji i sprawdzanie stanu żądania.
Uwaga
Wszystkie żądania wymagają ustawienia wersji schematu ($version parametru zapytania) w ramach odpowiedzi.
| Typ interfejsu API | Opis | Metoda i ścieżka HTTP |
|---|---|---|
| Zapytanie | Pobiera istniejące zasoby według: -Method 1: "resource-tree" typ zasobu -Method 2: durable-id -Method 3: query string parameters (Metoda 3: parametry ciągu zapytania) |
-Metoda 1: GET resource-tree/<product-durableID>-Metoda 2: GET <resource-durableID>-Metoda 3: GET <resourceType>?<query parameters> |
| Konfigurowanie przesyłania | Przesyła żądania utworzenia lub zaktualizowania co najmniej jednego zasobu. Po pomyślnym przetworzeniu zwracany jest identyfikator zadania, którego można użyć do pobrania stanu żądania. Ten typ interfejsu API może służyć do aktualizowania stanu wersji roboczej i publikowania zmian, synchronizowania prywatnych odbiorców i modyfikowania stanu cyklu życia zasobu. | POST configure |
| Konfigurowanie stanu | Pobiera stan oczekującego żądania za pośrednictwem identyfikatora zadania. | GET configure/<jobID>/status |
| Konfigurowanie szczegółów stanu | Pobiera szczegółowe podsumowanie ukończonego żądania, w tym zaktualizowane zasoby, za pośrednictwem identyfikatora jobID. | GET configure/<jobID> |
| Anuluj konfigurowanie | Anuluje określone zadanie konfiguracji. | POST configure/<jobID>/cancel |
Typowy przepływ pracy
Aby zaktualizować istniejący zasób, typowy przepływ pracy to:
- Pobieranie istniejącej konfiguracji zasobu (typ interfejsu API: zapytanie za pomocą drzewa zasobów)*
- Wprowadź niezbędne aktualizacje, a następnie prześlij żądanie konfiguracji (typ interfejsu API: Konfigurowanie przesyłania)
- Sprawdź stan żądania (typ interfejsu API: Konfigurowanie stanu i Konfigurowanie szczegółów stanu)
* Ten sam przepływ pracy można zastosować podczas tworzenia nowych zasobów, ale zamiast pobierania zasobów (krok 1) użyj tabeli referencyjnej interfejsu API zasobów, aby upewnić się, że używasz bieżącego schematu dla tworzonego typu zasobu.
Podsumowując, ten obraz przedstawia typowy wzorzec wywołania używany do przesyłania żądania konfiguracji niezależnie od tego, czy tworzysz nowy, czy modyfikujesz istniejący zasób.
Uwaga
Zapoznaj się z dodatkowymi wymaganiami wstępnymi specyficznymi dla typu oferty, którym zarządzasz, korzystając z sekcji Wskazówki dotyczące interfejsu API dla typu oferty.
Pobieranie istniejących konfiguracji zasobów
Przed zaktualizowaniem istniejących zasobów należy najpierw pobrać je, aby upewnić się, że masz najnowszą konfigurację. Istnieje kilka sposobów pobierania zasobów za pośrednictwem wywołania GET. Zobacz Metodę 1, szczegółowo poniżej, aby pobrać wszystkie zasoby w ramach określonego produktu w jednym wywołaniu interfejsu API.
Metoda 1. Drzewo zasobów
Schema: https://``schema.mp.microsoft.com``/schema/resource-tree/2022-03-01-preview2
GET resource-tree/<product-durableID>?$version=<schema-version>
Wszystkie konfiguracje zasobów w określonym produkcie można pobrać przy użyciu typu zasobu "drzewo zasobów" wraz z trwałym identyfikatorem produktu.
Najnowsza dostępna wersja schematu może być inna dla każdego zasobu. Podczas wykonywania żądania drzewa zasobów określona wersja schematu określa, która wersja jest zwracana dla każdego zasobu w produkcie. Określona wersja służy jako "maksymalny" limit wersji, ponieważ zwraca najnowszą wersję schematu dostępną dla wszystkich zasobów równej lub niższej wersji. Jeśli na przykład najnowsza dostępna wersja listy planów to "2022-03-01-preview3", odpowiedź będzie zawierać tę wersję, jeśli chcesz określić "2022-03-01-preview5" w żądaniu GET drzewa zasobów. Jeśli jednak żądanie "2022-03-01-preview2" jako wersji drzewa zasobów zwróci zasób "2022-03-01-preview2", mimo że najnowsza dostępna wersja to "2022-03-01-preview3". Zaleca się używanie najnowszej dostępnej wersji każdego zasobu, aby upewnić się, że używasz zaktualizowanego schematu z nowo obsługiwanymi funkcjami.
Uwaga
Jeśli nie znasz trwałego identyfikatora produktu, możesz użyć zewnętrznego identyfikatora produktu, aby pobrać zasób produktu, uruchamiając polecenie GET product?externalID=<product-externalID>&$version=<product-schema-version>. To żądanie korzysta z parametru ciągu zapytania, który został szczegółowo opisany w metodzie 3 poniżej. Odpowiedź będzie zawierać trwały identyfikator produktu, którego można użyć na potrzeby przyszłych żądań.
Domyślnie po uruchomieniu wywołania GET przy użyciu "drzewa zasobów" zostanie przywrócona wersja robocza zasobów. Jednak przekazując parametr zapytania "targetType", można określić żądany element docelowy, aby pobrać dane "preview" lub "live". W poniższym przykładzie wywołanie GET zwraca konfigurację środowiska w wersji zapoznawczej dla wszystkich zasobów w ramach produktu "12345678-abcd-efgh-1234-12345678901".
Przykładowe wywołanie GET:
GET https://graph.microsoft.com/rp/product-ingestion/resource-tree/product/12345678-abcd-efgh-1234-12345678901?targetType="preview"&$version=2022-03-01-preview5
Przykładowa odpowiedź:
{
"$schema": "https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2",
"root": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "preview"
},
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"id": "product/12345678-abcd-efgh-1234-12345678901",
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService",
"alias": "Contoso Image Resizing Service"
},
{
"$schema": "https://schema.mp.microsoft.com/schema/property/2022-03-01-preview3",
"id": "property/12345678-abcd-efgh-1234-12345678901/public/main",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"kind": "azureSaaS",
"termsConditions": "false",
"categories": {
"developer-tools-saas": [
"devService"
]
}
},
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/12345678-abcd-efgh-1234-12345678901/4e0bfefa-b993-4b79-a426-871c3bf236a5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468",
...
},
// The response would include all existing resources within this product.
{
...
}]
}
Metoda 2. Trwały identyfikator
GET <resource-durableID>?$version=<schema-version>
Pobierz określony zasób przy użyciu jego trwałego identyfikatora. Po utworzeniu zasobu trwały identyfikator zawsze pozostaje taki sam i może służyć do pobierania najnowszych zmian wersji roboczych tego zasobu przez wywołanie metody GET. Na przykład następujące żądanie zwróci wersję roboczą tego konkretnego produktu przy użyciu wersji schematu "2022-03-01-preview3".
GET product/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview3
Ważne
Ta metoda jest używana tylko do pobierania konfiguracji wersji roboczej. Jeśli chcesz pobrać dane w wersji zapoznawczej lub na żywo, użyj metody "resource-tree", zgodnie z powyższym opisem.
Aby znaleźć trwały identyfikator zasobów, możesz wykonać następujące czynności:
- Użyj metody "resource-tree", aby pobrać wszystkie zasoby w produkcie wraz z każdym z odpowiednich trwałych identyfikatorów lub
- Pobierz szczegóły ukończonego żądania konfiguracji zasobu, które zawiera trwałe identyfikatory wszystkich zasobów utworzonych lub zaktualizowanych w ramach żądania.
Pamiętaj, że właściwość "ID" jest trwałym identyfikatorem odpowiedniego zasobu.
Metoda 3. Parametry ciągu zapytania
GET <resourceType>?<query parameters>&$version=<schema-version>
Ta metoda służy do wykonywania zapytań dotyczących niektórych typów zasobów skojarzonych z określonym kontem. Możesz na przykład pobrać wszystkie produkty określonego typu produktu za pomocą jednego wywołania GET. Parametry ciągu zapytania służą do wykonywania zapytań dotyczących produktów, planów lub przesłanych danych.
W tej tabeli przedstawiono obsługiwane parametry zapytania dla każdego z obsługiwanych typów zasobów. Nie wszystkie typy zasobów obsługują każdy z parametrów zapytania. Ta tabela zawiera pełną listę aktualnie obsługiwanych ciągów zapytań.
| Typ zasobu | Parametry | Przykłady ciągów zapytania |
|---|---|---|
| Plan | Produktu*externalID $maxpagesize continuationToken$version * |
GET plan?product=<product-durableID>&$version=<schema-version>GET plan?product=<product-durableID>&externalID=<plan-externalID>&$version=<schema-version>GET plan?product=<product-durableID>&$maxpagesize=<#>&$version=<schema-version>GET plan?product=<product-durableID>&continuationToken=<token>&$version=<schema-version> |
| Produktu | externalID type $maxpagesize continuationToken$version * |
GET product?externalID=<product-externalID>&$version=<schema-version>GET product?type=<product-type>&$version=<schema-version>GET product?$maxpagesize=<#>&$version=<schema-version>GET product?continuationToken=<token>&$version=<schema-version> |
| Złożenia | Targettype $maxpagesize continuationToken$version * |
GET submission/<product-durableID>?targetType=<environment>&$version=<schema-version>GET submission/<product-id>?$maxpagesize=<#>&continuationToken=<token>&$version=<schema-version> |
| drzewo zasobów | targetType$version* |
GET resource-tree/<product-durableID>?targetType=<environment>&$version=<schema-version> |
* Parametry produktu i $version są zawsze wymagane.
Funkcjonalność każdego z obsługiwanych parametrów zapytania:
- product — podczas przekazywania parametru "product" w kontekście typu zasobu "plan" zwraca wszystkie plany w ramach tego konkretnego produktu.
- externalID — podczas przekazywania parametru "externalID" w kontekście produktu lub planu zwraca konfigurację odpowiedniego produktu lub planu. W przeciwieństwie do metody "resource-tree" ten parametr ciągu zapytania zwróci tylko szczegóły tego zasobu, a nie wszystkie zasoby w nim.
- type — podczas przekazywania parametru "type" w kontekście typu zasobu "product" zwraca wszystkie produkty tego typu skojarzone z kontem. Na przykład, określając wartość "type=softwareAsAService", zostaną zwrócone wszystkie produkty SaaS.
- targetType — zwraca dane określonego środowiska w kontekście używanego typu zasobu. Obsługiwane wartości "targetType" to "draft", "preview" lub "live".
- $maxpagesize — określając maksymalny rozmiar strony w postaci dodatniej liczby całkowitej, ten parametr służy do ograniczania wyników wyszukiwania podczas wykonywania zapytań dotyczących poprzednich przesłanych danych.
- continuationToken — ten parametr może być używany z parametrem "$maxpagesize", aby wysłać zapytanie do innego zestawu wyników dostępnych w wyszukiwaniu. Wartość "continuationToken" jest podana w odpowiedzi poprzedniej strony.
- $version — jest to wymagany parametr dla wszystkich wywołań, określa wersję schematu, którą chcesz uzyskać dla odpowiedzi z wykonanego żądania. Najnowsza dostępna wersja schematu może być inna dla każdego zasobu, a określona wersja stanowi "maksymalny" limit wersji. System zwraca dokładną wersję schematu, jeśli jest dostępna lub najbliższa wersja, która jest starsza niż żądana wersja. Może to pomóc w utrzymaniu działania kodu, nawet jeśli istnieją nowsze zmiany schematu, ale w celu korzystania z najnowszych funkcji zaleca się użycie najnowszej dostępnej wersji każdego schematu.
Wykonywanie zapytań dotyczących przesłanych danych
Istniejące przesłania produktów można pobrać, wykonując czynności GET submission/<product-durableID>. Domyślnie uzyskujesz wszystkie aktywne przesłania, w tym wersję roboczą, ale możesz dodatkowo wykonać zapytanie dotyczące określonego środowiska przy użyciu parametru zapytania "targetType": (GET submission/<product-durableID>?targetType=<environment>&$version=<version>).
Ważne
Po wypchnięciu przesyłania "Wersja zapoznawcza" do "Live" zastępuje wszystkie poprzednie przesyłanie "Na żywo". W takim przypadku dane reprezentują teraz środowiska "Wersja zapoznawcza" i "Na żywo", dopóki nowe przesłanie nie zostanie opublikowane w wersji zapoznawczej.
Przykładowe żądanie:
GET https://graph.microsoft.com/rp/product-ingestion/submission/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview2
Przykładowa odpowiedź:
W tym przykładzie przedstawiono żądanie GET dotyczące aktywnych przesłanych przesłanych do identyfikatora produktu "12345678-abcd-efgh-1234-12345678901". Aktywne przesyłanie "Na żywo" (przesyłanie/12345678-abcd-efgh-1234-12345678901/1152921515689847470) zostało opublikowane jako podgląd najpierw, a następnie później do wygaśnięcia. Po wypchnięciu tej przesyłania na żywo 25 stycznia 2022 r. była ona reprezentowana zarówno w wersji zapoznawczej, jak i na żywo do momentu utworzenia nowej wersji zapoznawczej (12345678-abcd-efgh-1234-12345678901/1152921515689848683) 4 lutego 2022 r.
{
"value": [
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345688901/0",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "draft"
}
},
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/1152921515689847470",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "live"
},
"status": "completed",
"result": "succeeded",
"created": "2022-01-25T07:13:06.4408032Z"
},
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/1152921515689848683",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "preview"
},
"status": "completed",
"result": "succeeded",
"created": "2022-02-04T20:07:22.4220588Z"
}
]
}
Tworzenie nowych produktów i zasobów
Możesz utworzyć nowe zasoby, w tym nowe produkty, w ramach pojedynczego żądania konfiguracji. Korzystając z tabeli referencyjnej interfejsu API zasobów, możesz pobrać schemat dla typu zasobu, który chcesz utworzyć. Gwarantuje to, że używasz najnowszego schematu i dlatego konfigurujesz wszystkie niezbędne właściwości do utworzenia zasobu.
Jeśli tworzysz nowy produkt, wymagania różnią się w zależności od typu produktu. W związku z tym należy podać różne zasoby. Możesz odwołać się do odpowiedniej dokumentacji komercyjnej platformy handlowej dla odpowiedniego typu produktu, aby upewnić się, że konfigurujesz podstawowe wymagania w żądaniu. Alternatywnie możesz wysłać żądanie konfiguracji przy użyciu tylko zasobu produktu. Po utworzeniu produktu wywołaj interfejs API konfigurowania szczegółów stanu, aby pobrać utworzony zasób produktu i znaleźć jego trwały identyfikator w celu wywołania interfejsu API zapytań drzewa zasobów. Odpowiedź zwraca odpowiednie obsługiwane zasoby dla utworzonego typu produktu.
Podobnie, aby utworzyć nowy zasób w istniejącym produkcie, należy również pobrać najnowszy schemat tego określonego typu zasobu. Upewnij się, że zasoby zależne są podane w ramach żądania konfiguracji, przeglądając zależności zasobów.
Po utworzeniu zasobów przy użyciu schematów dowiedz się, jak utworzyć żądanie konfiguracji.
Modyfikowanie istniejących produktów i zasobów
Aktualizacje można przesyłać przy użyciu ładunku konfiguracji. Ten ładunek składa się z co najmniej jednego typu zasobu, a właściwość "$schema" wskazuje przywoływany typ zasobu.
Napiwek
Zalecamy najpierw pobranie istniejących zasobów przed opublikowaniem aktualizacji, aby upewnić się, że korzystasz z najnowszej konfiguracji.
Po zmodyfikowaniu zasobów dowiedz się, jak utworzyć żądanie konfiguracji.
Żądania konfiguracji
Możesz edytować i publikować w tym samym ładunku. Aby przesłać żądanie konfiguracji, użyj metody HTTP POST interfejsu API konfiguracji. Ładunek konfiguracji składa się z tablicy zasobów, które wskazują żądane zmiany. Wszystkie zmiany mają wpływ tylko na wersję roboczą do momentu jawnego przesłania zasobu przesyłania w celu opublikowania zmian wersji roboczej. Podczas publikowania w wersji zapoznawczej lub na żywo uwzględnij zasób przesyłania i określ środowisko docelowe. Przed przesłaniem żądania musisz wiedzieć, jak odwoływać się do zasobów i zrozumieć ich zależności.
Schema:<https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2>
Po przesłaniu żądania konfiguracji otrzymasz obiekt configure-status z identyfikatorem jobID, którego można użyć do śledzenia postępu i wyników żądania.
Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>
Odwołania do zasobów i zależności
Informacje
Aby odwołać się do istniejącego zasobu w żądaniu konfiguracji, podaj typ "$schema" zasobu wraz z trwałym identyfikatorem zasobu. W przypadku produktów i planów można również odwoływać się do tych zasobów za pośrednictwem ich identyfikatora zewnętrznego.
Identyfikator trwały można znaleźć we właściwości "ID", na przykład jeśli jest to zasób produktu, do którego chcemy się odwołać w innym zasobie:
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"id": "product/12345678-abcd-efgh-1234-12345678901",
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService",
"alias": "Contoso Image Resizing Service"
}
Trwały identyfikator to "product/071b135e-9faf-4ff7-b113-a3f25bb0f468".
Identyfikator trwały można następnie użyć w poniższym przykładzie zasobu listy, ustawiając go we właściwości schematu zasobów "product" w następujący sposób:
{
"$schema": "https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468", // product durable ID
...
}
Identyfikator zewnętrzny zasobów produktu i planu jest definiowany we właściwości "identity".
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"alias": "Gold - Annual payment",
"identity": {"externalID": "gold-annual"},
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468",
...
}
Identyfikator zewnętrzny planu "gold-annual" można następnie odwoływać się do innych kolejnych zasobów w następującym formacie:
{
"$schema": "https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468"}
"plan": {"externalID": "gold-annual"}
...
}
Przykładowe żądanie:
W tym przykładzie ładunek konfiguracji służy do tworzenia nowego produktu SaaS z zewnętrznym identyfikatorem "ds-contoso-image-resize-demo". Po utworzeniu tego produktu możesz później odwołać się do tego produktu przy użyciu jego trwałego identyfikatora lub identyfikatora zewnętrznego.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService",
"alias": " Contoso Image Resizing Service"
}
]
}
Przykładowa odpowiedź:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
"jobID": "071b135e-9faf-4ff7-b113-a3f25bb0f468",
"jobStatus": "running",
"jobResult": "pending",
"jobStart": "2022-08-18T16:35:56.5917185Z",
"jobEnd": "0001-01-01T00:00:00",
"errors": []
}
Następnie możesz użyć identyfikatora jobID za pośrednictwem interfejsu API konfigurowania stanu, aby sprawdzić stan żądania.
Zależności
Niektóre zasoby mają zależności od utworzenia innego zasobu jako wymagania wstępne. W tej sytuacji używamy właściwości "resourceName" w ramach tego samego ładunku, aby określić zależność zasobu produktu w zasobie planu, ponieważ tworzysz oba te elementy w tym samym żądaniu.
Element "resourceName" służy tylko do identyfikowania każdego zasobu w ramach żądania konfiguracji, które wykonujesz. Wartość nie będzie częścią danych zasobów, nie jest przechowywana ani nie jest widoczna dla klientów. Ponadto, jeśli w ramach żądania konfiguracji wystąpią błędy, "resourceName" zostanie użyty do wywołania zasobu, do którego należy błąd.
Przykładowe żądanie:
W tym przykładzie należy utworzyć produkt przed planem i dlatego jest używana właściwość "resourceName". Tworzony produkt "myNewProduct" będzie wartością używaną dla zasobu "resourceName" i przywoływaną w ramach zasobu planu zależnego.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"resourceName": "myNewProduct",
"alias": "Contoso Image Resizing Service",
...
},
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"alias": " Gold - Annual payment",
"product": {"resourceName": "myNewProduct"}
...
},
}]
}
Zasób przesyłania
W przypadku publikowania w "wersji zapoznawczej" lub "na żywo" dołącz zasób przesyłania do żądania, który zawiera:
- Właściwość "product", oznaczając produkt aktualizowany jako przywoływany przez jego trwały identyfikator lub identyfikator zewnętrzny
- Właściwość "targetType" oznaczającą środowisko docelowe
Podczas publikowania na żywo w szczególności "identyfikator" przesłania w wersji zapoznawczej, którą chcesz opublikować:
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/11521167929065",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": { "targetType": "live" }
}
Uwaga
Jeśli zasób przesyłania nie zostanie uwzględniony, zmiany zostaną wprowadzone tylko do stanu wersji roboczej.
Publikowanie w wersji zapoznawczej
Typy produktów komercyjnych obsługują środowisko w wersji zapoznawczej, a każda aktualizacja musi być najpierw opublikowana w wersji zapoznawczej przed rozpoczęciem działania. Nie można publikować bezpośrednio na żywo.
Ważne
Wyjątkiem jest wprowadzenie zmian w prywatnych grupach planów. Podczas synchronizowania aktualizacji z odbiorcami prywatnymi te zmiany będą propagowane zarówno do wersji zapoznawczej, jak i na żywo w tym samym czasie.
Istnieją dwa sposoby publikowania zasobów w środowisku w wersji zapoznawczej. Jeśli jakiekolwiek zmiany muszą zostać wprowadzone do przesłania w wersji zapoznawczej, wykonaj inne żądanie GET, wprowadź niezbędne zmiany i wypchnij zmiany ponownie. Nie musisz najpierw przechodzić na żywo ze zmianami początkowymi.
Metoda 1. Publikowanie wszystkich zasobów roboczych
Jeśli chcesz opublikować każdą zmianę wersji roboczej, możesz wysłać żądanie konfiguracji z zasobem przesyłania, który ustawia środowisko wersji zapoznawczej jako "targetType". Jak pokazano w poniższym przykładzie, nie musisz jawnie podawać każdego zasobu, który wymaga aktualizacji, ponieważ ta metoda publikuje wszystkie zmiany w środowisku docelowym, co w tym przypadku jest w wersji zapoznawczej. Wystarczy podać punkt końcowy interfejsu API konfiguracji i zasób przesyłania.
Przykładowe żądanie:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
// Below is the submission resource to publish to preview
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
"target": { "targetType": "preview" }
}
]
}
Metoda 2. Publikowanie określonych zasobów roboczych (znanych również jako publikowanie modułowe)
Alternatywnie, jeśli nie chcesz publikować wszystkich zmian roboczych w różnych zasobach, wystarczy podać zasoby, które chcesz opublikować wraz z zasobem przesyłania, aby wyzwolić modułową publikację. Możesz również użyć tego podejścia, aby wprowadzić zmiany w zasobach i opublikować je w tym samym czasie zamiast w ramach zbiorczej aktualizacji, tak jak w przypadku metody 1. W przypadku modułowego publikowania wszystkie zasoby są wymagane z wyjątkiem szczegółów poziomu produktu (na przykład listy, dostępności, pakietów, odsprzedawcy) zgodnie z typem produktu.
Przykładowe żądanie:
W tym przykładzie zasoby w produkcie są jawnie udostępniane jako część modułowego publikowania, a następnie zasób przesyłania.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview2",
"id": "product/12345678-abcd-efgh-1234-12345678901",
...
},
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
...
},
// additional resources
{
...
},
// Below is the submission resource to publish to preview
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
"target": { "targetType": "preview" }
}
]
}
Publikowanie na żywo
Po przetestowaniu i zweryfikowaniu zmian w wersji zapoznawczej możesz wypchnąć zmiany na żywo, wysyłając żądanie konfiguracji z wartością "ID" przesłania podglądu i wartością "targetType" ustawioną na "live". Aby znaleźć "identyfikator" przesłania w wersji zapoznawczej, aby uwzględnić je w żądaniu konfiguracji, zobacz Wykonywanie zapytań dotyczących przesłanych danych.
Ważne
W przeciwieństwie do publikowania w wersji zapoznawczej nie ma możliwości wykonania modułowego publikowania podczas publikowania na żywo. W związku z tym ważne jest, aby upewnić się, że przed rozpoczęciem przesyłania podglądu na żywo wprowadzono zmiany.
Przykładowe żądanie:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
// Below is the submission resource, including the preview submission id, to publish to live.
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/11521167929065",
"product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
"target": { "targetType": "live" }
}
]
}
Sprawdzanie stanu żądania
Niezależnie od zasobów uwzględnionych w żądaniu konfiguracji lub wprowadzania zmian otrzymasz obiekt configure-status z powrotem w odpowiedzi po przesłaniu żądania po pomyślnym przetworzeniu. Identyfikator "jobID" jest ważny, ponieważ można go później użyć do sprawdzenia stanu żądania.
Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>
Przykładowa odpowiedź na przesłane żądanie:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
"jobID": "d4261631-c583-4949-a612-5150882632e9",
"jobStatus": "notStarted",
"jobResult": "pending",
"jobStart": "2022-03-01T13:32:43.123456Z",
"jobEnd": "0001-01-01T00:00:00",
"errors": []
}
Stan oczekującego żądania
Stan można pobrać do momentu zakończenia zadania przy użyciu następującego wywołania i wprowadzenia identyfikatora "jobID" żądania. Obiekt może również zawierać listę błędów, jeśli wystąpiły jakiekolwiek problemy z żądaniem.
GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>/status?$version=2022-03-01-preview2
Należy pamiętać, że czas ukończenia może się różnić w zależności od złożoności żądania,
Podsumowanie ukończonego żądania
Po pomyślnym lub niepowodzeniu zadania konfigurowania żądania można pobrać listę zasobów utworzonych lub zaktualizowanych przy użyciu identyfikatora "jobID".
Uwaga
Jeśli wykonasz to wywołanie przed ukończeniem zadania, zakończy się niepowodzeniem. Ponadto zwróci tylko zasoby, które zostały ukończone pomyślnie, lub w przypadku anulowania tylko te ukończone przed anulowaniem.
Schema: <https://``schema.mp.microsoft.com``/schema/configure-detail/2022-03-01-preview2>
GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>?$version=2022-03-01-preview2
Przykładowe żądanie:
W poniższym przykładzie żądanie GET służy do pobierania szczegółów podsumowania żądania konfiguracji używanego we wcześniejszym przykładzie, który utworzył nowy produkt SaaS. Odpowiedź to obiekt configure-detail z tablicą zasobów zawierającą zasób produktu, który został utworzony wraz z jego trwałym identyfikatorem.
GET https://graph.microsoft.com/rp/product-ingestion/configure/071b135e-9faf-4ff7-b113-a3f25bb0f468?$version=2022-03-01-preview2
Przykładowa odpowiedź:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-detail/2022-03-01-preview2",
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview2",
"id": "product/12345678-abcd-efgh-1234-12345678901",
"identity": {
"externalID": "ds-contoso-image-resize-demo "
},
"type": "softwareAsAService",
"alias": "Contoso Image Resizing Service"
}
]
}
Anulowanie żądania konfiguracji
Zanim zadanie zostanie ukończone, możesz spróbować anulować je w razie potrzeby. W przypadku długotrwałych żądań, takich jak publikowanie w wersji zapoznawczej lub "na żywo", żądanie anulowania może zostać odrzucone, jeśli zadanie jest wystarczająco daleko w ramach pełnego przetwarzania.
Aby anulować zadanie, wykonaj wywołanie POST do punktu końcowego anulowania i podaj identyfikator zadania żądania, które chcesz anulować.
POST https://graph.microsoft.com/rp/product-ingestion/configure<jobID>/cancel?$version=2022-03-01-preview2
Przykładowe żądanie:
POST <https://graph.microsoft.com/rp/product-ingestion/configure/d4261631-c583-4949-a612-5150882632e9/cancel?$version=2022-03-01-preview2>
Przykładowa odpowiedź pomyślnego żądania anulowania:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
"jobID": "d4261631-c583-4949-a612-5150882632e9",
"jobStatus": "completed",
"jobResult": "cancelled",
"jobStart": "2022-03-01-T13:32:43.123456Z",
"jobEnd": "2022-03-01T17:34:21.5225132Z",
"errors": []
}
Przykładowa odpowiedź w przypadku, gdy anulowanie nie jest dozwolone: HTTP Status code: 400
Zawartość:
{
"error": {
"code": "badRequest",
"message": "Cannot cancel job, job has already completed.",
"details": []
}
}
Ważne
Pamiętaj, że anulowanie dotyczy tylko zasobów, które nie zostały jeszcze przetworzone. Niektóre zasoby mogły już ukończyć przetwarzanie i będą odzwierciedlać najnowsze aktualizacje konfiguracji, pomimo anulowania żądania.
Podsumowanie żądania konfiguracji można pobrać po anulowaniu, aby sprawdzić, które zasoby (jeśli istnieją) zostały już przetworzone przed anulowaniem.
Synchronizowanie prywatnych odbiorców
W przypadku produktu na żywo aktualizacje dla prywatnych odbiorców w wersji roboczej, wersji zapoznawczej i środowiskach na żywo mogą być wykonywane jednocześnie bez konieczności publikowania. Grupę odbiorców prywatnych można zsynchronizować przy użyciu zasobu "price-and-availability-update-private-audiences", określając odbiorców, które chcesz dodać lub usunąć z określonego planu. Spowoduje to zsynchronizowanie wersji roboczej, wersji zapoznawczej i środowisk na żywo, aby mieć te same prywatne wartości odbiorców. Nie musisz podawać zasobu przesyłania podczas synchronizowania odbiorców prywatnych.
Aby edytować grupy odbiorców wersji roboczych, użyj zasobu "price-and-availability-plan" i właściwości "privateAudiences". Konieczne będzie przejście przez zwykły przepływ publikowania dla wartości, które mają być ustawione w wersji zapoznawczej i na żywo.
Ważne
Obsługiwane typy odbiorców to "subskrypcja", "ea", "msdn" i "dzierżawa", ale obsługa tych typów różni się w zależności od typu produktu. Jeśli produkt obsługuje więcej niż jeden typ identyfikatora w celu skonfigurowania odbiorców prywatnych (na przykład identyfikatorów dzierżawy i identyfikatorów subskrypcji), należy wykonać pełną publikację, jeśli po raz pierwszy podaj nowy typ identyfikatora. W tym przypadku nie można zsynchronizować odbiorców prywatnych.
Przykładowe żądanie synchronizacji konfiguracji odbiorców prywatnych:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview2",
"product": "product/12345678-abcd-efgh-1234-12345678901", // product durable ID
"plan": "plan/12345678-abcd-efgh-1234-12345678901/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b", //plan durable ID
"privateAudiences":
{
"add ":
[
{
"type": "tenant",
"id": "4c2bdcdc-f10e-468d-8a2a-0832e089215b",
"label": "test 1"
}
],
"remove ":
[
{
"type": "subscription",
"id": "412c45bf-c99a-4e96-b683-77b0aa2dd09e",
"label": "test 2"
}
]
}
}
]
}
Konfigurowanie zarządzania potencjalnymi klientami
Połączenie system zarządzania relacjami z klientami (CRM) z produktem platformy handlowej, dzięki czemu możesz otrzymywać informacje kontaktowe klienta, gdy klient wyraża zainteresowanie lub wdraża produkt. To połączenie można modyfikować w dowolnym momencie podczas tworzenia produktu lub po jego utworzeniu. Aby dowiedzieć się więcej, zobacz Pobieranie potencjalnych klientów.
Przykładowe żądanie konfigurowania zarządzania potencjalnymi klientami:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3",
"id": "customer-leads/a0c6484f-b4fb-4129-ac6b-35f2b5628089",
"product": "product/a0c6484f-b4fb-4129-ac6b-35f2b5628089",
"leadDestination": "httpsEndpoint",
"httpsEndpointLeadConfiguration": {
"httpsEndpointUrl": "https://www.your-crm.com/triggers/invoke"
}
}
]
}
Stany cyklu życia zasobów
Istnieją różne akcje, które można wykonać na mapie na stan cyklu życia zasobu. Nie wszystkie zasoby mają stan cyklu życia, a nie wszystkie stany cyklu życia są obsługiwane przez wszystkie zasoby. Aby sprawdzić, czy zasób ma stan cyklu życia i które wartości są obsługiwane, możesz sprawdzić schemat zasobów pod kątem istnienia właściwości "lifecycleState". Poniżej opisano różne obsługiwane stany cyklu życia.
Usunięty
Określone zasoby można usunąć, aktualizując właściwość "lifecycleState" na wartość "deleted". Można usunąć tylko zasoby robocze, które nie zostały wcześniej opublikowane. Tej akcji nie można cofnąć.
Przykładowe żądanie:
W poniższym przykładzie plan roboczy "podstawowy" jest usuwany.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"identity": { "externalID": "basic" },
"alias": "basic plan"
"lifecycleState": "deleted"
}
]
}
Przestarzały
Wycofanie usuwa zasób z komercyjnej platformy handlowej. Aby wycofać, ustaw właściwość "lifecycleState" na "przestarzałe" dla zasobów, które go obsługują. Istnieją różne poziomy wycofywania. Wszystkie typy produktów obsługują przestarzałe całe produkty i poszczególne plany w nim. Aby później przywrócić przestarzały zasób, zapoznaj się ze stanem cyklu życia "generalAvailable".
Przykładowe żądanie wycofania produktu:
W poniższym przykładzie przesyłanie na żywo produktu jest ustawione na przestarzałe. Po zastosowaniu tej zmiany zostanie ona automatycznie opublikowana, aby obowiązywać.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2 ",
"id": "submission/9f8af57f-ab07-461b-8404-50e10e5e80fb/1152921515689848683",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"target": {
"targetType": "live"
},
"lifecycleState": "deprecated"
}
]
}
W przypadku wycofania planów właściwość "lifecycleState" musi zostać zmieniona na "przestarzałą", a zmiany muszą zostać opublikowane w wersji zapoznawczej, a następnie "na żywo", aby wycofanie zostało zastosowane. Różni się to od wycofywania na poziomie produktu, w którym wycofanie zostanie automatycznie skonfigurowane w środowisku na żywo.
Przykładowe żądanie wycofania planu:
W poniższym przykładzie plan w ramach produktu SaaS jest ustawiony na przestarzałe. Pamiętaj, że aby zastosować tę zmianę, możesz później opublikować za pomocą zasobu przesyłania.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2 ",
"id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"identity": { "externalID": "basic" },
"alias": "basic plan"
"lifecycleState": "deprecated"
}
]
}
Istnieją inne formy wycofywania, które różnią się w zależności od typu produktu. Dowiedz się więcej na temat wycofywania rozwiązań SaaS, maszyn wirtualnych i kontenerów.
Ogólnie dostępne
generallyAvailable jest domyślnym stanem cyklu życia dla wszystkich zasobów. Gdy zasób jest przestarzały, możesz go przywrócić, zmieniając właściwość "lifecycleState" z powrotem na "generalAvailable". Aby przywrócić przestarzały produkt, musisz opublikować produkt w celu wyświetlenia podglądu, a następnie na żywo. Przykłady rozwiązań SaaS, maszyn wirtualnych i kontenerów można znaleźć w odpowiednich artykułach.
Przykładowe żądanie przywrócenia planu:
W poniższym przykładzie plan ma zostać przywrócony. Aby zastosować tę zmianę, później musisz opublikować całą drogę do życia przy użyciu zasobu przesyłania.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"identity": { "externalID": "basic" },
"alias": "basic plan"
"lifecycleState": "generallyAvailable"
}
]
}
Dokumentacja interfejsu API zasobów
Poniższe wersje schematu mają zastosowanie tylko do wersji zapoznawczej i zmienią się, gdy interfejs API stanie się ogólnie dostępny.
Uwaga
Istniejące dostępne zasoby i ich wersje można wyświetlić tutaj: resources-index
| Typ zasobu | Opis | Schemat |
|---|---|---|
| azure-test-drive-technical-configuration | Szczegóły techniczne ułatwiające platformie handlowej firmy Microsoft łączenie się z rozwiązaniem testowym. | https://schema.mp.microsoft.com/schema/azure-test-drive-technical-configuration/2022-03-01-preview3 |
| komercyjna platforma handlowa — konfiguracja | Opisuje transakcyjną konfigurację produktów na platformie handlowej. | https://schema.mp.microsoft.com/schema/commercial-marketplace-setup/2022-03-01-preview2 |
| potencjalni klienci | Umożliwia nawiązywanie połączenia z systemem CRM w celu odbierania potencjalnych klientów. | https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3 |
| Aukcji | Obejmuje to opisy produktu, które będą wyświetlane w witrynach sklepów platformy handlowej firmy Microsoft. | https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5 |
| element zawartości listy | Zrzuty ekranu i zasoby marketingowe połączone z zasobem listy. | https://schema.mp.microsoft.com/schema/listing-asset/2022-03-01-preview5 |
| przyczepa z listą | Zasoby wideo połączone z zasobem listy. | https://schema.mp.microsoft.com/schema/listing-trailer/2022-03-01-preview5 |
| integracja z platformą microsoft365 | Włączanie i wybieranie typu platformy Microsoft 365. | https://schema.mp.microsoft.com/schema/microsoft365-integration/2022-03-01-preview2 |
| Plan | Aby utworzyć plany, do których będą następnie odwoływać się skonfigurowane zasoby na poziomie planu, takie jak lista planów. | https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2 |
| lista planów | Zdefiniuj nazwę i opis planu, tak jak chcesz, aby były wyświetlane na platformie handlowej. | https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5 |
| price-and-availability-custom-meter | Zdefiniuj mierniki niestandardowe współużytkowane w ramach planów. | https://schema.mp.microsoft.com/schema/price-and-availability-custom-meter/2022-03-01-preview3 |
| oferta cenowa i dostępność | Zdefiniuj ograniczoną grupę odbiorców, którzy mogą przeglądać produkt przed opublikowaniem go na żywo. | https://schema.mp.microsoft.com/schema/price-and-availability-offer/2022-03-01-preview3 |
| plan cen i dostępności | Skonfiguruj rynki, w których jest dostępny ten plan, żądany model monetyzacji, cena i terminy rozliczeniowe. | https://schema.mp.microsoft.com/schema/price-and-availability-plan/2022-03-01-preview4 |
| price-and-availability-update-private-audiences | Aktualizacje do prywatnych odbiorców w środowiskach roboczych, zapoznawczych i na żywo można wykonywać w tym samym czasie bez konieczności publikowania. | https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview3 |
| private-and-availability-private-offer-plan | Służy do konfigurowania bezwzględnych szczegółów cen cen produktu/planu używanego w ramach oferty prywatnej | https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2022-07-01 |
| oferta prywatna | Definiuje nazwę i typ oferty prywatnej wraz z warunkami i szczegółami oferty wraz z dołączonymi produktami/planem oraz ich cennikami | https://schema.mp.microsoft.com/schema/private-offer/2022-07-01 |
| Produktu | Jest to główny zasób, definiuje nazwę i typ produktu, wszystkie zasoby odwołują się do tego. | https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3 |
| właściwość | Zdefiniuj kategorie i branże dotyczące oferty, wersji aplikacji i umów prawnych. | https://schema.mp.microsoft.com/schema/property/2022-03-01-preview5 |
| Sprzedawcy | Skonfiguruj partnerów w programie Dostawca rozwiązań w chmurze s (CSP), dla którego chcesz udostępnić produkt. | https://schema.mp.microsoft.com/schema/reseller/2022-03-01-preview2 |
| drzewo zasobów | Opisuje produkt listę zasobów dla tego produktu w bieżącym stanie dla określonego środowiska docelowego. | https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2 |
| software-as-a-service-technical-configuration | Szczegóły techniczne ułatwiające platformie handlowej firmy Microsoft łączenie się z rozwiązaniem. | https://schema.mp.microsoft.com/schema/software-as-a-service-technical-configuration/2022-03-01-preview3 |
| Złożenia | Może służyć do wyzwalania różnych akcji w produkcie i wskazywania stanu publikowania środowiska obojętnego produktu (wersja robocza, wersja zapoznawcza i na żywo). | https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2 |
| Przetestować | Określ, czy chcesz zezwolić klientom na wypróbowanie produktu bezpłatnie przez ograniczony czas. | https://schema.mp.microsoft.com/schema/test-drive/2022-03-01-preview2 |
| lista test-drive-listing | Zdefiniuj szczegóły dotyczące sposobu, w jaki klienci mogą wypróbować produkt. | https://schema.mp.microsoft.com/schema/test-drive-listing/2022-03-01-preview3 |
| virtual-machine-plan-technical-configuration | Szczegóły techniczne opisujące maszynę wirtualną i lokalizację obrazu. | https://schema.mp.microsoft.com/schema/virtual-machine-plan-technical-configuration/2022-03-01-preview3 |
| virtual-machine-test-drive-technical-configuration | Szczegóły techniczne ułatwiające platformie handlowej firmy Microsoft łączenie się z rozwiązaniem testowym. | https://schema.mp.microsoft.com/schema/virtual-machine-test-drive-technical-configuration/2022-03-01-preview2 |
| container-plan-technical-configuration | Szczegóły techniczne opisujące właściwości obrazu kontenera. | https://schema.mp.microsoft.com/schema/container-plan-technical-configuration/2022-03-01-preview3 |
Wskazówki dotyczące interfejsu API na typ produktu
Interfejs API pozyskiwania produktów zostanie udostępniony innym typom produktów w przyszłości. W miarę obsługi większej liczby typów produktów zostaną udostępnione bardziej szczegółowe wskazówki dotyczące poszczególnych typów produktów.
| Typ produktu | Zasoby specyficzne dla typu produktu |
|---|---|
| Oferty prywatne | Tworzenie ofert prywatnych i zarządzanie nimi za pośrednictwem interfejsu API pozyskiwania produktów |
| i SaaS | Tworzenie ofert SaaS i zarządzanie nimi za pośrednictwem interfejsu API pozyskiwania produktów |
| Maszyny wirtualne | Tworzenie ofert maszyn wirtualnych i zarządzanie nimi za pośrednictwem interfejsu API pozyskiwania produktów |
| Kontenery | Tworzenie ofert kontenerów i zarządzanie nimi za pośrednictwem interfejsu API pozyskiwania produktów |
Wersje i aktualizacje interfejsu API
| Update | Co się zmieniło? |
|---|---|
| 11-2023 | Wszystkie punkty końcowe schematu zostały zaktualizowane z product-ingestion.azureedge.net do schema.mp.microsoft.com |
| 12-2022 | Nowy schemat w wersji 2022-03-01-preview3 interfejsu API pozyskiwania komputerów dla potencjalnych klientów jest teraz dostępny, który akceptuje wartości clientID i clientSecret podczas konfigurowania potencjalnych klientów i zatrzymuje przechwytywanie identyfikatora serwera i kontaktowych pól poczty e-mail. Przejdź do nowej wersji i podaj identyfikator clientID i clientSecret, aby kontynuować konfigurowanie łącznika Marketo dla ofert w witrynie Marketplace. Nowy adres URL schematu: https://``schema.mp.microsoft.com``/schema/customer-leads/2022-03-01-preview3 |
| 09-2022 | Obsługa wersji zapoznawczej kontenera została wydana w wersji 2022-03-01-preview4 |
| 08-2022 | Obsługa wersji zapoznawczej oprogramowania jako usługi jest dostępna w wersji 2022-03-01-preview3 |
| 08-2022 | Publiczna wersja oferty prywatnej w wersji 2022-07-01 |
| 05-2022 | Obsługa wersji zapoznawczej maszyny wirtualnej została wydana w wersji 2022-03-01-preview2 |
Następne kroki
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