API Penyerapan Produk untuk marketplace komersial
API Penyerapan Produk adalah API modern yang menyatukan semua API pengiriman yang ada di semua produk marketplace komersial. API memungkinkan Anda membuat, menerbitkan, dan mengelola sumber daya yang terkait dengan produk dan paket dalam akun Pusat Mitra Anda. Ini menggunakan pola deklaratif untuk mengirimkan permintaan, di mana status yang diinginkan ditunjukkan dibandingkan dengan menentukan langkah-langkah individual untuk mencapai status yang diinginkan.
Artikel ini menyediakan panduan tentang cara memulai API untuk jenis penawaran marketplace komersial apa pun. API Penyerapan Produk saat ini didukung untuk saaS, VM, penawaran Privat, dan jenis penawaran kontainer dan sedang dalam pratinjau. Untuk panduan khusus untuk penawaran Anda, tinjau panduan API per jenis penawaran.
Penting
Grafik Azure Active Directory (Azure AD) tidak digunakan lagi per 30 Juni 2023. Ke depannya, kami tidak melakukan investasi lebih lanjut di Azure AD Graph. API Azure AD Graph tidak memiliki komitmen SLA atau pemeliharaan di luar perbaikan terkait keamanan. Investasi dalam fitur dan fungsionalitas baru hanya akan dilakukan di Microsoft Graph.
Kami akan menghentikan Azure AD Graph dalam langkah-langkah bertahap sehingga Anda memiliki waktu yang cukup untuk memigrasikan aplikasi Anda ke MICROSOFT Graph API. Di kemudian hari yang akan kami umumkan, kami akan memblokir pembuatan aplikasi baru apa pun menggunakan Azure AD Graph.
Untuk mempelajari selengkapnya, lihat Penting: Penghentian Azure AD Graph dan Penghentian Modul Powershell.
Memulai
API Penyerapan Produk dapat diakses menggunakan MSGraph API dengan nama beban kerja "penyerapan produk". URL dasar adalah https://graph.microsoft.com/rp/product-ingestion.
Untuk menggunakan API Penyerapan Produk, Anda harus terlebih dahulu memperoleh hal berikut:
- ID Microsoft Entra dan pastikan Anda memiliki izin Administrator global untuk direktori
- Aplikasi Microsoft Entra
- Token akses Microsoft Entra
Langkah 1: Lengkapi prasyarat
Sebelum Anda mulai menulis kode untuk memanggil API Penyerapan Produk, pastikan Anda telah menyelesaikan prasyarat berikut.
- Anda (atau organisasi Anda) harus memiliki direktori Microsoft Entra dan Anda harus memiliki izin Administrator global untuk direktori tersebut. Jika Anda sudah menggunakan Microsoft 365 atau layanan bisnis lainnya dari Microsoft, Anda sudah memiliki direktori Microsoft Entra. Jika tidak, Anda dapat membuat ID Microsoft Entra baru di Pusat Mitra tanpa biaya tambahan.
- Anda harus mengaitkan aplikasi Microsoft Entra dengan akun Pusat Mitra Anda dan mendapatkan ID penyewa, ID klien, dan kunci Anda. Anda memerlukannya untuk mendapatkan token akses Microsoft Entra yang akan Anda gunakan dalam panggilan ke API pengiriman Microsoft Store.
Mengaitkan aplikasi Microsoft Entra dengan akun Pusat Mitra Anda
Untuk menggunakan API Penyerapan Produk, Anda harus mengaitkan aplikasi Microsoft Entra dengan akun Pusat Mitra Anda, mengambil ID penyewa dan ID klien untuk aplikasi, dan membuat kunci. Aplikasi Microsoft Entra mewakili aplikasi atau layanan tempat Anda ingin memanggil API Penyerapan Produk. Anda memerlukan ID penyewa, ID klien, dan kunci untuk mendapatkan token akses Microsoft Entra untuk diteruskan ke API.
Catatan
Anda hanya perlu melakukan tugas ini sekali. Setelah Anda memiliki ID penyewa, ID klien, dan kunci, Anda dapat menggunakannya kembali kapan saja Anda perlu membuat token akses Microsoft Entra baru.
- Di Pusat Mitra, kaitkan akun Pusat Mitra organisasi Anda dengan direktori Microsoft Entra organisasi Anda.
- Dari halaman Pengguna di bagian Pengaturan akun di Pusat Mitra, tambahkan aplikasi Microsoft Entra yang mewakili aplikasi atau layanan yang akan Anda gunakan untuk mengakses pengiriman untuk akun Pusat Mitra Anda. Pastikan Anda menetapkan aplikasi ini sebagai peran Manajer. Jika aplikasi belum ada di direktori Microsoft Entra Anda, buat aplikasi Microsoft Entra baru di Pusat Mitra. Pusat Mitra akan membuat dua jenis entri untuk aplikasi satu sebagai perwakilan layanan dan yang lainnya sebagai jenis aplikasi Microsoft Entra.
- Kembali ke halaman Pengguna , pilih nama aplikasi Microsoft Entra Anda untuk masuk ke pengaturan aplikasi, dan salin nilai ID Penyewa dan ID Klien.
- Pilih Tambahkan kunci baru. Pada layar berikut, salin nilai Kunci. Anda tidak akan dapat mengakses info ini lagi setelah meninggalkan halaman ini. Untuk informasi selengkapnya, lihat Mengelola kunci untuk aplikasi Microsoft Entra.
Langkah 2: Mendapatkan token akses Microsoft Entra
Untuk memanggil salah satu metode dalam API Penyerapan Produk, Anda harus terlebih dahulu mendapatkan token akses Microsoft Entra untuk meneruskan ke header Otorisasi dari setiap metode dalam API. Token akses berakhir 60 menit setelah penerbitan. Setelah itu, Anda dapat merefreshnya sehingga Anda dapat menggunakannya di panggilan mendatang ke API.
Untuk mendapatkan token akses, ikuti instruksi dalam Layanan ke Panggilan Layanan Menggunakan Info Masuk Klien untuk mengirim HTTP POST ke titik akhir https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token. Berikut adalah permintaan sampel:
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
Untuk nilai tenant_id di parameter POST Pengidentifikasi Sumber Daya Seragam dan client_id dan client_secret, tentukan ID penyewa, ID klien, dan kunci untuk aplikasi yang Anda ambil dari Pusat Mitra di bagian sebelumnya. Untuk parameter cakupan, Anda harus menentukan https://graph.microsoft.com/.default.
Konsep
Sebelum memulai, Anda perlu memahami beberapa konsep dasar.
Sumber daya
API disusun di sekitar jenis sumber daya, di mana setiap jenis dijelaskan menggunakan definisi skema khusus sebagaimana dirujuk oleh properti "$schema". Skema terdiri dari properti konfigurasi sumber daya tersebut. Sumber daya sangat mendasar dalam membuat dan memperbarui konfigurasi berbagai aspek produk tertentu. Untuk daftar lengkap jenis sumber daya dan skemanya, lihat referensi RESOURCE API.
ID tahan lama
ID tahan lama adalah pengidentifikasi global yang dihasilkan sistem yang digunakan untuk mengidentifikasi sumber daya apa pun secara unik. Setiap sumber daya memiliki properti "ID" terkait, yang ketika dikombinasikan dengan nama jenis sumber daya, membentuk ID tahan lama sumber daya. ID tahan lama digunakan saat mereferensikan sumber daya untuk mengambil atau memodifikasi.
Format:
\<resource-type>/\<id>
Contoh:
{
"$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"
}
ID Eksternal
ID eksternal adalah pengidentifikasi unik lain yang dapat digunakan untuk mereferensikan produk atau paket tertentu. Ini adalah cara alternatif untuk mereferensikan sumber daya ini alih-alih menggunakan ID tahan lama. ID eksternal produk diterjemahkan ke "offerID" dan ID eksternal paket diterjemahkan ke "planID", seperti yang didefinisikan setelah dibuat di bawah properti "identitas".
Contoh:
{
"$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",
}
Metode API
Ada empat API manajemen yang dapat digunakan untuk melakukan tindakan yang berbeda, seperti mengkueri sumber daya yang ada, membuat pembaruan konfigurasi, dan memeriksa status permintaan.
Catatan
Semua permintaan mengharuskan Anda mengatur versi skema (parameter kueri $version) yang Anda inginkan sebagai bagian dari respons.
| Tipe API | Keterangan | Metode dan jalur HTTP |
|---|---|---|
| Kueri | Mengambil sumber daya yang ada dengan: -Method 1: jenis sumber daya "resource-tree" -Method 2: durable-id -Method 3: parameter string kueri |
-Metode 1: GET resource-tree/<product-durableID>-Metode 2: GET <resource-durableID>-Metode 3: GET <resourceType>?<query parameters> |
| Mengonfigurasi kirim | Mengirimkan permintaan untuk membuat atau memperbarui satu atau beberapa sumber daya. Setelah pemrosesan berhasil, jobID dikembalikan, yang dapat digunakan untuk mengambil status permintaan. Jenis API ini dapat digunakan untuk memperbarui status draf dan menerbitkan perubahan, menyinkronkan audiens privat, dan memodifikasi status siklus hidup sumber daya. | POST configure |
| Mengonfigurasi status | Mengambil status permintaan yang tertunda melalui jobID. | GET configure/<jobID>/status |
| Mengonfigurasi detail status | Mengambil ringkasan terperinci dari permintaan yang telah selesai, termasuk sumber daya yang diperbarui, melalui jobID. | GET configure/<jobID> |
| Batalkan Konfigurasi | Membatalkan pekerjaan Konfigurasi yang ditentukan. | POST configure/<jobID>/cancel |
Alur kerja umum
Untuk memperbarui sumber daya yang ada, alur kerja umumnya adalah:
- Mengambil konfigurasi sumber daya yang ada (jenis API: Kueri melalui pohon sumber daya)*
- Buat pembaruan yang diperlukan lalu kirim permintaan konfigurasi (jenis API: Konfigurasikan kirim)
- Periksa status permintaan (jenis API: Mengonfigurasi status dan Mengonfigurasi detail status)
* Alur kerja yang sama ini dapat diterapkan saat membuat sumber daya baru, tetapi alih-alih mengambil sumber daya (Langkah 1), gunakan tabel referensi RESOURCE API untuk memastikan bahwa Anda menggunakan skema saat ini untuk jenis sumber daya yang Anda buat.
Untuk meringkas, gambar ini menunjukkan pola panggilan umum yang digunakan untuk mengirimkan permintaan konfigurasi, terlepas dari apakah Anda membuat sumber daya baru atau memodifikasi sumber daya yang ada.
Catatan
Pastikan untuk meninjau prasyarat tambahan khusus untuk jenis penawaran yang Anda kelola dengan merujuk ke bagian panduan API per jenis penawaran.
Mengambil konfigurasi sumber daya yang ada
Sebelum memperbarui sumber daya yang ada, penting untuk terlebih dahulu mengambilnya untuk memastikan bahwa Anda memiliki konfigurasi terbarunya. Ada beberapa cara untuk mengambil sumber daya melalui panggilan GET. Lihat Metode 1, yang dirinci di bawah ini, untuk mengambil semua sumber daya dalam produk tertentu dalam satu panggilan API.
Metode 1: Pohon sumber daya
Schema: https://``schema.mp.microsoft.com``/schema/resource-tree/2022-03-01-preview2
GET resource-tree/<product-durableID>?$version=<schema-version>
Anda dapat mengambil semua konfigurasi sumber daya dalam produk tertentu dengan menggunakan jenis sumber daya "pohon sumber daya" bersama dengan ID tahan lama produk.
Versi skema terbaru yang tersedia dapat berbeda untuk setiap sumber daya. Saat melakukan permintaan pohon sumber daya, versi skema yang ditentukan menentukan versi mana yang dikembalikan untuk setiap sumber daya dalam produk. Versi yang ditentukan berfungsi sebagai batas versi "maks" karena mengembalikan versi skema terbaru yang tersedia untuk semua sumber daya dengan versi yang sama atau lebih rendah. Misalnya, jika versi daftar paket terbaru yang tersedia adalah "2022-03-01-preview3", respons akan menampilkan versi ini jika Anda menentukan "2022-03-01-preview5" dalam permintaan GET pohon sumber daya. Namun, jika meminta "2022-03-01-preview2" sebagai versi pohon sumber daya, ini akan mengembalikan sumber daya daftar paket "2022-03-01-preview2" meskipun versi terbaru yang tersedia adalah "2022-03-01-preview3". Disarankan untuk menggunakan versi terbaru yang tersedia dari setiap sumber daya untuk memastikan Anda menggunakan skema yang diperbarui dengan fitur yang baru didukung.
Catatan
Jika Anda tidak tahu ID tahan lama produk, Anda dapat menggunakan ID eksternal produk untuk mengambil sumber daya produk dengan menjalankan GET product?externalID=<product-externalID>&$version=<product-schema-version>. Permintaan ini memanfaatkan parameter string kueri, yang dirinci dalam metode 3 di bawah ini. Respons akan mencakup ID tahan lama produk, yang dapat Anda gunakan untuk permintaan di masa mendatang.
Secara default, saat Anda menjalankan panggilan GET menggunakan "pohon sumber daya", Anda mendapatkan kembali versi draf sumber daya Anda. Namun, dengan meneruskan parameter kueri "targetType", Anda dapat menentukan target yang diinginkan untuk mengambil data "pratinjau" atau "langsung". Dalam contoh berikut, panggilan GET mengembalikan konfigurasi lingkungan pratinjau untuk semua sumber daya di bawah produk "12345678-abcd-efgh-1234-12345678901".
Contoh panggilan GET:
GET https://graph.microsoft.com/rp/product-ingestion/resource-tree/product/12345678-abcd-efgh-1234-12345678901?targetType="preview"&$version=2022-03-01-preview5
Respons sampel:
{
"$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.
{
...
}]
}
Metode 2: ID tahan lama
GET <resource-durableID>?$version=<schema-version>
Ambil sumber daya tertentu dengan menggunakan ID tahan lama. Setelah sumber daya dibuat, ID tahan lama selalu tetap sama dan dapat digunakan untuk mengambil perubahan draf terbaru sumber daya tersebut dengan memanggil metode GET. Misalnya, permintaan berikut akan mengembalikan konfigurasi draf produk tertentu ini menggunakan versi skema "2022-03-01-preview3".
GET product/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview3
Penting
Metode ini hanya digunakan untuk mengambil konfigurasi draf. Jika Anda ingin mengambil pratinjau atau data langsung, gunakan metode "resource-tree", seperti yang dijelaskan di atas.
Untuk menemukan ID tahan lama untuk sumber daya Anda, Anda dapat:
- Gunakan metode "pohon sumber daya" untuk mengambil semua sumber daya dalam produk bersama dengan masing-masing ID tahan lama masing-masing, atau
- Ambil detail permintaan konfigurasi sumber daya lengkap, yang mencakup ID tahan lama untuk semua sumber daya yang dibuat atau diperbarui sebagai bagian dari permintaan.
Ingat, properti "ID" adalah id tahan lama untuk sumber daya masing-masing.
Metode 3: Parameter string kueri
GET <resourceType>?<query parameters>&$version=<schema-version>
Metode ini digunakan untuk mengkueri jenis sumber daya tertentu yang terkait dengan akun tertentu. Misalnya, Anda dapat mengambil semua produk Anda dari jenis produk tertentu dengan satu panggilan GET. Parameter string kueri digunakan untuk mengkueri detail yang berkaitan dengan produk, paket, atau pengiriman Anda.
Tabel ini memperlihatkan parameter kueri yang didukung untuk setiap jenis sumber daya yang didukung. Tidak semua jenis sumber daya mendukung setiap parameter kueri. Referensikan tabel ini untuk daftar lengkap string kueri yang saat ini didukung.
| Jenis Sumber Daya | Parameter | Contoh string kueri |
|---|---|---|
| Rencana | Produk*eksternalId $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> |
| product | eksternalId jenis $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> |
| Penyerahan | targetType $maxpagesize continuationToken$version * |
GET submission/<product-durableID>?targetType=<environment>&$version=<schema-version>GET submission/<product-id>?$maxpagesize=<#>&continuationToken=<token>&$version=<schema-version> |
| pohon sumber daya | targetType$version* |
GET resource-tree/<product-durableID>?targetType=<environment>&$version=<schema-version> |
* Parameter produk dan $version selalu diperlukan.
Fungsionalitas setiap parameter kueri yang didukung:
- produk – Saat meneruskan parameter "produk" dalam konteks jenis sumber daya "rencana", ia mengembalikan semua paket dalam produk tertentu.
- externalID – Saat meneruskan parameter "externalID" dalam konteks produk atau paket, parameter mengembalikan konfigurasi produk atau paket masing-masing. Tidak seperti metode "resource-tree", parameter string kueri ini hanya akan mengembalikan detail sumber daya tersebut, tidak semua sumber daya di dalamnya.
- jenis – Saat meneruskan parameter "jenis" dalam konteks jenis sumber daya "produk", parameter mengembalikan semua produk dari jenis tersebut yang terkait dengan akun Anda. Misalnya, dengan menentukan "type=softwareAsAService", semua produk SaaS Anda akan dikembalikan.
- targetType – Ini mengembalikan data lingkungan tertentu dalam konteks jenis sumber daya yang digunakan. Nilai "targetType" yang didukung adalah "draf", "pratinjau", atau "langsung".
- $maxpagesize – Dengan menentukan ukuran halaman maksimum, dalam bentuk bilangan buletin positif, parameter ini digunakan untuk membatasi hasil pencarian Anda saat mengkueri pengiriman Anda sebelumnya.
- continuationToken – Parameter ini dapat digunakan dengan parameter "$maxpagesize" untuk mengkueri kumpulan hasil lain yang tersedia dalam pencarian Anda. Nilai "continuationToken" disediakan dalam respons halaman sebelumnya.
- $version – Ini adalah parameter yang diperlukan untuk semua panggilan, ini menentukan versi skema apa yang Anda inginkan untuk respons dari permintaan yang Anda buat. Versi skema terbaru yang tersedia dapat berbeda untuk setiap sumber daya dan versi yang ditentukan berfungsi sebagai batas versi "maks". Sistem mengembalikan versi skema yang tepat jika tersedia atau versi terdekat yang lebih lama dari versi yang diminta. Ini dapat membantu mempertahankan kode Anda berfungsi bahkan jika ada perubahan skema yang lebih baru, tetapi untuk menggunakan fitur terbaru, disarankan untuk menggunakan versi terbaru yang tersedia dari setiap skema.
Mengkueri pengiriman Anda
Anda dapat mengambil pengiriman produk yang ada dengan melakukan GET submission/<product-durableID>. Secara default, Anda mendapatkan kembali semua pengiriman aktif termasuk referensi draf, tetapi Anda juga dapat mengkueri lingkungan tertentu menggunakan parameter kueri "targetType": (GET submission/<product-durableID>?targetType=<environment>&$version=<version>).
Penting
Setelah pengiriman "Pratinjau" didorong ke "Langsung", pengiriman "Langsung" sebelumnya akan diganti. Ketika ini terjadi, data sekarang mewakili lingkungan "Pratinjau" dan "Langsung" hingga pengiriman baru diterbitkan ke "Pratinjau".
Permintaan sampel:
GET https://graph.microsoft.com/rp/product-ingestion/submission/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview2
Respons sampel:
Contoh ini menunjukkan permintaan GET untuk pengiriman aktif yang terkait dengan ID produk "12345678-abcd-efgh-1234-12345678901". Pengiriman "Langsung" aktif (pengiriman/12345678-abcd-efgh-1234-12345678901/1152921515689847470) diterbitkan untuk pratinjau terlebih dahulu dan kemudian ditayangkan. Ketika pengiriman ini didorong untuk ditayangkan pada 25 Januari 2022, itu mewakili pratinjau dan langsung hingga pengiriman pratinjau baru (pengiriman/12345678-abcd-efgh-1234-12345678901/1152921515689848683) dibuat pada 4 Februari 2022.
{
"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"
}
]
}
Membuat produk dan sumber daya baru
Anda dapat membuat sumber daya baru, termasuk produk baru, sebagai bagian dari satu permintaan konfigurasi. Dengan menggunakan tabel referensi Resource API, Anda dapat mengambil skema untuk jenis sumber daya yang ingin Anda buat. Ini memastikan bahwa Anda menggunakan skema terbaru dan karena itu mengonfigurasi semua properti yang diperlukan untuk membuat sumber daya.
Jika Anda membuat produk baru, persyaratan bervariasi menurut jenis produk. Oleh karena itu, Anda perlu menyediakan sumber daya yang berbeda. Anda dapat mereferensikan dokumentasi marketplace komersial yang sesuai untuk jenis produk masing-masing untuk memastikan bahwa Anda mengonfigurasi persyaratan dasar dalam permintaan Anda. Atau, Anda dapat membuat permintaan konfigurasi hanya menggunakan sumber daya produk. Setelah membuat produk, panggil API detail status konfigurasi untuk mengambil sumber daya produk yang dibuat dan temukan ID tahan lama untuk memanggil API Kueri pohon sumber daya. Respons mengembalikan sumber daya yang didukung yang berlaku untuk jenis produk yang Anda buat.
Demikian pula, untuk membuat sumber daya baru dalam produk yang ada, Anda juga perlu mengambil skema terbaru dari jenis sumber daya tertentu tersebut. Pastikan Anda menyediakan sumber daya dependen sebagai bagian dari permintaan konfigurasi dengan meninjau dependensi sumber daya.
Setelah membuat sumber daya Anda menggunakan skema, pelajari cara membuat permintaan konfigurasi.
Mengubah produk dan sumber daya yang ada
Anda dapat mengirimkan pembaruan dengan menggunakan payload konfigurasi. Payload ini terdiri dari satu atau beberapa jenis sumber daya dan properti "$schema" menunjukkan jenis sumber daya yang sedang dirujuk.
Tip
Kami menyarankan agar Anda terlebih dahulu mengambil sumber daya yang ada sebelum menerbitkan pembaruan untuk memastikan bahwa Anda memanfaatkan konfigurasi terbaru.
Setelah memodifikasi sumber daya Anda, pelajari cara membuat permintaan konfigurasi.
Permintaan konfigurasi
Anda dapat mengedit dan menerbitkan dalam payload yang sama. Untuk mengirimkan permintaan konfigurasi, gunakan metode HTTP POST dari API konfigurasi. Payload konfigurasi terdiri dari array sumber daya yang menunjukkan perubahan yang diinginkan. Semua pengeditan hanya memengaruhi versi draf hingga Anda secara eksplisit mengirimkan sumber daya pengiriman untuk menerbitkan perubahan draf Anda. Saat menerbitkan ke pratinjau atau langsung, sertakan sumber daya pengiriman dan tentukan lingkungan target. Sebelum mengirimkan permintaan, Anda perlu tahu cara mereferensikan sumber daya dan memahami dependensinya.
Schema:<https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2>
Setelah mengirimkan permintaan konfigurasi, Anda mendapatkan kembali objek status konfigurasi dengan jobID yang dapat Anda gunakan untuk melacak kemajuan dan hasil permintaan Anda.
Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>
Referensi dan dependensi sumber daya
Referensi
Untuk mereferensikan sumber daya yang ada dalam permintaan konfigurasi, berikan jenis "$schema" sumber daya bersama dengan ID tahan lama sumber daya. Dalam kasus produk dan paket, Anda juga dapat mereferensikan sumber daya ini melalui ID eksternal mereka.
ID tahan lama dapat ditemukan di properti "ID", misalnya jika ini adalah sumber daya produk yang ingin kami referensikan di sumber daya lain:
{
"$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"
}
ID tahan lama adalah "product/071b135e-9faf-4ff7-b113-a3f25bb0f468".
ID tahan lama kemudian dapat digunakan dalam contoh sumber daya daftar di bawah ini dengan mengaturnya di properti skema sumber daya "produk" seperti ini:
{
"$schema": "https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468", // product durable ID
...
}
ID eksternal sumber daya produk dan paket ditentukan dalam properti "identitas".
{
"$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",
...
}
ID eksternal paket "gold-annual" kemudian dapat direferensikan oleh sumber daya berikutnya lainnya dalam format berikut:
{
"$schema": "https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468"}
"plan": {"externalID": "gold-annual"}
...
}
Permintaan sampel:
Dalam contoh ini, payload konfigurasi digunakan untuk membuat produk SaaS baru dengan ID eksternal "ds-contoso-image-resize-demo". Setelah membuat produk ini, Anda nantinya dapat mereferensikan produk ini menggunakan ID tahan lama atau ID eksternalnya.
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"
}
]
}
Respons sampel:
{
"$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": []
}
Anda kemudian dapat menggunakan jobID melalui API Konfigurasi Status untuk memeriksa status permintaan Anda.
Dependensi
Sumber daya tertentu memiliki dependensi pada pembuatan sumber daya lain sebagai prasyarat. Dalam keadaan ini, kami menggunakan properti "resourceName" dalam payload yang sama untuk menunjukkan dependensi sumber daya produk dalam sumber daya paket saat kami membuat keduanya dalam permintaan yang sama.
"resourceName" hanya digunakan untuk mengidentifikasi setiap sumber daya sebagai bagian dari permintaan konfigurasi yang Anda lakukan. Nilai tidak akan menjadi bagian dari data sumber daya, tidak disimpan, juga tidak terekspos ke pelanggan. Selain itu jika ada kesalahan sebagai bagian dari permintaan konfigurasi, "resourceName" akan digunakan untuk memanggil sumber daya tempat kesalahan berada.
Permintaan sampel:
Dalam contoh ini, produk harus dibuat sebelum paket dan oleh karena itu, properti "resourceName" digunakan. Produk yang dibuat, "myNewProduct," akan menjadi nilai yang digunakan untuk "resourceName" dan direferensikan dalam sumber daya paket dependen.
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"}
...
},
}]
}
Sumber daya pengiriman
Jika menerbitkan ke "pratinjau" atau "langsung", sertakan sumber daya pengiriman dalam permintaan Anda, yang berisi:
- Properti "produk", menunjukkan produk yang diperbarui sebagaimana dirujuk oleh ID tahan lama atau ID eksternalnya
- Properti "targetType", menunjukkan lingkungan target
Saat menerbitkan untuk ditayangkan secara khusus, "ID" dari pengiriman pratinjau yang ingin Anda terbitkan:
{
"$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" }
}
Catatan
Jika Anda tidak menyertakan sumber daya pengiriman, perubahan hanya akan dilakukan pada status draf.
Menerbitkan ke pratinjau
Jenis produk komersial mendukung lingkungan pratinjau, dan setiap pembaruan harus terlebih dahulu diterbitkan untuk pratinjau sebelum ditayangkan. Anda tidak dapat menerbitkan langsung untuk ditayangkan.
Penting
Pengecualian untuk ini adalah saat membuat perubahan pada audiens privat paket Anda. Saat menyinkronkan pembaruan ke audiens privat secara khusus, perubahan ini akan disebarluaskan ke pratinjau dan ditayangkan secara bersamaan.
Ada dua cara untuk menerbitkan sumber daya anda ke lingkungan pratinjau. Jika ada perubahan yang perlu dilakukan pada pengiriman pratinjau, lakukan permintaan GET lain, buat perubahan yang diperlukan, dan dorong perubahan lagi. Anda tidak perlu terlebih dahulu melakukan siaran langsung dengan perubahan awal Anda.
Metode 1: Menerbitkan semua sumber daya draf
Jika Anda ingin menerbitkan setiap perubahan draf yang telah Anda buat, Anda dapat mengirim permintaan konfigurasi dengan sumber daya pengiriman yang menetapkan lingkungan pratinjau sebagai "targetType". Seperti yang ditunjukkan dalam contoh di bawah ini, Anda tidak perlu secara eksplisit menyediakan setiap sumber daya yang memerlukan pembaruan karena metode ini menerbitkan semua perubahan pada lingkungan target, yang dalam hal ini adalah pratinjau. Anda hanya perlu menyediakan titik akhir API konfigurasi dan sumber daya pengiriman.
Permintaan sampel:
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" }
}
]
}
Metode 2: Menerbitkan sumber daya draf tertentu (juga dikenal sebagai penerbitan modular)
Atau, jika Anda tidak siap untuk menerbitkan semua perubahan draf di berbagai sumber daya, cukup berikan sumber daya yang ingin Anda terbitkan bersama dengan sumber daya pengiriman untuk memicu penerbitan modular. Anda juga dapat menggunakan pendekatan ini untuk membuat perubahan pada sumber daya dan menerbitkannya pada saat yang sama alih-alih sebagai bagian dari pembaruan massal, seperti yang dilakukan melalui Metode 1. Untuk penerbitan modular, semua sumber daya diperlukan kecuali untuk detail tingkat produk (misalnya, daftar, ketersediaan, paket, penjual) sebagaimana berlaku untuk jenis produk Anda.
Permintaan sampel:
Dalam contoh ini, sumber daya dalam produk secara eksplisit disediakan sebagai bagian dari penerbitan modular diikuti oleh sumber daya pengiriman.
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" }
}
]
}
Penerbitan untuk ditayangkan
Setelah perubahan dalam pratinjau diuji dan diverifikasi, Anda dapat mendorong perubahan agar aktif dengan mengirim permintaan konfigurasi dengan "ID" pengiriman pratinjau Anda dan "targetType" diatur ke "langsung". Untuk menemukan "ID" pengiriman pratinjau Anda untuk dimasukkan dalam permintaan konfigurasi Anda, lihat Mengkueri pengiriman Anda.
Penting
Tidak seperti saat menerbitkan ke pratinjau, tidak ada opsi untuk melakukan penerbitan modular saat menerbitkan untuk ditayangkan. Oleh karena itu, penting untuk memastikan bahwa Anda telah memverifikasi pengiriman pratinjau sebelum melakukan siaran langsung dengan perubahan Anda.
Permintaan sampel:
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" }
}
]
}
Memeriksa status permintaan
Terlepas dari sumber daya yang disertakan dalam permintaan konfigurasi atau perubahan yang Anda buat, Anda akan mendapatkan objek status konfigurasi kembali dalam respons segera setelah mengirimkan permintaan setelah berhasil diproses. "jobID" penting karena nantinya dapat digunakan untuk memeriksa status permintaan.
Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>
Sampel respons terhadap permintaan yang dikirimkan:
{
"$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": []
}
Status permintaan yang tertunda
Anda dapat mengambil status hingga pekerjaan selesai menggunakan panggilan berikut dan memasukkan "jobID" permintaan. Objek mungkin juga berisi daftar kesalahan jika ada masalah dengan permintaan Anda.
GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>/status?$version=2022-03-01-preview2
Perlu diingat bahwa waktu untuk menyelesaikan mungkin bervariasi tergantung pada kompleksitas permintaan Anda,
Ringkasan permintaan yang telah selesai
Setelah pekerjaan permintaan konfigurasi selesai, baik berhasil atau dengan kegagalan, Anda bisa mendapatkan daftar sumber daya yang dibuat atau diperbarui menggunakan "jobID".
Catatan
Jika Anda melakukan panggilan ini sebelum pekerjaan selesai, itu akan gagal. Selain itu hanya akan mengembalikan sumber daya yang berhasil diselesaikan, atau dalam kasus pembatalan hanya yang selesai sebelum pembatalan.
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
Permintaan sampel:
Dalam contoh di bawah ini, permintaan GET digunakan untuk mengambil detail ringkasan permintaan konfigurasi yang digunakan dalam contoh sebelumnya yang membuat produk SaaS baru. Responsnya adalah objek konfigurasi detail dengan array sumber daya yang berisi sumber daya produk yang dibuat bersama dengan ID tahan lamanya.
GET https://graph.microsoft.com/rp/product-ingestion/configure/071b135e-9faf-4ff7-b113-a3f25bb0f468?$version=2022-03-01-preview2
Respons sampel:
{
"$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"
}
]
}
Membatalkan permintaan konfigurasi
Sebelum pekerjaan selesai, Anda dapat mencoba membatalkannya jika diperlukan. Untuk permintaan jangka panjang, seperti penerbitan ke "pratinjau" atau "langsung", permintaan pembatalan mungkin ditolak jika pekerjaan cukup jauh dalam sepenuhnya diproses.
Untuk membatalkan pekerjaan, lakukan panggilan POST ke titik akhir pembatalan dan berikan ID pekerjaan permintaan yang ingin Anda batalkan.
POST https://graph.microsoft.com/rp/product-ingestion/configure<jobID>/cancel?$version=2022-03-01-preview2
Permintaan sampel:
POST <https://graph.microsoft.com/rp/product-ingestion/configure/d4261631-c583-4949-a612-5150882632e9/cancel?$version=2022-03-01-preview2>
Sampel respons permintaan pembatalan yang berhasil:
{
"$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": []
}
Sampel respons jika pembatalan tidak diizinkan: HTTP Status code: 400
Konten:
{
"error": {
"code": "badRequest",
"message": "Cannot cancel job, job has already completed.",
"details": []
}
}
Penting
Perlu diingat bahwa pembatalan hanya berlaku untuk sumber daya yang belum diproses. Beberapa sumber daya mungkin telah menyelesaikan pemrosesan dan akan mencerminkan pembaruan konfigurasi terbaru, meskipun ada pembatalan permintaan.
Anda dapat mengambil ringkasan permintaan konfigurasi setelah pembatalan untuk memverifikasi sumber daya mana (jika ada) yang telah diproses sebelum pembatalan.
Menyinkronkan audiens privat
Untuk produk langsung, pembaruan untuk audiens privat di draf, pratinjau, dan lingkungan langsung dapat dilakukan secara bersamaan tanpa memerlukan penerbitan. Anda dapat menyinkronkan audiens privat menggunakan sumber daya "price-and-availability-update-private-audiences" dengan menentukan audiens mana yang ingin Anda tambahkan atau hapus dari paket tertentu. Ini akan menyinkronkan draf, pratinjau, dan lingkungan langsung untuk memiliki nilai audiens privat yang sama. Anda tidak perlu menyediakan sumber daya pengiriman saat menyinkronkan audiens privat.
Untuk mengedit draf audiens, gunakan sumber daya "harga dan paket ketersediaan" dan properti "privateAudiences". Ini harus melalui alur penerbitan reguler agar nilai diatur dalam pratinjau dan langsung.
Penting
Jenis audiens yang didukung adalah "langganan", "ea", "msdn" dan "penyewa" tetapi dukungan untuk ini bervariasi menurut jenis produk. Jika produk Anda mendukung lebih dari satu jenis pengidentifikasi untuk mengonfigurasi audiens privat (misalnya, ID penyewa dan ID langganan), Anda harus melakukan penerbitan penuh jika menyediakan jenis pengidentifikasi baru untuk pertama kalinya. Anda tidak dapat menyinkronkan audiens privat dalam kasus ini.
Contoh permintaan untuk menyinkronkan konfigurasi audiens privat:
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"
}
]
}
}
]
}
Mengonfigurasi manajemen prospek
Koneksi sistem manajemen hubungan pelanggan (CRM) Anda dengan produk marketplace komersial Anda sehingga Anda dapat menerima informasi kontak pelanggan saat pelanggan mengekspresikan minat atau menyebarkan produk Anda. Anda dapat mengubah koneksi ini kapan saja selama atau setelah pembuatan produk. Untuk mempelajari selengkapnya, lihat Mendapatkan prospek pelanggan.
Contoh permintaan untuk mengonfigurasi manajemen prospek:
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"
}
}
]
}
Status siklus hidup sumber daya
Ada berbagai tindakan yang dapat Anda ambil peta tersebut ke status siklus hidup sumber daya. Tidak semua sumber daya memiliki status siklus hidup dan tidak semua status siklus hidup didukung oleh semua sumber daya. Untuk menemukan apakah sumber daya memiliki status siklus hidup dan nilai mana yang didukung, Anda dapat memeriksa skema sumber daya untuk keberadaan properti "lifecycleState". Berbagai status siklus hidup yang didukung dirinci di bawah ini.
Dihapus
Anda dapat menghapus sumber daya tertentu dengan memperbarui properti "lifecycleState" menjadi "dihapus". Anda hanya dapat menghapus sumber daya draf yang belum diterbitkan sebelumnya. Tindakan ini tidak dapat diurungkan.
Permintaan sampel:
Dalam contoh di bawah ini, rancangan rencana "dasar" dihapus.
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"
}
]
}
Tidak digunakan lagi
Penghentian menghapus sumber daya dari marketplace komersial. Untuk menghentikannya, atur properti "lifecycleState" ke "tidak digunakan lagi" pada sumber daya yang mendukungnya. Ada berbagai tingkat penghentian. Semua jenis produk mendukung penghentian seluruh produk dan paket individual di dalamnya. Untuk memulihkan sumber daya yang tidak digunakan lagi nantinya, lihat status siklus hidup "generallyAvailable".
Contoh permintaan penghentian produk:
Dalam contoh di bawah ini, pengiriman langsung produk diatur untuk dihentikan. Setelah perubahan ini diterapkan, perubahan secara otomatis dipublikasikan untuk hidup agar berlaku.
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"
}
]
}
Saat menghentikan rencana, properti "lifecycleState" harus diubah menjadi "tidak digunakan lagi" dan perubahan kemudian harus diterbitkan ke "pratinjau" lalu "langsung" agar penghentian berlaku. Ini berbeda dari penghentian tingkat produk di mana penghentian akan secara otomatis dikonfigurasi di lingkungan langsung.
Contoh permintaan penghentian rencana:
Dalam contoh di bawah ini, paket dalam produk SaaS diatur untuk dihentikan. Ingat bahwa untuk menerapkan perubahan ini, Anda nantinya dapat menerbitkan menggunakan sumber daya pengiriman.
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"
}
]
}
Ada bentuk penghentian lain yang bervariasi tergantung pada jenis produk. Pelajari selengkapnya tentang penghentian SaaS, komputer virtual, dan kontainer.
Tersedia secara umum
generallyAvailable adalah status siklus hidup default untuk semua sumber daya. Setelah sumber daya tidak digunakan lagi, Anda dapat memulihkannya dengan mengubah properti "lifecycleState" kembali ke "generallyAvailable". Untuk memulihkan produk yang tidak digunakan lagi, Anda harus menerbitkan produk untuk dipratinjau lalu ditayangkan. Anda dapat menemukan contoh untuk SaaS, VM, dan kontainer di artikel masing-masing.
Contoh permintaan pemulihan paket:
Dalam contoh di bawah ini, rencana dimaksudkan untuk dipulihkan. Untuk menerapkan perubahan ini, Anda nantinya perlu menerbitkan semua cara untuk hidup menggunakan sumber daya pengiriman.
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"
}
]
}
Referensi API Sumber Daya
Versi skema di bawah ini hanya berlaku untuk pratinjau dan akan berubah setelah API tersedia secara umum.
Catatan
Anda dapat melihat sumber daya yang tersedia dan versinya yang ada di sini: indeks sumber daya
| Jenis Sumber Daya | Keterangan | Skema |
|---|---|---|
| azure-test-drive-technical-configuration | Detail teknis yang membantu marketplace komersial Microsoft terhubung ke solusi uji coba Anda. | https://schema.mp.microsoft.com/schema/azure-test-drive-technical-configuration/2022-03-01-preview3 |
| penyiapan marketplace komersial | Menjelaskan konfigurasi produk yang dapat ditransaksikan di pasar komersial. | https://schema.mp.microsoft.com/schema/commercial-marketplace-setup/2022-03-01-preview2 |
| prospek pelanggan | Memungkinkan menyambungkan ke sistem CRM untuk menerima prospek pelanggan. | https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3 |
| Daftar | Ini termasuk deskripsi produk Anda, yang akan ditampilkan di etalase pasar komersial Microsoft. | https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5 |
| listing-asset | Cuplikan layar dan aset pemasaran Anda yang ditautkan ke sumber daya daftar. | https://schema.mp.microsoft.com/schema/listing-asset/2022-03-01-preview5 |
| listing-trailer | Aset video yang ditautkan ke sumber daya daftar. | https://schema.mp.microsoft.com/schema/listing-trailer/2022-03-01-preview5 |
| integrasi microsoft365 | Pengaktifan Microsoft 365 dan pilihan jenis. | https://schema.mp.microsoft.com/schema/microsoft365-integration/2022-03-01-preview2 |
| Rencana | Untuk membuat paket, yang kemudian akan dirujuk oleh sumber daya tingkat paket yang Anda konfigurasi, seperti daftar paket. | https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2 |
| daftar paket | Tentukan nama dan deskripsi paket sesuai keinginan Anda untuk muncul di marketplace komersial. | https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5 |
| price-and-availability-custom-meter | Tentukan pengukur kustom yang dibagikan di seluruh paket Anda. | https://schema.mp.microsoft.com/schema/price-and-availability-custom-meter/2022-03-01-preview3 |
| penawaran harga dan ketersediaan | Tentukan audiens terbatas yang dapat meninjau produk Anda sebelum menerbitkannya secara langsung. | https://schema.mp.microsoft.com/schema/price-and-availability-offer/2022-03-01-preview3 |
| paket harga dan ketersediaan | Konfigurasikan pasar tempat paket ini tersedia, model monetisasi, harga, dan ketentuan penagihan yang diinginkan. | https://schema.mp.microsoft.com/schema/price-and-availability-plan/2022-03-01-preview4 |
| price-and-availability-update-private-audiences | Pembaruan untuk audiens privat di draf, pratinjau, dan lingkungan langsung dapat dilakukan secara bersamaan tanpa memerlukan penerbitan. | https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview3 |
| private-and-availability-private-offer-plan | Digunakan untuk mengonfigurasi detail harga absolut dari harga produk/paket yang digunakan dalam penawaran privat | https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2022-07-01 |
| penawaran privat | Mendefinisikan nama dan jenis penawaran privat, dengan syarat dan detail penawaran, bersama dengan produk/paket yang disertakan dan harganya | https://schema.mp.microsoft.com/schema/private-offer/2022-07-01 |
| product | Ini adalah sumber daya utama, mendefinisikan nama dan jenis produk, semua sumber daya mereferensikan ini. | https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3 |
| property | Tentukan kategori dan industri yang berlaku untuk penawaran, versi aplikasi, dan kontrak hukum Anda. | https://schema.mp.microsoft.com/schema/property/2022-03-01-preview5 |
| Reseller | Konfigurasikan mitra dalam program Penyedia Solusi Cloud (CSP) yang ingin Anda sediakan untuk produk Anda. | https://schema.mp.microsoft.com/schema/reseller/2022-03-01-preview2 |
| pohon sumber daya | Menjelaskan produk daftar sumber daya untuk produk tersebut dalam status saat ini untuk lingkungan target yang ditentukan. | https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2 |
| software-as-a-service-technical-configuration | Detail teknis yang membantu marketplace komersial Microsoft terhubung ke solusi Anda. | https://schema.mp.microsoft.com/schema/software-as-a-service-technical-configuration/2022-03-01-preview3 |
| Penyerahan | Dapat digunakan untuk memicu berbagai tindakan pada produk Anda dan menunjukkan status penerbitan lingkungan produk Anda yang tidak acuh (draf, pratinjau, dan langsung). | https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2 |
| Menguji | Tentukan apakah Anda ingin membiarkan pelanggan Anda mencoba produk secara gratis untuk waktu yang terbatas. | https://schema.mp.microsoft.com/schema/test-drive/2022-03-01-preview2 |
| test-drive-listing | Tentukan detail mengenai bagaimana pelanggan dapat mencoba produk Anda. | https://schema.mp.microsoft.com/schema/test-drive-listing/2022-03-01-preview3 |
| virtual-machine-plan-technical-configuration | Detail teknis yang menjelaskan komputer virtual dan lokasi gambar. | https://schema.mp.microsoft.com/schema/virtual-machine-plan-technical-configuration/2022-03-01-preview3 |
| virtual-machine-test-drive-technical-configuration | Detail teknis yang membantu marketplace komersial Microsoft terhubung ke solusi uji coba Anda. | https://schema.mp.microsoft.com/schema/virtual-machine-test-drive-technical-configuration/2022-03-01-preview2 |
| kontainer-plan-technical-configuration | Detail teknis yang menjelaskan properti gambar kontainer. | https://schema.mp.microsoft.com/schema/container-plan-technical-configuration/2022-03-01-preview3 |
Panduan API per jenis produk
API Penyerapan Produk akan tersedia untuk jenis produk lain di masa mendatang. Karena lebih banyak jenis produk didukung, lebih banyak panduan khusus untuk setiap jenis produk akan tersedia.
| Jenis produk | Sumber daya khusus jenis produk |
|---|---|
| Penawaran privat | Membuat dan mengelola penawaran privat melalui API Penyerapan Produk |
| SaaS | Membuat dan mengelola penawaran SaaS melalui API Penyerapan Produk |
| Mesin virtual | Membuat dan mengelola penawaran komputer virtual melalui API Penyerapan Produk |
| Kontainer | Membuat dan mengelola penawaran kontainer melalui API Penyerapan Produk |
Versi dan pembaruan API
| Pembaruan | Apa yang telah berubah? |
|---|---|
| 11-2023 | Semua titik akhir skema telah diperbarui dari product-ingestion.azureedge.net ke schema.mp.microsoft.com |
| 12-2022 | Skema baru versi 2022-03-01-preview3 dari API Penyerapan PC untuk prospek pelanggan sekarang tersedia yang menerima clientID dan clientSecret saat mengonfigurasi prospek pelanggan dan berhenti menangkap serverID dan menghubungi bidang email. Beralih ke versi baru dan berikan clientID dan clientSecret untuk terus mengonfigurasi konektor Marketo untuk penawaran marketplace. URL skema baru: https://``schema.mp.microsoft.com``/schema/customer-leads/2022-03-01-preview3 |
| 09-2022 | Dukungan pratinjau kontainer dirilis sebagai versi 2022-03-01-preview4 |
| 08-2022 | Dukungan pratinjau perangkat lunak sebagai layanan dirilis sebagai versi 2022-03-01-preview3 |
| 08-2022 | Rilis publik penawaran privat sebagai versi 2022-07-01 |
| 05-2022 | Dukungan pratinjau komputer virtual dirilis sebagai versi 2022-03-01-preview2 |
Langkah berikutnya
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk