Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
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 Depresiasi modul Powershell.
Mulai Sekarang
API Penyerapan Produk dapat diakses menggunakan API MSGraph di bawah 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:
Sebuah Microsoft Entra ID
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. 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 Partner Center tanpa biaya.
- 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 Anda gunakan ketika memanggil 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 Pusat Mitra, tambahkan aplikasi Microsoft Entra yang mewakili aplikasi atau layanan yang Anda gunakan untuk mengakses pengajuan 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. Partner Center membuat dua jenis entri untuk aplikasi, satu sebagai induk 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 contoh permintaan:
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 POST URI dan parameter 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
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 merujuk sumber daya untuk pengambilan atau modifikasi.
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 sebuah produk diterjemahkan menjadi "offerID" dan ID eksternal sebuah paket diterjemahkan menjadi "planID," seperti yang didefinisikan saat 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: -Metode 1: tipe sumber daya "resource-tree" -Metode 2: identifikasi tahan lama -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 lain khusus untuk jenis penawaran yang Anda kelola per jenis penawaran dengan merujuk ke panduan API di bagian.
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 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 "resource-tree" bersama dengan durable ID 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 rencana terbaru yang tersedia adalah "2022-03-01-preview3," respons akan menampilkan versi ini jika Anda memasukkan "2022-03-01-preview5" pada permintaan GET sumber daya. Namun, jika meminta "2022-03-01-preview2" sebagai versi pohon sumber daya, ini 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 mengetahui ID tetap produk, Anda dapat menggunakan ID eksternal produk
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 yang stabil. 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 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 "pohon sumber daya", seperti yang dijelaskan sebelumnya.
Untuk menemukan ID permanen untuk sumber daya Anda, Anda dapat:
- Gunakan metode "pohon sumber daya" untuk mengambil semua sumber daya dalam produk bersama dengan ID stabil mereka, atau
- Ambil rincian permintaan konfigurasi sumber daya yang sudah selesai, yang mencakup ID unik dan tahan lama untuk semua sumber daya yang dibuat atau diperbarui sebagai bagian dari permintaan tersebut.
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*ID Eksternal $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> |
| hasil | ID Eksternal 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 "plan", akan mengembalikan semua rencana dalam produk tertentu.
- externalID – Saat meneruskan parameter "externalID" dalam konteks produk atau paket, parameter mengembalikan konfigurasi produk atau paket masing-masing. Tidak seperti metode "pohon sumber daya", parameter string kueri ini hanya 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 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 bulat positif, parameter ini digunakan untuk membatasi hasil pencarian Anda saat melakukan pencarian penyerahan 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.
Memeriksa pengajuan 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 "Live," itu menggantikan pengiriman "Live" sebelumnya. Ketika ini terjadi, data sekarang mewakili lingkungan "Pratinjau" dan "Live" 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 pengajuan aktif yang terkait dengan ID produk "12345678-abcd-efgh-1234-12345678901." Pengajuan aktif "Live" ( pengajuan/12345678-abcd-efgh-1234-12345678901/1152921515689847470) diterbitkan untuk pratinjau terlebih dahulu, kemudian ditayangkan. Ketika pengiriman ini dipublikasikan pada 25 Januari 2022, itu mewakili baik pratinjau maupun siaran 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 konfigurasi status detail untuk mengambil sumber daya produk yang sudah dibuat dan temukan ID persisten untuk memanggil API Kueri resource-tree. 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 mengajukan pembaruan dengan menggunakan mengonfigurasi payload. Payload ini terdiri dari satu atau beberapa jenis sumber daya dan properti "$schema" menunjukkan jenis sumber daya yang sedang dirujuk.
Petunjuk
Kami menyarankan agar Anda terlebih dahulu mengambil sumber daya yang ada sebelum menerbitkan pembaruan untuk memastikan bahwa Anda menggunakan 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. Konfigurasi payload terdiri dari array sumber daya yang menunjukkan perubahan yang diinginkan. Semua pengeditan hanya memengaruhi versi draf hingga Anda secara eksplisit mengirimkan sumber daya pengajuan 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. Untuk 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 permanen adalah "produk/071b135e-9faf-4ff7-b113-a3f25bb0f468."
ID tahan lama kemudian dapat digunakan pada sumber daya daftar dalam contoh berikut dengan menetapkan ID tersebut pada 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 rencana 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 dirujuk oleh sumber daya lain 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 situasi ini, kami menggunakan properti "resourceName" dalam payload yang sama untuk menunjukkan ketergantungan sumber daya produk pada sumber daya rencana saat kami membuat keduanya dalam permintaan yang sama.
"resourceName" hanya digunakan untuk mengidentifikasi setiap sumber daya sebagai bagian dari permintaan konfigurasi yang Anda lakukan. Nilainya bukan bagian dari data sumber daya, tidak disimpan, juga tidak diekspos ke pelanggan. Selain itu jika ada kesalahan sebagai bagian dari permintaan konfigurasi, "resourceName" digunakan untuk memanggil sumber daya tempat kesalahan berada.
Permintaan sampel:
Dalam contoh ini, produk harus dibuat sebelum rencana dan oleh karena itu, properti "resourceName" digunakan. Produk yang dibuat, "myNewProduct," merupakan nilai yang digunakan untuk "resourceName" dan dirujuk di dalam sumber daya rencana yang menjadi acuan.
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 Anda menerbitkan ke "pratinjau" atau "siaran langsung", sertakan sumber pengiriman dalam permintaan Anda, yang mencakup:
- Properti "produk", menunjukkan produk yang diperbarui sebagaimana dirujuk oleh ID tahan lama atau ID eksternalnya
- Properti "targetType" yang 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 dilakukan pada status draf.
Publikasi 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 pribadi rencana Anda. Saat menyinkronkan pembaruan kepada audiens privat secara khusus, perubahan ini menyebar secara bersamaan ke pratinjau dan tampilan langsung.
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 langsung menerapkan perubahan awal Anda.
Metode 1: Menerbitkan semua sumber daya draf
Jika Anda ingin menerbitkan setiap perubahan draf yang Anda buat, Anda dapat mengirim permintaan konfigurasi dengan sumber daya pengiriman yang menetapkan lingkungan pratinjau sebagai "targetType." Seperti yang ditunjukkan dalam contoh berikut, 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 sediakan sumber daya yang ingin Anda terbitkan bersama dengan sumber daya pengiriman untuk memicu penerbitan secara bertahap. 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" }
}
]
}
Publikasi Langsung
Setelah perubahan dalam pratinjau selesai diuji dan diverifikasi, Anda dapat mendorong perubahan tersebut menjadi live dengan mengirim permintaan konfigurasi menggunakan "ID" dari pengiriman pratinjau Anda dan "targetType" yang diatur menjadi "live". Untuk menemukan "ID" dari pengiriman pratinjau Anda yang perlu dimasukkan dalam permintaan konfigurasi Anda, lihat bagian "Menelusuri pengiriman Anda" .
Penting
Tidak seperti saat menerbitkan ke pratinjau, tidak ada opsi untuk melakukan penerbitan modular saat menerbitkan ke live. Oleh karena itu, penting untuk memastikan bahwa Anda telah memverifikasi pengiriman pratinjau sebelum mengimplementasikan 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 sampai pekerjaan selesai dengan menggunakan panggilan di bawah ini 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 menggunakanjobID
Catatan
Jika Anda melakukan panggilan ini sebelum pekerjaan selesai, maka akan gagal. Selain itu hanya mengembalikan sumber daya yang berhasil diselesaikan, atau dalam kasus pembatalan hanya yang diselesaikan 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 berikut, 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 "tayang", permintaan pembatalan mungkin ditolak jika pekerjaan sudah cukup jauh dalam proses penyelesaian.
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 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 pribadi
Untuk produk yang sudah live, pembaruan untuk audiens privat dalam lingkungan draf, pratinjau, dan live dapat dilakukan secara bersamaan tanpa memerlukan untuk dipublikasikan. 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 menyinkronkan draf, pratinjau, dan lingkungan live 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 perlu melalui alur penerbitan reguler agar nilai dapat diatur dalam pratinjau dan langsung ditayangkan.
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
Hubungkan 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 nanti.
Dihapus
Anda dapat menghapus sumber daya tertentu dengan memperbarui properti "lifecycleState" ke "dihapus." Anda hanya dapat menghapus sumber daya draf yang belum diterbitkan sebelumnya. Tindakan ini tidak dapat diurungkan.
Permintaan sampel:
Dalam contoh berikut, rencana draf "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 penggunaan menghapus sumber daya dari pasar komersial. Untuk menghentikannya, atur properti "lifecycleState" ke "tidak digunakan lagi" pada sumber daya yang mendukungnya. Ada berbagai tingkat pengurangan penggunaan. Semua jenis-jenis produk mendukung penghentian seluruh produk dan rencana individu di dalamnya. Untuk memulihkan sumber daya yang tidak digunakan lagi nantinya, lihat status siklus hidup "generallyAvailable".
Contoh permintaan penghentian produk:
Dalam contoh berikut, pengiriman langsung produk diatur untuk dihentikan. Setelah perubahan ini diterapkan, perubahan tersebut secara otomatis dipublikasikan secara langsung untuk mulai 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 pada tingkat produk di mana penghentian secara otomatis dikonfigurasi di lingkungan langsung.
Contoh permintaan penonaktifan rencana:
Dalam contoh berikut, rencana dalam produk SaaS dijadwalkan untuk dihentikan. Ingat bahwa untuk menerapkan perubahan ini, Anda dapat menerbitkannya nanti menggunakan sumber daya pengajuan.
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 rencana paket:
Dalam contoh berikut, rencana dimaksudkan untuk dikembalikan ke kondisi semula. 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 berikut hanya berlaku untuk pratinjau dan perubahan 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 |
|---|---|---|
| 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 ditampilkan di etalase marketplace komersial Microsoft. | https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5 |
| aset-daftar | Tangkapan layar dan aset pemasaran Anda yang ditautkan dengan sumber daya penempatan. | https://schema.mp.microsoft.com/schema/listing-asset/2022-03-01-preview5 |
| cuplikan daftar | Aset video yang ditautkan ke sumber daya pencantuman. | 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 rencana, yang kemudian dirujuk oleh sumber daya tingkat rencana yang Anda konfigurasi, seperti daftar rencana. | https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2 |
| daftar rencana | 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 |
| meter-khusus-harga-dan-ketersediaan | Tentukan meteran kustom yang digunakan 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 |
| pembaruan-harga-dan-ketersediaan-audiens-pribadi | Pembaruan untuk audiens khusus di lingkungan draf, pratinjau, dan langsung dapat dilakukan secara bersamaan tanpa perlu dipublikasikan. | https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview3 |
| penawaran-pribadi-dan-ketersediaan-rencana-penawaran-pribadi | 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 |
| hasil | 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 |
| harta benda | 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 |
| konfigurasi teknis perangkat lunak-sebagai-layanan | 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 produk Anda dalam berbagai lingkungan (draf, pratinjau, dan langsung). | https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2 |
| 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 |
| 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 tersedia untuk jenis produk lain di masa mendatang. Karena lebih banyak jenis produk yang didukung, lebih banyak panduan khusus untuk setiap jenis produk 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 Pengambilan PC untuk prospek pelanggan sekarang tersedia. Skema ini menerima clientID dan clientSecret saat mengonfigurasi prospek pelanggan dan menghentikan pengambilan bidang serverID dan email kontak. 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 versi 2022-07-01 |
| 05-2022 | Dukungan pratinjau komputer virtual dirilis sebagai versi 2022-03-01-preview2 |