API Operasi pemenuhan SaaS v2 di pasar komersial Microsoft

Artikel ini menjelaskan versi 2 dari API operasi pemenuhan SaaS.

Operasi berguna untuk menanggapi permintaan apa pun yang datang melalui webhook sebagai bagian dari tindakan ChangePlan, ChangeQuantity, dan Reinstate. Ini memberikan kesempatan untuk menerima atau menolak permintaan dengan menambal operasi webhook tersebut dengan Keberhasilan atau Kegagalan dengan menggunakan API di bawah ini.

Ini hanya berlaku untuk peristiwa webhook seperti ChangePlan, ChangeQuantity, dan Reinstate yang memerlukan ACK. Tidak ada tindakan yang diperlukan dari vendor perangkat lunak independen (ISV) pada peristiwa Perpanjang, Tangguhkan, dan Berhenti berlangganan karena peristiwa tersebut hanya memberi tahu.

Daftar operasi yang tersisa

Dapatkan daftar operasi yang tertunda untuk langganan SaaS yang ditentukan. Penerbit harus mengakui operasi yang dikembalikan dengan memanggil Operation Patch API.

Dapatkanhttps://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?api-version=<ApiVersion>

Parameter kueri:

Parameter	Nilai
ApiVersion	Gunakan 2018-08-31.
subscriptionId	Pengidentifikasi unik dari langganan SaaS yang dibeli. ID ini diperoleh setelah menyelesaikan token otorisasi pasar komersial dengan menggunakan Resolve API.

Header permintaan:

Parameter	Nilai
content-type	application/json
x-ms-requestid	Nilai karakter unik untuk melacak permintaan dari klien, sebaiknya GUID. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
x-ms-correlationid	Nilai karakter unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
authorization	Formatnya adalah "Bearer <access_token>" ketika nilai token diambil oleh penerbit seperti yang dijelaskan dalam Mendapatkan token berdasarkan aplikasi Microsoft Entra.

Kode respons:

Kode: 200 Menghasiilkan operasi Pemulihan tertunda pada langganan SaaS yang ditentukan.

Respons contoh payload:

{
  "operations": [
    {
      "id": "<guid>", //Operation ID, should be provided in the operations patch API call
      "activityId": "<guid>", //not relevant
      "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription that is being reinstated
      "offerId": "offer1", // purchased offer ID
      "publisherId": "contoso",
      "planId": "silver", // purchased plan ID
      "quantity": 20, // purchased amount of seats, will be empty is not relevant
      "action": "Reinstate",
      "timeStamp": "2018-12-01T00:00:00", // UTC
      "status": "InProgress" // the only status that can be returned in this case
    }
  ]
}

Mengembalikan json kosong jika tidak ada operasi pemulihan yang tertunda.

Kode: 400 Permintaan buruk: validasi gagal.

Kode: 403 Terlarang. Token otorisasi tidak valid, kadaluwarsa, atau tidak disediakan. Permintaan ini mencoba mengakses langganan SaaS untuk penawaran yang diterbitkan dengan ID aplikasi Microsoft Entra yang berbeda dari yang digunakan untuk membuat token otorisasi.

Kesalahan ini sering merupakan gejala tidak melakukan pendaftaranSaaS denganbenar.

Kode: 404 Tidak ditemukan. Langganan SaaS dengan subscriptionId tidak ditemukan.

Kode: 500 Kesalahan server internal. Coba lagi panggilan API. Jika masalah berlanjut, hubungidukungan Microsoft.

Dapatkan status operasi

API ini membuat penerbit dapat melacak status operasi tidak sinkron yang ditentukan:Berhenti berlangganan,UbahPaket,atauUbahJumlah.

UntukoperationId panggilan API ini dapat diambil dari nilai yang dikembalikan oleh Operation-Location, dapatkan panggilan Operations API yang tertunda, atau<id>nilai parameter yang diterima dalam panggilan webhook.

Dapatkanhttps://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>

Parameter kueri:

Parameter	Nilai
ApiVersion	Gunakan 2018-08-31.
subscriptionId	Pengidentifikasi unik dari langganan SaaS yang dibeli. ID ini diperoleh setelah menyelesaikan token otorisasi pasar komersial dengan menggunakan Resolve API.
operationId	Pengidentifikasi unik operasi yang diambil.

Header permintaan:

Parameter	Nilai
content-type	application/json
x-ms-requestid	Nilai karakter unik untuk melacak permintaan dari klien, sebaiknya GUID. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
x-ms-correlationid	Nilai karakter unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
authorization	Token akses unik yang mengidentifikasi penerbit melakukan panggilan API ini. Formatnya adalah "Bearer <access_token>" ketika nilai token diambil oleh penerbit seperti yang dijelaskan dalam Mendapatkan token berdasarkan aplikasi Microsoft Entra.

Kode respons:

Kode: 200 Mendapatkan detail operasi SaaS yang ditentukan.

Respons contoh payload:

Response body:
{
  "id  ": "<guid>", //Operation ID, should be provided in the patch operation API call
  "activityId": "<guid>", //not relevant
  "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription for which this operation is relevant
  "offerId": "offer1", // purchased offer ID
  "publisherId": "contoso",
  "planId": "silver", // purchased plan ID
  "quantity": 20, // purchased amount of seats
  "action": "ChangePlan", // Can be ChangePlan, ChangeQuantity or Reinstate
  "timeStamp": "2018-12-01T00:00:00", // UTC
  "status": "InProgress", // Possible values: NotStarted, InProgress, Failed, Succeeded, Conflict (new quantity / plan is the same as existing)
  "errorStatusCode": "",
  "errorMessage": ""
}

Kode: 403 Terlarang. Token otorisasi tidak valid, kadaluwarsa, atau tidak disediakan. Permintaan ini mencoba mengakses langganan SaaS untuk penawaran yang diterbitkan dengan ID aplikasi Microsoft Entra yang berbeda dari yang digunakan untuk membuat token otorisasi.

Kesalahan ini sering merupakan gejala tidak melakukan pendaftaranSaaS denganbenar.

Kode: 404 Tidak ditemukan.

• Langganan dengan subscriptionId tidak ditemukan.
• Operasi dengan operationId tidak ditemukan.

Kode: 500 Kesalahan server internal. Coba lagi panggilan API. Jika masalah berlanjut, hubungidukungan Microsoft.

Perbarui status operasi

Gunakan API ini untuk memperbarui status operasi yang tertunda untuk menunjukkan keberhasilan atau kegagalan operasi yang dilakukan penerbit.

UntukoperationId panggilan API ini dapat diambil dari nilai yang dikembalikan oleh Operation-Location, dapatkan panggilan Operations API yang tertunda, atau<id>nilai parameter yang diterima dalam panggilan webhook.

Tambalhttps://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>

Parameter kueri:

Parameter	Nilai
ApiVersion	Gunakan 2018-08-31.
subscriptionId	Pengidentifikasi unik dari langganan SaaS yang dibeli. ID ini diperoleh setelah menyelesaikan token otorisasi pasar komersial dengan menggunakan Resolve API.
operationId	Pengidentifikasi unik operasi yang sedang diselesaikan.

Header permintaan:

Parameter	Nilai
content-type	application/json
x-ms-requestid	Nilai karakter unik untuk melacak permintaan dari klien, sebaiknya GUID. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
x-ms-correlationid	Nilai karakter unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
authorization	Token akses unik yang mengidentifikasi penerbit melakukan panggilan API ini. Formatnya adalah "Bearer <access_token>" ketika nilai token diambil oleh penerbit seperti yang dijelaskan dalam Mendapatkan token berdasarkan aplikasi Microsoft Entra.

Minta contoh payload:

{
  "status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}

Kode respons:

Kode: 200 Panggilan untuk menginformasikan penyelesaian operasi yang dilakukan mitra. Misalnya, respons ini dapat menandakan penyelesaian perubahan seat atau paket oleh penerbit.

Kode: 403

• Terlarang. Token otorisasi tidak tersedia, tidak valid, atau kedaluwarsa. Permintaan mungkin mencoba mengakses langganan yang bukan milik penerbit saat ini.
• Terlarang. Token otorisasi tidak valid, kadaluwarsa, atau tidak disediakan. Permintaan ini mencoba mengakses langganan SaaS untuk penawaran yang diterbitkan dengan ID aplikasi Microsoft Entra yang berbeda dari yang digunakan untuk membuat token otorisasi.

Kesalahan ini sering merupakan gejala tidak melakukan pendaftaranSaaS denganbenar.

Kode: 404 Tidak ditemukan.

• Langganan dengan subscriptionId tidak ditemukan.
• Operasi dengan operationId tidak ditemukan.

Kode: 409 Konflik. Misalnya, pembaruan yang lebih baru telah terpenuhi.

Kode: 500 Kesalahan server internal. Coba lagi panggilan API. Jika masalah berlanjut, hubungidukungan Microsoft.

Langkah berikutnya

• Lihat API layanan pengukuran pasar komersial untuk pilihan lebih lanjut untuk penawaran SaaS di pasar komersial.
• Tinjau dan gunakan klien untuk bahasa pemrogram dan sampel yang berbeda.