Interfejs API pozyskiwania produktów dla usługi SaaS
Interfejs API pozyskiwania produktów to zmodernizowany interfejs API, który łączy wszystkie istniejące interfejsy API przesyłania we wszystkich produktach platformy handlowej. Aby uzyskać szczegółowe informacje na temat rozpoczynania pracy, zapoznaj się z tematem Interfejs API pozyskiwania produktów.
Ten artykuł zawiera wskazówki dotyczące używania interfejsów API specjalnie dla typu oferty SaaS.
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 następującą sekcję, Metoda 1, aby pobrać wszystkie zasoby w ramach określonego produktu w jednym wywołaniu interfejsu API.
Metoda 1. Drzewo zasobów
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. Podasz wersję schematu jako maksymalną obsługiwaną wersję dla każdego z odpowiednich zasobów żądanego produktu.
Uwaga
Jeśli nie znasz trwałego identyfikatora produktu, możesz najpierw pobrać zasób produktu przy użyciu identyfikatora zewnętrznego produktu i uruchomić 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. 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": "product_external_id_example"
},
"type": "softwareAsAService",
"alias": "product_example"
},
{
"$schema": "https://schema.mp.microsoft.com/schema/commercial-marketplace-setup/2022-03-01-preview2",
"id": "commercial-marketplace-setup/12345678-abcd-efgh-1234-12345678901",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"sellThroughMicrosoft": true,
"useMicrosoftLicenseManagementService": false
},
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/12345678-abcd-efgh-1234-12345678901/98756328-04e9-55ae-9403-52b6c971a956
...
},
// The response would include all existing resources within this product.
{
...
}]
}
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. Sprawdź schemat zasobu pod kątem istnienia właściwości lifecycleState , aby sprawdzić, czy zasób ma stan cyklu życia i które wartości są obsługiwane. Poniżej przedstawiono kilka przykładów ustawiania stanu cyklu życia zasobu dla typu oferty SaaS.
Przestarzałe
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ą. Różne poziomy wycofywania są obsługiwane w zależności od typu produktu. Na przykład w przypadku produktów SaaS można wycofać plany lub cały produkt. W przypadku wycofania planów należy zmienić wartość "lifecycleState", a zmiany należy opublikować 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 ustawienie powoduje automatyczne rozpoczęcie wycofywania w środowisku na żywo. Aby później przywrócić przestarzały zasób, zapoznaj się ze stanem cyklu życia "generalAvailable".
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"
}
]
}
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"
}
]
}
Ogólnie dostępne
generalAvailable to domyślny stan 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 ogólnie Dostępne. Aby przywrócić przestarzały produkt, należy opublikować produkt jeszcze raz, aby wyświetlić podgląd, a następnie na żywo.
Przykładowe żądanie przywracania 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"
}
]
}