API penagihan terukur marketplace
API penagihan terukur harus digunakan saat penerbit membuat dimensi pengukuran kustom agar penawaran dipublikasikan di Pusat Mitra. Integrasi dengan API penagihan terukur diperlukan untuk setiap penawaran yang dibeli yang memiliki satu atau beberapa paket dengan dimensi khusus untuk memancarkan peristiwa penggunaan.
Penting
Anda harus melacak penggunaan di kode Anda dan hanya kirimkan peristiwa penggunaan ke Microsoft untuk penggunaan yang melebihi biaya dasar.
Untuk informasi selengkapnya tentang membuat dimensi pengukuran kustom untuk SaaS, lihat Tagihan terukur SaaS.
Untuk informasi selengkapnya tentang membuat dimensi pengukuran kustom untuk penawaran Azure Application dengan paket aplikasi Terkelola, lihat Mengonfigurasi detail penyetelan penawaran aplikasi Azure Anda.
Memberlakukan TLS 1.2 Note
Versi TLS versi 1.2 akan diberlakukan segera setelah versi minimal untuk komunikasi HTTPS. Pastikan Anda menggunakan versi TLS ini di kode Anda. TLS versi 1.0 dan 1.1 ditolak dan upaya koneksi akan ditolak.
Peristiwa penggunaan tunggal penagihan terukur
API peristiwa penggunaan harus dipanggil oleh penerbit untuk memancarkan peristiwa penggunaan terhadap sumber daya aktif (berlangganan) untuk paket yang dibeli oleh pelanggan tertentu. Peristiwa penggunaan dipancarkan secara terpisah untuk setiap dimensi kustom dari paket yang ditentukan oleh penerbit saat menerbitkan penawaran.
Hanya satu peristiwa penggunaan yang dapat dipancarkan untuk setiap jam hari kalender per sumber daya dan dimensi. Jika lebih dari satu unit dikonsumsi dalam satu jam, maka akumulasi semua unit yang dikonsumsi dalam satu jam dan kemudian keluarkan dalam satu peristiwa. Peristiwa penggunaan hanya dapat dipancarkan selama 24 jam terakhir. Jika Anda memancarkan peristiwa penggunaan kapan saja antara pukul 08.00 dan 08.59:59 (dan diterima) dan mengirimkan peristiwa tambahan untuk hari yang sama antara pukul 08.00 dan 08.59.59, maka akan ditolak sebagai duplikat.
POST:https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>
Parameter kueri:
| Parameter | Rekomendasi |
|---|---|
ApiVersion |
Gunakan 2018-08-31. |
Header permintaan:
| Jenis-konten | Menggunakan application/json |
|---|---|
x-ms-requestid |
Nilai string unik untuk melacak permintaan dari klien, sebaiknya berupa GUID. Jika nilai ini tidak disediakan, nilai akan dihasilkan dan disediakan di header respons. |
x-ms-correlationid |
Nilai string unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai akan dihasilkan 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 untuk
|
Contoh isi permintaan:
{
"resourceId": <guid>, // unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
}
Untuk paket Azure Application Managed Apps, resourceId aplikasi tersebut adalah Aplikasi Terkelola resource group Id. Contoh skrip untuk mengambilnya dapat ditemukan dalam menggunakan token identitas yang dikelola Azure.
Untuk penawaran SaaS, resourceId adalah ID langganan SaaS. Untuk detail selengkapnya tentang langganan SaaS, lihat daftar langganan.
Respons
Kode: 200
OK. Emisi penggunaan diterima dan direkam di sisi Microsoft untuk pemrosesan dan penagihan lebih lanjut.
Contoh payload respons:
{
"usageEventId": <guid>, // unique identifier associated with the usage event in Microsoft records
"status": "Accepted" // this is the only value in case of single usage event
"messageTime": "2020-01-12T13:19:35.3458658Z", // time in UTC this event was accepted
"resourceId": <guid>, // unique identifier of the resource against which usage is emitted. For SaaS it's the subscriptionId.
"quantity": 5.0, // amount of emitted units as recorded by Microsoft
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, as sent by the ISV
"planId": "plan1", // id of the plan purchased for the offer
}
Kode: 400
Permintaan buruk.
- Data permintaan yang hilang atau tidak valid disediakan.
effectiveStartTimelebih dari 24 jam di masa lalu. Peristiwa telah kedaluwarsa.- Langganan SaaS tidak dalam status Berlangganan.
Contoh payload respons:
{
"message": "One or more errors have occurred.",
"target": "usageEventRequest",
"details": [
{
"message": "The resourceId is required.",
"target": "ResourceId",
"code": "BadArgument"
}
],
"code": "BadArgument"
}
Kode: 403
Terlarang. Token otorisasi tidak tersedia, tidak valid, atau kedaluwarsa. Atau permintaan mencoba mengakses langganan untuk penawaran yang diterbitkan dengan ID Aplikasi Microsoft Entra yang berbeda dari yang digunakan untuk membuat token otorisasi.
Kode: 409
Konflik. Peristiwa penggunaan telah berhasil dilaporkan untuk ID sumber daya, tanggal dan jam penggunaan efektif yang ditentukan.
Contoh payload respons:
{
"additionalInfo": {
"acceptedMessage": {
"usageEventId": "<guid>", //unique identifier associated with the usage event in Microsoft records
"status": "Duplicate",
"messageTime": "2020-01-12T13:19:35.3458658Z",
"resourceId": "<guid>", //unique identifier of the resource against which usage is emitted.
"quantity": 1.0,
"dimension": "dim1",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "plan1"
}
},
"message": "This usage event already exist.",
"code": "Conflict"
}
Peristiwa penggunaan batch penagihan terukur
API peristiwa penggunaan batch memungkinkan Anda untuk memancarkan peristiwa penggunaan untuk lebih dari satu sumber daya yang dibeli sekaligus. Ini juga memungkinkan Anda untuk memancarkan beberapa peristiwa penggunaan untuk sumber daya yang sama selama mereka untuk jam kalender yang berbeda. Jumlah maksimal peristiwa dalam satu batch adalah 25.
POSTING:https://marketplaceapi.microsoft.com/api/batchUsageEvent?api-version=<ApiVersion>
Parameter kueri:
| Parameter | Rekomendasi |
|---|---|
ApiVersion |
Gunakan 2018-08-31. |
Header permintaan:
| Jenis-konten | Menggunakan application/json |
|---|---|
x-ms-requestid |
Nilai string unik untuk melacak permintaan dari klien, sebaiknya berupa GUID. Jika nilai ini tidak disediakan, nilai akan dihasilkan dan disediakan di header respons. |
x-ms-correlationid |
Nilai string unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai akan dihasilkan 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 untuk
|
Catatan
Di badan permintaan, pengenal sumber daya memiliki arti yang berbeda untuk aplikasi SaaS dan untuk aplikasi Azure Managed yang memancarkan meter kustom. Pengidentifikasi sumber daya untuk Aplikasi SaaS adalah resourceID. Paket pengidentifikasi sumber daya untuk Azure Application Managed Apps adalah resourceUri. Untuk informasi selengkapnya tentang pengidentifikasi sumber daya, lihat Marketplace Azure Penagihan Terukur- Memilih ID yang benar saat mengirimkan peristiwa penggunaan.
Untuk penawaran SaaS, resourceId adalah ID langganan SaaS. Untuk detail selengkapnya tentang langganan SaaS, lihat daftar langganan.
Contoh badan permintaan untuk aplikasi SaaS:
{
"request": [ // list of usage events for the same or different resources of the publisher
{ // first event
"resourceId": "<guid1>", // Unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", //Custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
},
{ // next event
"resourceId": "<guid2>",
"quantity": 39.0,
"dimension": "email",
"effectiveStartTime": "2018-11-01T23:33:10
"planId": "gold", // id of the plan purchased for the offer
}
]
}
Untuk paket Azure Application Managed Apps, resourceUri adalah Aplikasi resourceUsageIdTerkelola . Contoh skrip untuk mengambilnya dapat ditemukan dalam menggunakan token identitas yang dikelola Azure.
Contoh badan permintaan untuk aplikasi terkelola Aplikasi Azure:
{
"request": [ // list of usage events for the same or different resources of the publisher
{ // first event
"resourceUri": "<fullyqualifiedname>", // Unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", //Custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
}
]
}
Respons
Kode: 200
OK. Emisi penggunaan diterima dan direkam di sisi Microsoft untuk pemrosesan dan penagihan lebih lanjut. Daftar respons dikembalikan dengan status untuk setiap peristiwa individual dalam batch. Anda harus melakukan iterasi melalui muatan respons untuk memahami respons untuk setiap peristiwa penggunaan individu yang dikirim sebagai bagian dari peristiwa batch.
Contoh payload respons:
{
"count": 2, // number of records in the response
"result": [
{ // first response
"usageEventId": "<guid>", // unique identifier associated with the usage event in Microsoft records
"status": "Accepted" // see list of possible statuses below,
"messageTime": "2020-01-12T13:19:35.3458658Z", // Time in UTC this event was accepted by Microsoft,
"resourceId": "<guid1>", // unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // amount of emitted units as recorded by Microsoft
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",// time in UTC when the usage event occurred, as sent by the ISV
"planId": "plan1", // id of the plan purchased for the offer
},
{ // second response
"status": "Duplicate",
"messageTime": "0001-01-01T00:00:00",
"error": {
"additionalInfo": {
"acceptedMessage": {
"usageEventId": "<guid>",
"status": "Duplicate",
"messageTime": "2020-01-12T13:19:35.3458658Z",
"resourceId": "<guid2>",
"quantity": 1.0,
"dimension": "email",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "gold"
}
},
"message": "This usage event already exist.",
"code": "Conflict"
},
"resourceId": "<guid2>",
"quantity": 1.0,
"dimension": "email",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "gold"
}
]
}
Deskripsi kode status yang direferensikan dalam respons API BatchUsageEvent:
| Kode status | Deskripsi |
|---|---|
Accepted |
Diterima. |
Expired |
Penggunaan kedaluwarsa. |
Duplicate |
Penggunaan duplikat disediakan. |
Error |
Kode Kesalahan. |
ResourceNotFound |
Sumber daya penggunaan yang disediakan tidak valid. |
ResourceNotAuthorized |
Anda tidak berwenang untuk menyediakan penggunaan untuk sumber daya ini. |
ResourceNotActive |
Sumber daya ditangguhkan atau tidak pernah diaktifkan. |
InvalidDimension |
Dimensi di mana penggunaan diteruskan tidak valid untuk penawaran/paket ini. |
InvalidQuantity |
Kuantitas yang dilewati lebih rendah atau sama dengan 0. |
BadArgument |
Input hilang atau cacat. |
Kode: 400
Permintaan buruk. Batch berisi lebih dari 25 peristiwa penggunaan.
Kode: 403
Terlarang. Token otorisasi tidak tersedia, tidak valid, atau kedaluwarsa. Atau permintaan mencoba mengakses langganan untuk penawaran yang diterbitkan dengan ID Aplikasi Microsoft Entra yang berbeda dari yang digunakan untuk membuat token otorisasi.
Penagihan terukur mengambil peristiwa penggunaan
Anda dapat memanggil API peristiwa penggunaan untuk mendapatkan daftar peristiwa penggunaan. ISV dapat menggunakan API ini untuk melihat peristiwa penggunaan yang telah diposting selama durasi waktu tertentu yang dapat dikonfigurasi dan status peristiwa ini pada saat memanggil API.
MENDAPATKAN: https://marketplaceapi.microsoft.com/api/usageEvents
Parameter kueri:
| Parameter | Rekomendasi |
|---|---|
| ApiVersion | Gunakan 2018-08-31. |
| usageStartDate | DateTime dalam format ISO8601. Misalnya, 2020-12-03T15:00 atau 2020-12-03 |
| UsageEndDate (opsional) | DateTime dalam format ISO8601. Default = tanggal saat ini |
| offerId (opsional) | Default = semua tersedia |
| planId (opsional) | Default = semua tersedia |
| dimensi (opsional) | Default = semua tersedia |
| azureSubscriptionId (opsional) | Default = semua tersedia |
| reconStatus (opsional) | Default = semua tersedia |
Kemungkinan nilai reconStatus:
| ReconStatus | Deskripsi |
|---|---|
| Dikirim | Belum diproses oleh PC Analytics |
| Diterima | Dicocokkan dengan ANalitik PC |
| Ditolak | Ditolak dalam alur. Hubungi dukungan Microsoft untuk menyelidiki penyebabnya. |
| Tidak cocok | Jumlah MarketplaceAPI dan Analitik Pusat Mitra keduanya bukan nol, namun tidak cocok |
Header permintaan:
| Jenis konten | Menggunakan aplikasi/json |
|---|---|
| x-ms-requestid | Nilai string unik (sebaiknya GUID), untuk melacak permintaan dari klien. Jika nilai ini tidak disediakan, nilai akan dihasilkan dan disediakan di header respons. |
| x-ms-correlationid | Nilai string unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai akan dihasilkan 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. Untuk informasi selengkapnya, lihat:
|
Respons
Contoh payload respons:
Diterima*
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "Silver",
"offerId": "mycooloffer",
"offerName": "My Cool Offer",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Accepted",
"submittedQuantity": 17.0,
"processedQuantity": 17.0,
"submittedCount": 17
}
]
Dikirimkan
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "",
"offerId": "mycooloffer",
"offerName": "",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Submitted",
"submittedQuantity": 17.0,
"processedQuantity": 0.0,
"submittedCount": 17
}
]
Ketidakcocokan
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "Silver",
"offerId": "mycooloffer",
"offerName": "My Cool Offer",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Mismatch",
"submittedQuantity": 17.0,
"processedQuantity": 16.0,
"submittedCount": 17
}
]
Ditolak
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "",
"offerId": "mycooloffer",
"offerName": "",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Rejected",
"submittedQuantity": 17.0,
"processedQuantity": 0.0,
"submittedCount": 17
}
]
Kode status
Kode: 403 Terlarang. Token otorisasi tidak tersedia, tidak valid, atau kedaluwarsa. Atau permintaan mencoba mengakses langganan untuk penawaran yang diterbitkan dengan ID Aplikasi Microsoft Entra yang berbeda dari yang digunakan untuk membuat token otorisasi.
Pengembangan dan pengujian praktik terbaik
Untuk menguji emisi pengukuran kustom, terapkan integrasi dengan API pengukuran, buat rencana untuk penawaran SaaS yang Anda terbitkan dengan dimensi khusus yang ditentukan di dalamnya dengan harga nol per unit. Dan publikasikan penawaran ini sebagai pratinjau sehingga hanya pengguna terbatas yang dapat mengakses dan menguji integrasi.
Anda juga dapat menggunakan paket privat untuk penawaran langsung yang ada untuk membatasi akses ke paket ini selama pengujian ke audiens terbatas.
Mendapatkan dukungan
Ikuti instruksi dalam Dukungan untuk program marketplace komersial di Pusat Mitra untuk memahami opsi dukungan penayang dan membuka tiket dukungan dengan Microsoft.
Langkah berikutnya
Untuk informasi selengkapnya tentang API layanan pengukuran, lihat FAQ API layanan pengukuran Marketplace.
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